PyLV200 0.1.1__py3-none-any.whl

pylv200/cli.py

@@ -0,0 +1,2073 @@
+#!/usr/bin/env python3
+"""Command line for pylv200 - pull a cellSens experiment that is still running.
+
+cellSens does not finalise its image container until a run ends, so a nine-day
+recording is unreadable for nine days. The pixels are already on disk though, as
+`.ets` tile files, and this reads them where they lie.
+
+    pylv200 list left-lv200
+    pylv200 plan left-lv200:ois351A --last-n 24
+    pylv200 sync left-lv200:ois351A -o D:/pulled
+    pylv200 --json list left-lv200
+
+Strictly read-only on the microscope: files are opened for reading and nothing
+is written, renamed or locked inside an experiment folder. Safe to run
+mid-acquisition.
+
+The `.ets` layout is self-describing but its field offsets vary between cellSens
+versions, so the parser probes and scores rather than trusting a layout.
+`pull --dry-run` prints exactly what it worked out; check that before trusting
+the pixels.
+
+This is the only module that prints or sets an exit code. Everything it calls
+raises instead.
+"""
+from __future__ import annotations
+
+import argparse
+import contextlib
+import io
+import json
+import logging
+import re
+import sys
+import threading
+from datetime import datetime
+from dataclasses import replace
+from pathlib import Path
+
+from . import __version__
+from .client import LV200Client
+from . import config
+from . import engine
+from .engine import derive_interval
+from .errors import (AmbiguousDataset, InvalidSelection, LV200Error,
+                     NoDatasetFound)
+from .manifest import MANIFEST_FILENAME
+from .models import Source, human_bytes
+from .options import (DEFAULT_BATCH_FRAMES, LAYOUTS, LAYOUT_DESCRIPTIONS,
+                      MOMENT_HELP, STATE_SCOPES, parse_index,
+                      resolve_layout)
+from . import preview as lv200preview
+from . import setup as lv200setup
+from .state import StateStore
+from . import watch as lv200watch
+from .timeline import DEFAULT_BYTE_BUDGET, DEFAULT_PROJECTION_FRAMES
+
+
+#: Exit code for work a caller stopped. Distinct from 1 ("nothing to do") and
+#: 2 ("it failed"), because a scheduled task treats all three differently.
+STOPPED = 3
+
+#: `scans` lists things every other part of this package calls timepoints, and
+#: that mismatch has to be explained where somebody meets it rather than only
+#: in a planning document.
+SCANS_HELP = """\
+List what a run has acquired so far, one line per timepoint.
+
+Two words for one thing, deliberately: the command is `scans`, which is
+what PyIncucyte calls it and what a microscope operator says, but
+everything this package writes calls them timepoints - the number
+`--from-t` takes, the manifest column, the resume ledger key. So
+`pylv200 timepoints` works too, and --json says "timepoints".
+
+Times are DERIVED from the run's start and its frame interval. An .ets
+records no per-tile timestamp, and nothing here reads a tile.
+"""
+
+
+def _cancelled(args):
+    """Has the caller asked to stop?
+
+    ``args.cancel`` is a ``threading.Event`` the desktop app sets from its
+    Cancel button; nothing sets it on the command line. It is checked between
+    positions and again before a stack is built - not inside the tile loop, so
+    a pull already writing one position finishes that position. Saying it stops
+    sooner than it does would be worse than the wait.
+    """
+    event = getattr(args, "cancel", None)
+    return event is not None and event.is_set()
+
+
+def _recipe(args, exp_name=None):
+    """The resolved recipe: command line > pinned > preset > source > built-in.
+
+    Called once before anything is parsed, so the mirror and the channel
+    selection are known before a tile is read, and again with the experiment
+    name once the sidecar has given one - a per-experiment pin is keyed on that
+    name, and nothing can know it until the `.vsi` has been opened.
+    """
+    source = config.get_source(args.source) if getattr(args, "source", None) \
+        else None
+    key = config.experiment_key(source.name if source else "local", exp_name) \
+        if exp_name else None
+    return config.resolve_options(cli=_given(args), key=key,
+                                  preset=getattr(args, "preset", None),
+                                  source=source), source, key
+
+
+# --------------------------------------------------------------------------
+# machine setup: three commands that are about the microscope, not the data
+#
+# These arrive as subcommands while everything else is still flags. Stage 10
+# turns the whole front end into subparsers; until then a name in this set is
+# routed here and anything else falls through to the flat parser, so nothing
+# that already works changes.
+# --------------------------------------------------------------------------
+
+def _cmd_setup(args):
+    say("walking %s" % (", ".join(args.drives) if args.drives
+                          else "every fixed drive"))
+    seen = [0]
+
+    def progress(path):
+        seen[0] += 1
+        if not args.quiet and seen[0] % 500 == 0:
+            say("    %d folders... %s" % (seen[0], path))
+
+    report = lv200setup.inspect(account=args.account, drives=args.drives,
+                                max_depth=args.max_depth, progress=progress)
+    say("  searched %d folders on %s"
+          % (seen[0], "  ".join(report.drives) or "nothing"))
+
+    if report.datasets:
+        say("\ncellSens data found in %d folder(s):" % len(report.datasets))
+        for path in report.datasets[:20]:
+            say("    %s" % path)
+        if len(report.datasets) > 20:
+            say("    ... and %d more" % (len(report.datasets) - 20))
+        say("\nroots to record:")
+        for root in report.roots:
+            say("    %s" % root)
+    else:
+        say("\nno cellSens data was found. It is recognised by the first four "
+              "bytes of\na file, never by a folder name, so a run in an oddly "
+              "named folder still\ncounts - but one on a drive that was not "
+              "searched does not. Try --drives.")
+
+    if report.registry:
+        agrees = report.agrees_with_registry()
+        say("\ncellSens's own record of an output path:")
+        for where, name, value in report.registry[:6]:
+            say("    %s\\%s = %s" % (where, name, value))
+        say("    -> %s the folders found above"
+              % ("agrees with" if agrees else "DISAGREES with"))
+    else:
+        say("\nno Olympus/Evident registry entry naming an output path. That "
+              "is a normal\nresult - nobody has confirmed cellSens records one - "
+              "and it changes nothing.")
+
+    for note in report.notes:
+        say("  ** %s" % note)
+
+    blockers = report.blockers()
+    if blockers:
+        say("\nwhat is stopping a pull from this machine:")
+        for key, detail in blockers:
+            say("  %-16s %s" % (key.replace("_", " "), detail))
+            say("      %s" % lv200setup.SYMPTOMS[key])
+    else:
+        say("\nnothing is stopping a pull: the profile is Private, the "
+              "firewall rules are\non, %s exists, and a share covers the roots."
+              % args.account)
+
+    if report.account_is_admin:
+        say("\n  ** %s is in the local Administrators group. A broad "
+              "read-only share is\n     safe only because the account is an "
+              "ordinary user; as an administrator\n     the same share reads "
+              "every profile and the registry hives. No share will\n     be "
+              "created while that is true." % args.account)
+
+    plan = lv200setup.build_plan(report, grant_scope=args.grant_scope)
+    if not args.create_share:
+        if plan:
+            say("\n%d change(s) would fix that. Re-run with --create-share to "
+                  "see the plan." % len(plan))
+        return 0 if not blockers else 1
+
+    say("\n" + lv200setup.format_plan(report, plan, args.grant_scope))
+    if not args.yes:
+        return 1
+
+    undo = Path(lv200setup.UNDO_FILENAME)
+    undo.write_text(lv200setup.undo_text(plan, args.account), encoding="utf-8")
+    say("\nwrote %s BEFORE making any change, so an interrupted run is still "
+          "reversible." % undo)
+
+    results = lv200setup.apply_plan(plan, report=report, yes=True)
+    failed = [(a, c) for a, c, ok, _ in results if not ok]
+    for action, command, ok, _ in results:
+        say("  %-4s %s" % ("ok" if ok else "FAIL", command))
+    if failed:
+        say("\n%d command(s) failed. Run them yourself in an elevated "
+              "PowerShell." % len(failed))
+        return 1
+
+    source = lv200setup.source_block(report, host=args.host)
+    block = json.dumps({"sources": {source.name: {
+        "host": source.host, "address": source.address, "share": source.share,
+        "roots": list(source.roots), "account": source.account,
+        "output": ""}}}, indent=2)
+    say("\nrecord this machine on the analysis PC - paste into %s:\n"
+          % config._path(config.SOURCES_FILE))
+    say(block)
+    if args.save_to:
+        Path(args.save_to).write_text(block, encoding="utf-8")
+        say("\nalso written to %s" % args.save_to)
+    say("\nthen, once, on the analysis PC:   pylv200 login %s" % source.name)
+    return 0
+
+
+def _cmd_probe(args):
+    source = source_for(args.source)
+    result = lv200setup.probe(source)
+    for step in result["steps"]:
+        say("  %-4s %-6s %s" % ("ok" if step["ok"] else "FAIL",
+                                  step["layer"], step["detail"]))
+    for note in result.get("notes", ()):
+        say("  ** %s" % note)
+    if result["ok"]:
+        return 0
+    if result["failed"] in ("name", "host", "share"):
+        return 2
+    return 1
+
+
+def _cmd_login(args):
+    source = config.get_source(args.source)
+    command = config.credential_command(source)
+    # Worded without the obvious noun on purpose: tests/test_config.py greps
+    # this package for it, and a guard that has to reason about which lines are
+    # prose is a guard that eventually lets a real one through.
+    say("Windows will now prompt for the credential for %s.\nIt is stored in "
+          "Credential Manager and never reaches pylv200, so it cannot appear in "
+          "a\nconfig file, a log line or a traceback." % source.account)
+    config.store_credential(source)
+    say("\nstored for %s. Check with:  cmdkey /list:%s"
+          % (source.target, source.target))
+    return 0
+
+
+def _cmd_rescan(args):
+    source = config.get_source(args.source)
+    previous = config.get_root_counts(source.name)
+    result = lv200setup.rescan(source, previous=previous)
+    for warning in result["warnings"]:
+        say("  ** %s" % warning)
+    for note in result["notes"]:
+        say("  -- %s" % note)
+    say(result["message"])
+    if not result["roots"]:
+        return 1
+    if result["moved"] and not args.yes:
+        say("\nre-run with --yes to record these roots.")
+        return 1
+    if result["moved"]:
+        config.save_source(replace(source, roots=tuple(result["roots"])))
+        say("recorded.")
+    config.record_root_counts(source.name, result.get("counts", {}))
+    return 0
+
+
+# --------------------------------------------------------------------------
+# the front end
+#
+# Shaped like PyIncucyte's so the two tools are driven the same way. Every
+# command here formats and prints; everything it calls raises instead.
+# --------------------------------------------------------------------------
+
+#: Set by main() before anything runs. Under --json the human commentary moves
+#: to stderr so stdout holds the payload and nothing else - a friendly line on
+#: stdout corrupts the output of whatever is parsing it.
+_JSON = [False]
+
+#: Where output goes when something other than a terminal is driving this.
+#: The desktop app installs itself here and then calls the very same command
+#: functions, so there is one pull, not one per front end - which is the only
+#: way two front ends can be guaranteed to write the same bytes.
+_CONSOLE = [None]
+
+
+@contextlib.contextmanager
+def console(on_say=None, on_emit=None):
+    """Route this module's output to callables instead of stdout.
+
+    Nested and restored on the way out, so a caller that installs one cannot
+    leave the command line silent afterwards.
+    """
+    previous = _CONSOLE[0]
+    _CONSOLE[0] = (on_say, on_emit)
+    try:
+        yield
+    finally:
+        _CONSOLE[0] = previous
+
+
+#: The progress bar currently on screen, if any. `say` wipes it before
+#: printing: the bar is one rewritten line on stderr and a `say` is a fresh
+#: line on stdout, so without this a line lands on top of the bar and leaves
+#: the tail of it behind, on screen, forever.
+_BAR = [None]
+
+
+def say(text=""):
+    """Human-readable progress. stderr under --json, stdout otherwise."""
+    installed = _CONSOLE[0]
+    if installed and installed[0]:
+        installed[0](text)
+        return
+    if _BAR[0] is not None:
+        _BAR[0].clear()
+    print(text, file=sys.stderr if _JSON[0] else sys.stdout)
+
+
+def result(args, payload):
+    """One position's outcome. Collected rather than printed when a run covers
+    several, so a multi-position pull emits one JSON document, not one per
+    stack - two documents on stdout is not JSON."""
+    sink = getattr(args, "sink", None)
+    if sink is None:
+        emit(payload)
+    else:
+        sink.append(payload)
+
+
+def emit(payload, lines=()):
+    """The one place both output modes are produced, so they cannot disagree."""
+    installed = _CONSOLE[0]
+    if installed and installed[1]:
+        installed[1](payload, list(lines))
+        return
+    if _JSON[0]:
+        print(json.dumps(payload, indent=2, default=str))
+    else:
+        for line in lines:
+            print(line)
+
+
+def print_table(rows, headers, align=""):
+    """An aligned plain-text table, **returned rather than printed**.
+
+    PyIncucyte's prints. Here it cannot: `emit` is the one place both output
+    modes are produced, and a table that printed itself would put stray columns
+    on stdout in `--json` mode, where stdout is a document something else is
+    parsing. So this hands lines back and the caller passes them to `emit`.
+
+    ``align`` is one letter per column, "l" or "r"; short strings pad with "l".
+    Counts read wrong left-aligned - the eye compares the wrong digits.
+    """
+    if not rows:
+        return []
+    body = [[("" if cell is None else str(cell)) for cell in row]
+            for row in rows]
+    widths = [max(len(cell) for cell in column)
+              for column in zip(*([list(headers)] + body))]
+    align = (align + "l" * len(widths))[:len(widths)]
+
+    def lay(cells):
+        return "  " + "  ".join(
+            cell.rjust(w) if a == "r" else cell.ljust(w)
+            for cell, w, a in zip(cells, widths, align)).rstrip()
+
+    return [lay(headers), "  " + "  ".join("-" * w for w in widths)] +         [lay(row) for row in body]
+
+
+class ConsoleProgress:
+    """A one-line rewriting progress bar, for a terminal and nothing else.
+
+    Three things switch it off, and all three matter:
+
+    * not a TTY - `\r` and padding written into a redirected file are noise a
+      pipeline then has to strip;
+    * `--json` or `--quiet` - the first has a document on stdout to keep clean,
+      the second was asked for silence;
+    * the desktop app capturing output through `console()` - a bar rewriting
+      itself into a scrolling log pane fills it with padding.
+
+    Deliberately plain: no colour and no ANSI escapes, which need
+    virtual-terminal mode turned on and are not on by default in `cmd.exe`.
+    """
+
+    #: Wide enough to see movement, narrow enough to leave room for the text
+    #: on an 80-column console.
+    WIDTH = 24
+    LINE = 110
+
+    def __init__(self, enabled=True, stream=None):
+        self.stream = stream if stream is not None else sys.stderr
+        self.enabled = bool(enabled) and bool(
+            getattr(self.stream, "isatty", lambda: False)())
+        self.drawn = False
+
+    def __call__(self, event):
+        if not self.enabled:
+            return
+        # `done` is the one terminal event a pull emits, and a watcher emits one
+        # per poll. Clearing here rather than at exit is what stops the second
+        # poll's bar continuing the first one's line.
+        if event.stage == "done":
+            self.clear()
+            return
+        if event.total:
+            filled = int(round(self.WIDTH * min(1.0, event.fraction)))
+            text = ("%-9s [%s] %d/%d %s"
+                    % (event.stage, "#" * filled + "." * (self.WIDTH - filled),
+                       event.done, event.total, event.unit))
+        else:
+            text = "%-9s %s" % (event.stage, event.detail)
+        if event.position:
+            text = "%s  %s" % (text, event.position)
+        self.stream.write("\r" + text[:self.LINE].ljust(self.LINE))
+        self.stream.flush()
+        self.drawn = True
+
+    def clear(self):
+        """Wipe the line, leaving no padding behind for the next thing."""
+        if self.enabled and self.drawn:
+            self.stream.write("\r" + " " * self.LINE + "\r")
+            self.stream.flush()
+            self.drawn = False
+
+
+def _progress(args):
+    """What a command hands the engine: a caller's own hook, or a bar.
+
+    A front end sets `args.progress` before calling the command function, and
+    it wins - it is already capturing output, so `_progress_for` would return
+    None for it anyway; this just says so where somebody reading the command
+    can see it.
+    """
+    return getattr(args, "progress", None) or _progress_for(args)
+
+
+def _progress_for(args):
+    """A bar to hand to the engine, or None. Never a bar and captured output.
+
+    Registered in `_BAR` so `say` can wipe the line before printing over it.
+    """
+    if getattr(args, "json", False) or getattr(args, "quiet", False):
+        return None
+    if _CONSOLE[0] is not None:          # a front end is capturing this
+        return None
+    bar = ConsoleProgress()
+    if not bar.enabled:
+        return None
+    _BAR[0] = bar
+    return bar
+
+
+def literal(text):
+    """Help text argparse will not %-format.
+
+    argparse %-formats every help string, so a bare `%` in one raises TypeError
+    when the user types --help. It is a crash they meet and no test catches
+    unless --help is asserted on. PyIncucyte hit exactly this.
+    """
+    return text.replace("%", "%%")
+
+
+def add_selection_options(p):
+    """Which timepoints, which channels, and how the pixels are read."""
+    # --channels selects, as it does in PyIncucyte. The header override it
+    # used to be is now --channel-count; `--channels 4` on a four-channel file
+    # would otherwise silently change meaning, so select_channels raises and
+    # names the replacement rather than writing the wrong stack.
+    p.add_argument("-c", "--channels", type=int, nargs="+", metavar="C",
+                   help="only these channel indexes. Tiles are read by offset, "
+                        "so the others never cross the wire.")
+    p.add_argument("--channel-count", type=int, metavar="N",
+                   help="override the channel count read from the file header")
+    # ExportOptions.positions and LV200Client.plan have honoured a position
+    # filter since stage 04, and _pull_experiment has read one since stage 10;
+    # only the flag was missing. The desktop app selects positions by clicking
+    # a thumbnail, and a control the command line cannot express is how two
+    # front ends start disagreeing.
+    p.add_argument("-p", "--positions", nargs="+", metavar="NAME",
+                   help="only these positions (fields of view). Each gets its "
+                        "own stack; the default is every one the run has.")
+    p.add_argument("-n", "--last-n", type=int, metavar="N",
+                   help="only the N most recent timepoints. Tiles are read by "
+                        "offset, so the rest never cross the wire - use this "
+                        "over a network share.")
+    p.add_argument("--from-t", type=int, metavar="T",
+                   help="first timepoint, numbered as the file numbers them")
+    p.add_argument("--to-t", type=int, metavar="T",
+                   help="last timepoint, numbered as the file numbers them")
+    # --last-n and --from-t are the friendly spellings of the two common cases
+    # and stay. These say the same thing in the recipe's own vocabulary, and
+    # are the ONLY way to ask for a duration: the recipe has always accepted
+    # `-48h` and until now no flag could produce one, so "the last two days"
+    # was reachable from a preset and from Python but not from a prompt.
+    p.add_argument("-s", "--start-from", metavar="WHEN",
+                   help=literal("where the window opens: %s. A duration is "
+                                "resolved against the run's own frame "
+                                "interval, counting back from its newest "
+                                "timepoint - not from now, so a run that "
+                                "finished last month still has a last 48 "
+                                "hours." % MOMENT_HELP))
+    p.add_argument("--end-at", metavar="WHEN",
+                   help=literal("where it closes: %s. '+100f' takes the first "
+                                "100 timepoints of the window, '+7d' its "
+                                "first week." % MOMENT_HELP))
+    # Here rather than with the writing flags, where it used to be: it
+    # calibrates the T axis of the stack, but it is ALSO what a duration window
+    # is resolved against, and `plan` takes no writing flags - so `plan
+    # --start-from -48h` on a run whose timestamps give nothing had no way to
+    # say how long a frame is.
+    p.add_argument("--interval", type=float,
+                   help="seconds between timepoints; derived from the run's "
+                        "own timestamps when not given. A duration window such "
+                        "as --start-from -48h is resolved against it.")
+    p.add_argument("--include-last", action="store_true",
+                   help="include the final tile (may be mid-write and torn)")
+    p.add_argument("--axes", help="override axis names, e.g. 'tx,ty,z,c,t'")
+    p.add_argument("--ndims", type=int,
+                   help="force the chunk-table dimension count")
+    p.add_argument("--dtype", help="force pixel type, e.g. uint16")
+    p.add_argument("--safe-copy", action="store_true",
+                   help="copy each .ets to temp before parsing (slower, immune "
+                        "to growth)")
+    p.add_argument("--preset", metavar="NAME",
+                   help="apply a saved recipe. The command line still wins.")
+
+
+def add_writing_options(p):
+    """Where the stacks go and what shape they take."""
+    # --output is PyIncucyte's spelling of the same flag. Both stay: -o is
+    # what everything already written types, and --output is what somebody
+    # arriving from the other package types without thinking about it.
+    p.add_argument("-o", "--out", "--output",
+                   help="output directory for the stacks")
+    p.add_argument("--pixel-size", type=float,
+                   help="pixel size in microns, for spatial calibration")
+    p.add_argument("--channel-names",
+                   help="comma-separated names in acquisition order. Normally "
+                        "unnecessary - they are read from the .vsi - and used "
+                        "on later pulls of the same experiment once given.")
+    # The canonical control. The three booleans below are shorthands for it
+    # and must not disagree with it - `_given` resolves both in one place and
+    # errors rather than picking a winner.
+    p.add_argument("--layout", metavar="NAME",
+                   help=literal("how the pixels are laid out on disk: %s "
+                                "(default: composite). Synonyms such as "
+                                "'hyperstack' and 'ome-tiff' resolve too."
+                                % ", ".join("%s - %s" % (n, LAYOUT_DESCRIPTIONS[n])
+                                            for n in LAYOUTS)))
+    p.add_argument("--composite", action="store_true",
+                   help="display channels overlaid in ImageJ's default colours. "
+                        "Off by default: these are grayscale detector channels "
+                        "and the colours carry no meaning.")
+    p.add_argument("--split-channels", action="store_true",
+                   help="one TIFF per channel instead of one multichannel stack")
+    p.add_argument("--ome-tiff", action="store_true",
+                   help="a lossless LZW OME-TIFF (<stem>.ome.tif) instead of an "
+                        "ImageJ hyperstack - the same shape as the Bio-Formats "
+                        "conversion of a finished .vsi, so the two are "
+                        "interchangeable. Chosen automatically past 4 GB, which "
+                        "ImageJ cannot exceed.")
+    p.add_argument("--no-pin", action="store_true",
+                   help="do not remember --channel-names for this experiment, "
+                        "and forget any already pinned for it")
+    p.add_argument("--mirror", metavar="DIR",
+                   help="keep a local byte copy of each .ets in DIR and read "
+                        "the tiles from there. Only the bytes the acquisition "
+                        "has added since the last run cross the wire, and what "
+                        "is left behind is a complete copy of the run - which "
+                        "during acquisition is the only copy that exists.")
+    p.add_argument("--no-append", dest="append_stacks", action="store_false",
+                   default=None,
+                   help="rewrite the whole stack when a timepoint is added, "
+                        "instead of adding the new planes in place. Appending "
+                        "falls back to a rewrite on its own whenever the file "
+                        "is not the earlier part of this same stack, so the "
+                        "only reason to ask is caution: an appended frame "
+                        "cannot be un-appended, where a rewrite replaces the "
+                        "file.")
+    p.add_argument("--no-manifest", dest="write_manifest", action="store_false",
+                   default=None,
+                   help="do not write pylv200-manifest.json and the CSV index. "
+                        "They are what a pipeline reads instead of parsing "
+                        "filenames, so this is rarely what you want.")
+    p.add_argument("--state-scope", choices=STATE_SCOPES, default=None,
+                   help="where the resume ledger lives (default: folder, one "
+                        "beside the images). 'global' keeps a single ledger "
+                        "under the settings home, so a pull into a fresh "
+                        "folder starts already knowing what was collected - "
+                        "and therefore may write nothing into it. 'none' keeps "
+                        "no ledger.")
+    p.add_argument("--no-state", dest="state_scope", action="store_const",
+                   const="none", default=None,
+                   help="shorthand for --state-scope none: keep no resume "
+                        "ledger for this output folder at all. Different from "
+                        "--no-resume, which stops the ledger being consulted "
+                        "but still records what was written.")
+    # An action rather than a recipe field, which is why it has no ExportOptions
+    # counterpart and never appears in `command_line`: it says "also write down
+    # what you resolved", not "pull it this way".
+    p.add_argument("--save-preset", metavar="PATH",
+                   help="write the resolved recipe to this JSON file before "
+                        "reading a tile, so a run that is cancelled still "
+                        "leaves the recipe it was going to use. `preset --save "
+                        "NAME` is the other one - that stores into the named "
+                        "preset store.")
+
+
+def add_watch_options(p):
+    """The cadence a watcher keeps.
+
+    On ``preset`` as well as ``watch``, because the recipe carries it: "collect
+    this run a week at a time" is exactly the thing worth saving, and a cadence
+    that lives only in a flag cannot be saved at all.
+    """
+    # NOT --interval: that already means the run's frame interval on every
+    # writing command, and two flags a letter apart meaning different periods
+    # is a mistake somebody makes at 2am.
+    p.add_argument("-i", "--poll-interval", dest="poll_interval", type=float,
+                   metavar="SECONDS",
+                   help="seconds between polls. Defaults to half the run's own "
+                        "frame interval: polling a 31-minute acquisition every "
+                        "30 seconds costs round trips for nothing.")
+    p.add_argument("--batch-frames", type=int, metavar="N", default=None,
+                   help=literal("hold new timepoints until N have accumulated, "
+                                "then write the chunk in one go. The default "
+                                "writes each timepoint as it appears (%d), "
+                                "which is cheap because new planes are added "
+                                "to the stack in place - see --no-append."
+                                % DEFAULT_BATCH_FRAMES))
+    p.add_argument("--batch-after", metavar="DURATION",
+                   help="write regardless once the oldest waiting timepoint is "
+                        "this old, e.g. 7d. Measured from when it was acquired, "
+                        "so restarting the watcher does not restart the wait.")
+
+
+TARGET_HELP = literal(
+    "source:experiment, e.g. left-lv200:ois351A. A bare experiment name "
+    "resolves against the only configured source; a path is taken as-is.")
+
+
+def build_parser():
+    ap = argparse.ArgumentParser(
+        prog="pylv200", description=literal(__doc__),
+        formatter_class=argparse.RawDescriptionHelpFormatter)
+    # --json belongs to the top-level parser, not to each subcommand, or
+    # `pylv200 list --json` and `pylv200 --json list` end up disagreeing.
+    ap.add_argument("--json", action="store_true",
+                    help="machine-readable output on stdout; everything else "
+                         "goes to stderr")
+    ap.add_argument("--version", action="version",
+                    version="pylv200 %s" % __version__)
+    ap.add_argument("-q", "--quiet", action="store_true",
+                    help="no progress display, and warnings only in the log")
+    ap.add_argument("--verbose", action="store_true",
+                    help="debug logging on stderr")
+    subs = ap.add_subparsers(dest="command", required=True)
+
+    # -- the microscope ----------------------------------------------------
+    s = subs.add_parser("setup", help="run ON THE MICROSCOPE: find the data and "
+                                      "report what stops a share from working")
+    s.add_argument("--account", default=lv200setup.DEFAULT_ACCOUNT,
+                   help=literal("the read-only account to create "
+                                "(default: %(default)s)"))
+    s.add_argument("--drives", nargs="+", metavar="D:\\",
+                   help="search only these drives instead of every fixed one")
+    s.add_argument("--max-depth", type=int, default=lv200setup.MAX_DEPTH,
+                   help=literal("how deep to walk each drive "
+                                "(default: %(default)s)"))
+    s.add_argument("--create-share", action="store_true",
+                   help="also fix the network layer and create the share")
+    s.add_argument("--grant-scope", choices=("drives", "discovered"),
+                   default="drives",
+                   help=literal("grant NTFS read at every fixed drive root, or "
+                                "only where data was found "
+                                "(default: %(default)s)"))
+    s.add_argument("--yes", action="store_true",
+                   help="actually make the changes. Without it the plan is "
+                        "printed and nothing happens.")
+    s.add_argument("--host", default="",
+                   help="the name to record for this machine (default: its "
+                        "hostname)")
+    s.add_argument("--save-to", metavar="FILE",
+                   help="write the source block here as well as printing it")
+    s.add_argument("--quiet", action="store_true",
+                   default=argparse.SUPPRESS,
+                   help="do not print each folder as it is walked. The global "
+                        "-q means this too.")
+
+    p = subs.add_parser("probe", help="is a source reachable, and if not, which "
+                                      "layer failed")
+    p.add_argument("source", help="a name from the settings, or a path")
+
+    lg = subs.add_parser("login", help="hand a credential to Windows Credential "
+                                       "Manager; this package never sees it")
+    lg.add_argument("source", help="a name from the settings")
+
+    lo = subs.add_parser("logout", help="forget a source's stored credential")
+    lo.add_argument("source", help="a name from the settings")
+
+    r = subs.add_parser("rescan", help="find an output folder that moved, "
+                                       "without a lab visit")
+    r.add_argument("source", help="a name from the settings")
+    r.add_argument("--yes", action="store_true",
+                   help="update the recorded roots when the data has moved")
+
+    subs.add_parser("sources", help="the microscopes this machine knows about")
+
+    # -- what is there -----------------------------------------------------
+    ls = subs.add_parser("list", help="experiments on a source, newest first")
+    ls.add_argument("source", nargs="?",
+                    help="a name from the settings, or a path. Omitted, the "
+                         "only configured source is used.")
+    ls.add_argument("--live", action="store_true",
+                    help="also say which are being written right now. Costs a "
+                         "header read per position, so it is opt-in.")
+    ls.add_argument("--refresh", action="store_true",
+                    help="walk again instead of using the cached scan")
+
+    st = subs.add_parser("status", help="what is reachable, what a watcher is "
+                                       "doing, what has been written")
+    st.add_argument("target", nargs="?",
+                    help="a source, or source:experiment. Omitted, every "
+                         "configured source is reported on.")
+    st.add_argument("-o", "--out", "--output",
+                    help="an output folder: report its watcher heartbeat and "
+                         "how much its resume ledger holds")
+    st.add_argument("-i", "--poll-interval", type=float, metavar="SECONDS",
+                    help="the cadence the watcher was started with. A "
+                         "heartbeat older than three of these is called stale; "
+                         "the default assumes 900.")
+
+    sc = subs.add_parser(
+        "scans", help="the timepoints a run holds, and when each was acquired",
+        description=SCANS_HELP,
+        formatter_class=argparse.RawDescriptionHelpFormatter)
+    sc.add_argument("target", help=TARGET_HELP)
+
+    fd = subs.add_parser("find", help="which experiment is that?")
+    fd.add_argument("pattern", help="part of an experiment, folder or position "
+                                    "name")
+    fd.add_argument("--source", help="a name from the settings, or a path")
+
+    # -- what a pull would do ----------------------------------------------
+    pl = subs.add_parser("plan", help="what a pull would fetch, and what is "
+                                      "already held")
+    pl.add_argument("target", help=TARGET_HELP)
+    pl.add_argument("-o", "--out", "--output",
+                    help="the output folder whose ledger to compare against")
+    add_selection_options(pl)
+
+    # -- pulling -----------------------------------------------------------
+    pu = subs.add_parser("pull", help="fetch once, writing every selected "
+                                      "timepoint")
+    pu.add_argument("target", help=TARGET_HELP)
+    pu.add_argument("--dry-run", action="store_true",
+                    help="report the geometry and write nothing")
+    pu.add_argument("--resume", action="store_true",
+                    help="skip timepoints this output folder already holds. "
+                         "`sync` is that, by default.")
+    add_selection_options(pu)
+    add_writing_options(pu)
+
+    sy = subs.add_parser("sync", help="fetch only what is new, using the ledger")
+    sy.add_argument("target", help=TARGET_HELP)
+    sy.add_argument("--dry-run", action="store_true",
+                    help="report the geometry and write nothing")
+    sy.add_argument("--no-resume", action="store_true",
+                    help="write every selected timepoint again, ignoring the "
+                         "ledger")
+    add_selection_options(sy)
+    add_writing_options(sy)
+
+    wa = subs.add_parser("watch", help="poll a running experiment and collect "
+                                      "what is new, on an interval")
+    wa.add_argument("target", help=TARGET_HELP)
+    add_watch_options(wa)
+    wa.add_argument("--once", action="store_true",
+                    help="poll once and stop, for a Scheduled Task")
+    wa.add_argument("--flush", action="store_true",
+                    help="write whatever is being held now, then stop")
+    wa.add_argument("--status", action="store_true",
+                    help="report what the watcher for this output has done, "
+                         "and whether it is still running")
+    add_selection_options(wa)
+    add_writing_options(wa)
+
+    pv = subs.add_parser("preview", help="a few tiles per position, so you can "
+                                        "see which one you want before pulling it")
+    pv.add_argument("target", help=TARGET_HELP)
+    pv.add_argument("-o", "--out", "--output",
+                    help="folder for the thumbnails and the sheet")
+    pv.add_argument("--stretch", nargs=2, type=float, metavar=("LO", "HI"),
+                    default=(lv200preview.DEFAULT_LO, lv200preview.DEFAULT_HI),
+                    help=literal("contrast percentiles (default: %(default)s). "
+                                 "A full-range map renders a photon-starved "
+                                 "luminescence frame black, which reads as no "
+                                 "data rather than few photons."))
+    pv.add_argument("--project", type=int, metavar="N",
+                    default=lv200preview.PROJECT_FRAMES,
+                    help=literal("frames to average for a photon-starved "
+                                 "channel (default: %(default)s)"))
+    pv.add_argument("-c", "--channels", type=int, nargs="+", metavar="C",
+                    help="only these channel indexes")
+    # A preset carries a channel selection, and a preview of the wrong channels
+    # is a preview of nothing: the point of it is deciding which position to
+    # pull, using the recipe the pull will use.
+    pv.add_argument("--preset", metavar="NAME",
+                    help="apply a saved recipe's channel selection. The "
+                         "command line still wins.")
+    pv.add_argument("--no-sheet", action="store_true",
+                    help="thumbnails only, no contact sheet")
+
+    tl = subs.add_parser(
+        "timeline", help="save a byte-bounded set of time-course previews")
+    tl.add_argument("target", help=TARGET_HELP)
+    tl.add_argument("-o", "--out", "--output",
+                    help="folder for the bounded anchor PNG files")
+    tl.add_argument("--position", help="one position (default: the first)")
+    tl.add_argument("-c", "--channel", type=int,
+                    help="one channel index (default: the first)")
+    tl.add_argument("--budget-mib", type=float,
+                    default=DEFAULT_BYTE_BUDGET / float(1 << 20),
+                    help="maximum initial source bytes in MiB (default: 64)")
+    tl.add_argument("--stretch", nargs=2, type=float, metavar=("LO", "HI"),
+                    default=(lv200preview.DEFAULT_LO, lv200preview.DEFAULT_HI),
+                    help="contrast percentiles for saved previews")
+    tl.add_argument("--project", type=int, metavar="N",
+                    default=DEFAULT_PROJECTION_FRAMES,
+                    help="frames averaged for bioluminescence (default: 4)")
+    tl.add_argument("--preview-cache",
+                    help="folder for disposable persistent previews")
+    tl.add_argument("--no-proxy", action="store_true",
+                    help="do not read or write the persistent preview cache")
+    tl.add_argument("--local", metavar="PULL_FOLDER",
+                    help="prefer a completed local PyLV200 pull")
+    tl.add_argument("--mirror", metavar="FOLDER",
+                    help="read available ETS bytes from this configured mirror")
+
+    g = subs.add_parser("gui", help="the desktop app: choose a position by "
+                                    "looking at it rather than by name")
+    g.add_argument("target", nargs="?", help=TARGET_HELP)
+    g.add_argument("--light", dest="dark", action="store_false", default=None,
+                   help="force the light theme instead of following Windows")
+    g.add_argument("--dark", dest="dark", action="store_true",
+                   help="force the dark theme instead of following Windows")
+
+    mf = subs.add_parser("manifest", help="summarise a previous pull")
+    mf.add_argument("folder", help="a folder a pull wrote into")
+
+    pr = subs.add_parser("preset", help="show or save a named recipe")
+    pr.add_argument("name", nargs="?", help="the preset to show or save")
+    pr.add_argument("--save", action="store_true",
+                    help="save the options given here under that name")
+    pr.add_argument("--delete", action="store_true", help="remove it")
+    add_selection_options(pr)
+    add_writing_options(pr)
+    add_watch_options(pr)
+    return ap
+
+
+# --------------------------------------------------------------------------
+# targets
+# --------------------------------------------------------------------------
+
+def parse_target(text):
+    """``'left-lv200:ois351A'`` -> ``(Source or None, experiment or None)``.
+
+    A bare name resolves against the only configured source; with more than one
+    it raises and lists them, because guessing which microscope is what puts one
+    experiment's channel names on another's pixels. A path is taken as itself.
+    """
+    text = str(text or "")
+    # A Windows path starts `D:\` - one letter before the colon - so a colon
+    # alone does not make something a source:experiment target.
+    head, sep, tail = text.partition(":")
+    if sep and len(head) > 1 and not tail.startswith(("\\", "/")):
+        sources = config.load_sources()
+        if head in sources:
+            return sources[head], tail or None
+        # A folder works wherever a source name does. Nothing about naming one
+        # experiment inside a scratch tree requires the tree to be configured
+        # first, and the alternative is `find` then a full path.
+        if Path(head).is_dir():
+            return Source(name=head, roots=(head,)), tail or None
+        return config.get_source(head), tail or None    # raises, listing what it knows
+
+    if Path(text).exists() or text.startswith("\\\\"):
+        return Source(name=text, roots=(text,)), None
+
+    sources = config.load_sources()
+    if not sources:
+        raise LV200Error(
+            "%r is not a folder, and no microscope is configured to look it up "
+            "on.\n  Run `pylv200 setup` on the microscope, or give a path."
+            % text)
+    if len(sources) > 1:
+        raise LV200Error(
+            "%r does not say which microscope. Write it as source:experiment.\n"
+            "  Configured sources: %s" % (text, ", ".join(sorted(sources))))
+    return next(iter(sources.values())), text
+
+
+def source_for(name):
+    """A settings name if there is one, otherwise a path taken as itself."""
+    if not name:
+        sources = config.load_sources()
+        if len(sources) == 1:
+            return next(iter(sources.values()))
+        if not sources:
+            raise LV200Error("no microscope is configured and no path was "
+                             "given.\n  Run `pylv200 setup` on the microscope, "
+                             "or give a folder.")
+        raise LV200Error("more than one microscope is configured; name one: %s"
+                         % ", ".join(sorted(sources)))
+    try:
+        return config.get_source(name)
+    except LV200Error:
+        if Path(name).exists() or name.startswith("\\\\"):
+            return Source(name=name, roots=(name,))
+        raise
+
+
+def _experiment_dict(exp, live=False):
+    return {"name": exp.name, "folder": str(exp.folder),
+            "positions": [p.name for p in exp.positions],
+            "channels": list(exp.channel_names or ()),
+            "started": exp.started, "camera": exp.camera,
+            "objective": exp.objective,
+            "bytes": sum(p.size for p in exp.positions),
+            "live": (any(p.is_live for p in exp.positions) if live else None)}
+
+
+# --------------------------------------------------------------------------
+# commands
+# --------------------------------------------------------------------------
+
+def cmd_sources(args):
+    sources = config.load_sources()
+    payload = {"sources": [
+        {"name": s.name, "host": s.host, "address": s.address,
+         "share": s.share, "roots": list(s.roots), "account": s.account,
+         "output": s.output} for s in sources.values()]}
+    lines = print_table(
+        [(s.name, s.target or "-", ", ".join(s.roots) or "no roots recorded")
+         for s in sources.values()],
+        ("source", "reached at", "roots"))
+    emit(payload, lines or ["  no microscope is configured. Run `pylv200 "
+                            "setup` on one, then paste the block it prints "
+                            "into %s." % config._path(config.SOURCES_FILE)])
+    return 0 if sources else 1
+
+
+def cmd_list(args):
+    source = source_for(args.source)
+    client = LV200Client(source)
+    experiments = client.experiments(refresh=args.refresh, live=args.live)
+    payload = {"source": source.name,
+               "experiments": [_experiment_dict(e, args.live)
+                               for e in experiments],
+               "notes": list(client.notes)}
+    # Measured rather than %-44s: an experiment name is whatever cellSens was
+    # given, and a truncated one is a name somebody then cannot paste back in.
+    rows = [([exp.name, len(exp.positions),
+              human_bytes(sum(p.size for p in exp.positions))]
+             + (["LIVE" if any(p.is_live for p in exp.positions) else ""]
+                if args.live else []))
+            for exp in experiments]
+    lines = print_table(rows, ["experiment", "positions", "size"]
+                        + (["live"] if args.live else []), "lrrl")
+    for note in client.notes:
+        say("  ** %s" % note)
+    emit(payload, lines or ["  nothing found under %s"
+                            % (", ".join(source.roots) or source.name)])
+    return 0 if experiments else 1
+
+
+def cmd_find(args):
+    source = source_for(args.source)
+    matches = LV200Client(source).find(args.pattern)
+    emit({"source": source.name,
+          "experiments": [_experiment_dict(e) for e in matches]},
+         print_table([(e.name, len(e.positions), e.folder) for e in matches],
+                     ("experiment", "positions", "folder"), "lrl")
+         or ["  nothing matches %r" % args.pattern])
+    return 0 if matches else 1
+
+
+def cmd_plan(args):
+    source, name = parse_target(args.target)
+    client = LV200Client(source)
+    experiment = client.experiment(name) if name else _only(client)
+    opts = config.resolve_options(
+        cli=_given(args), key=config.experiment_key(source, experiment.name),
+        preset=getattr(args, "preset", None), source=source)
+
+    # The ledger key carries the recipe, and a pull fills the channel names in
+    # from the .vsi before recording. `plan` has to do the same or every
+    # timepoint reads as new - the same file, two keys.
+    if not opts.channel_names and experiment.channel_names:
+        opts = opts.replace(channel_names=tuple(experiment.channel_names))
+
+    store = None
+    if args.out and Path(args.out).is_dir():
+        store = StateStore.for_output(Path(args.out))
+    plan = client.plan(experiment, opts, store=store,
+                       progress=_progress(args))
+
+    payload = {"experiment": experiment.name,
+               "positions": [p.name for p in plan.positions],
+               "timepoints": list(plan.timepoints),
+               "channels": list(plan.channels),
+               "already_held": list(plan.already_have),
+               "to_fetch": {"timepoints": len(plan.new_timepoints),
+                            "bytes": plan.bytes_to_read},
+               "channel_names": list(experiment.channel_names or ())}
+    lines = [
+        "  %s" % experiment.name,
+        "  %d position(s), %d timepoint(s), %d channel(s)"
+        % (len(plan.positions), len(plan.timepoints), len(plan.channels)),
+    ]
+    if experiment.channel_names:
+        lines.append("  channels        %s"
+                     % "  ".join("C%d %s" % (i, n) for i, n
+                                 in enumerate(experiment.channel_names)))
+    if plan.timepoints:
+        lines.append("  selection       t=%d..%d"
+                     % (plan.timepoints[0], plan.timepoints[-1]))
+    if store is not None:
+        lines.append("  already held    %d timepoint(s) in %s"
+                     % (len(plan.already_have), args.out))
+    lines.append("  to fetch        %d timepoint(s), %s"
+                 % (len(plan.new_timepoints), human_bytes(plan.bytes_to_read)))
+    emit(payload, lines)
+    return 0 if plan.new_timepoints else 1
+
+
+def _only(client):
+    """The experiment on a source that has exactly one."""
+    found = client.experiments()
+    if len(found) == 1:
+        return found[0]
+    if not found:
+        raise NoDatasetFound("nothing was found under %s"
+                             % (", ".join(client.roots) or client.source.name))
+    raise AmbiguousDataset(
+        "%d experiments are here; name one:\n    %s"
+        % (len(found), "\n    ".join(e.name for e in found[:20])))
+
+
+def _one_of(args, *flags):
+    """Refuse two flags that both set the same recipe field.
+
+    Picking a winner is what makes two spellings drift apart: somebody types
+    both, gets the other one's answer, and the flag they meant is never
+    mentioned. Saying which two disagree costs one retype and no gigabytes.
+    """
+    given = [(flag, getattr(args, dest, None)) for flag, dest in flags
+             if getattr(args, dest, None) is not None]
+    if len(given) > 1:
+        raise InvalidSelection(
+            "%s say the same thing and disagree: %s. Use one."
+            % (" and ".join(f for f, _v in given),
+               ", ".join("%s %s" % (f, v) for f, v in given)))
+    return given[0][1] if given else None
+
+
+def _window_start(args):
+    """Where the time window opens, in ExportOptions' own vocabulary.
+
+    `--last-n 24` is "-24f" - 24 frames back from the newest - which is what
+    makes it survive into a preset and stay meaningful when the run has grown.
+    `--start-from` says the same thing in the recipe's own words and is the
+    only one of the three that can carry a duration.
+    """
+    _one_of(args, ("--start-from", "start_from"), ("--from-t", "from_t"),
+            ("--last-n", "last_n"))
+    if getattr(args, "start_from", None):
+        return _moment(args.start_from)
+    if getattr(args, "from_t", None) is not None:
+        return args.from_t
+    last_n = getattr(args, "last_n", None)
+    return "-%df" % last_n if last_n else None
+
+
+def _window_end(args):
+    """Where it closes. `--to-t 40` and `--end-at 40` are one field."""
+    _one_of(args, ("--end-at", "end_at"), ("--to-t", "to_t"))
+    if getattr(args, "end_at", None):
+        return _moment(args.end_at)
+    return args.to_t if getattr(args, "to_t", None) is not None else None
+
+
+def _moment(text):
+    """A --start-from / --end-at value as the recipe holds it.
+
+    A bare number becomes an int, so `--end-at 40` and `--to-t 40` save the
+    same preset rather than one holding 40 and the other "40".
+    """
+    index = parse_index(text)
+    return index if index is not None else text
+
+
+def _layout(args):
+    """The layout, from `--layout` or from whichever boolean was set.
+
+    One place, because `--layout ome --split-channels` has no right answer and
+    two places is how a front end and a prompt come to write different files.
+    """
+    named = getattr(args, "layout", None)
+    booleans = [flag for flag, dest in (("--split-channels", "split_channels"),
+                                        ("--ome-tiff", "ome_tiff"))
+                if getattr(args, dest, False)]
+    if named and booleans:
+        raise InvalidSelection(
+            "--layout %s and %s say the same thing and disagree. Use one."
+            % (named, " and ".join(booleans)))
+    if len(booleans) > 1:
+        raise InvalidSelection(
+            "%s say the same thing and disagree. Use one."
+            % " and ".join(booleans))
+    if named:
+        return resolve_layout(named)     # raises, listing the valid names
+    if booleans:
+        return "split" if booleans[0] == "--split-channels" else "ome"
+    return None
+
+
+def _given(args):
+    """Only the options the caller actually passed.
+
+    A filled-in ExportOptions would carry a default for every flag that was not
+    given, and a default silently unpins whatever somebody chose.
+    """
+    names = getattr(args, "channel_names", None)
+    positions = getattr(args, "positions", None)
+    channels = getattr(args, "channels", None)
+    given = {
+        "output": getattr(args, "out", None),
+        "positions": tuple(positions) if positions else None,
+        "channels": tuple(channels) if channels else None,
+        "mirror": getattr(args, "mirror", None),
+        "write_manifest": getattr(args, "write_manifest", None),
+        "append_stacks": getattr(args, "append_stacks", None),
+        "state_scope": getattr(args, "state_scope", None),
+        "poll_interval_s": getattr(args, "poll_interval", None),
+        "batch_frames": (getattr(args, "batch_frames", None) or None),
+        "batch_after": getattr(args, "batch_after", None),
+        "channel_names": (tuple(n.strip() for n in names.split(","))
+                          if names else None),
+        "pixel_size_um": getattr(args, "pixel_size", None),
+        "interval_s": getattr(args, "interval", None),
+        "layout": _layout(args),
+        "composite_display": True if getattr(args, "composite", False) else None,
+        "include_last": True if getattr(args, "include_last", False) else None,
+        "safe_copy": True if getattr(args, "safe_copy", False) else None,
+        "start_from": _window_start(args),
+        "end_at": _window_end(args),
+    }
+    return {k: v for k, v in given.items() if v is not None}
+
+
+# --------------------------------------------------------------------------
+# a recipe as a command line
+#
+# The desktop app does not build an argparse namespace by hand. It builds argv
+# and hands it to `build_parser()`, so it cannot express anything the command
+# line cannot - which is what makes "the app and the CLI write the same bytes"
+# a property of the code rather than a claim in a docstring.
+# --------------------------------------------------------------------------
+
+# --save-preset is deliberately absent: it is an action a run performs, not a
+# field of the recipe, so there is nothing for `command_line` to emit.
+_SELECTION_FLAGS = {"--last-n", "--from-t", "--to-t", "--start-from",
+                    "--end-at", "--interval", "--include-last", "--safe-copy",
+                    "--positions", "--channels", "--preset"}
+_WRITING_FLAGS = {"-o", "--pixel-size", "--channel-names",
+                  "--layout", "--composite", "--split-channels", "--ome-tiff",
+                  "--no-pin", "--mirror", "--no-manifest", "--state-scope",
+                  "--no-state", "--no-append"}
+#: Only `watch` has a cadence to describe.
+_WATCH_FLAGS = {"--poll-interval", "--batch-frames", "--batch-after"}
+
+#: Which flags each verb accepts. Explicit rather than introspected, because a
+#: wrong entry here has to fail loudly - and it does: the round-trip test parses
+#: every command :func:`command_line` builds.
+VERB_FLAGS = {
+    "plan": _SELECTION_FLAGS | {"-o"},
+    "pull": _SELECTION_FLAGS | _WRITING_FLAGS,
+    "sync": _SELECTION_FLAGS | _WRITING_FLAGS,
+    "watch": _SELECTION_FLAGS | _WRITING_FLAGS | _WATCH_FLAGS,
+    "preview": {"-o", "--channels"},
+}
+
+
+def command_line(options, target, verb="sync", preset=None, no_pin=False):
+    """The exact ``pylv200`` command this recipe is, as argv.
+
+    A recipe field with no flag behind it is not emitted, and a time window the
+    command line cannot say raises rather than being quietly dropped: a window
+    that silently became "the whole run" would move gigabytes nobody asked for.
+    """
+    allowed = VERB_FLAGS.get(verb, set())
+    argv = [verb, str(target)]
+
+    def add(flag, *values):
+        if flag in allowed:
+            argv.append(flag)
+            argv.extend(str(v) for v in values)
+
+    frames = options.start_frames
+    first = parse_index(options.start_from)
+    last = parse_index(options.end_at)
+
+    if options.output:
+        add("-o", options.output)
+    if options.positions:
+        add("--positions", *options.positions)
+    if options.channels:
+        add("--channels", *options.channels)
+    if options.mirror:
+        add("--mirror", options.mirror)
+    if not options.append_stacks:
+        add("--no-append")
+    if not options.write_manifest:
+        add("--no-manifest")
+    if options.state_scope == "none":
+        add("--no-state")
+    elif options.state_scope == "global":
+        add("--state-scope", "global")
+    if options.poll_interval_s:
+        add("--poll-interval", options.poll_interval_s)
+    # Emitted even at its default: the recipe owns the cadence, so the command
+    # has to say what the cadence is rather than rely on a flag default that
+    # could drift away from the field default.
+    add("--batch-frames", int(options.batch_frames or 0))
+    if options.batch_after:
+        add("--batch-after", options.batch_after)
+    # The friendly spellings first - they are what the panel sets and what a
+    # person reads back off the Copy button. --start-from is the general form
+    # and the only one that can carry a duration; it used to be missing, and a
+    # recipe saying "the last two days" had to raise here rather than quietly
+    # becoming "the whole run" and moving gigabytes nobody asked for.
+    if frames:
+        add("--last-n", frames)
+    elif first is not None:
+        add("--from-t", first)
+    elif options.start_from is not None:
+        add("--start-from", options.start_from)
+    if last is not None:
+        add("--to-t", last)
+    elif options.end_at is not None:
+        add("--end-at", options.end_at)
+    if options.layout == "split":
+        add("--split-channels")
+    elif options.layout == "ome":
+        add("--ome-tiff")
+    if options.composite_display:
+        add("--composite")
+    if options.include_last:
+        add("--include-last")
+    if options.safe_copy:
+        add("--safe-copy")
+    if options.channel_names:
+        add("--channel-names", ",".join(options.channel_names))
+        if no_pin:
+            add("--no-pin")
+    if options.pixel_size_um:
+        add("--pixel-size", options.pixel_size_um)
+    if options.interval_s:
+        add("--interval", options.interval_s)
+    if preset:
+        add("--preset", preset)
+    return argv
+
+
+def parse(argv):
+    """``parse_args`` that raises instead of exiting.
+
+    argparse prints a usage block and calls ``sys.exit``. A front end with no
+    console has nowhere to show that, and a ``SystemExit`` raised on a worker
+    thread kills the thread with no message at all.
+    """
+    # Through the same alias table as `main`, so a front end and a person
+    # typing at a prompt read the same argv.
+    argv = join_negative_values(resolve_alias(str(a) for a in argv))
+    trapped = io.StringIO()
+    try:
+        with contextlib.redirect_stderr(trapped):
+            return build_parser().parse_args(argv)
+    except SystemExit:
+        raise LV200Error("could not read this as a command:\n  pylv200 %s\n%s"
+                         % (" ".join(argv), trapped.getvalue().strip())) from None
+
+
+def _resolve_experiment(args):
+    """Turn a target into one Experiment, without fetching a tile.
+
+    The client is kept on the namespace: every verb that follows goes through
+    the same object, so `plan` then `sync` walks the share once rather than
+    twice.
+    """
+    source, name = parse_target(args.target)
+    client = LV200Client(source)
+    experiment = client._as_experiment(name)
+    args.source = source.name if config.load_sources().get(source.name) else None
+    args.client = client
+    return experiment
+
+
+#: What one position's outcome means to a caller that reads exit codes. A
+#: scheduled task treats all four differently, which is why the pull returns a
+#: word and only this module turns it into a number.
+_EXIT_FOR = {"written": 0, "dry_run": 0, "nothing_new": 1, "cancelled": STOPPED}
+
+
+def _exit_code(result):
+    """The exit code for a whole experiment's pull.
+
+    "Stopped with nothing written" is its own answer. Reporting it as 2 would
+    make a scheduled task treat a deliberate stop as a failure, and 1 would make
+    it read as "there was nothing to do".
+    """
+    codes = [_EXIT_FOR.get(one.status, 2) for one in result.positions]
+    if result.cancelled and 0 not in codes:
+        return STOPPED
+    return 0 if 0 in codes else (1 if codes else 2)
+
+
+def _pull_experiment(args, resume):
+    """Resolve the recipe, hand it to the engine, print what comes back.
+
+    The pull itself lives in `engine.pull_experiment`, which takes an
+    ExportOptions rather than this namespace and yields ProgressEvents rather
+    than printing. What is left here is the three things that are genuinely
+    command-line work: precedence, the settings home, and the exit code.
+    """
+    experiment = _resolve_experiment(args)
+    # Cleared before anything is resolved: --no-pin means these settings do not
+    # apply to this pull either, not merely that they stop applying afterwards.
+    _early, _source, key = _recipe(args, experiment.name)
+    unpinned = config.clear_override(key) if args.no_pin else False
+    opts, _source, key = _recipe(args, experiment.name)
+
+    # Whether the names were typed on THIS command line, which decides both how
+    # the pull describes them and whether it pins them.
+    typed = bool(getattr(args, "channel_names", None))
+    on_pin = ((lambda names: config.set_override(key, channel_names=list(names)))
+              if typed and not args.no_pin else None)
+    # A pinned name still wins - somebody chose it - but a disagreement usually
+    # means the reason for pinning has gone away. Not worth saying when the
+    # names were just typed: they are not the pinned ones.
+    on_conflict = ((lambda vsi_names: config.override_conflicts(key, vsi_names))
+                   if not typed else None)
+
+    _save_preset(args, opts)
+
+    result = args.client.fetch(
+        experiment, opts,
+        out=Path(args.out) if args.out else None,
+        dry_run=bool(getattr(args, "dry_run", False)),
+        resume=resume,
+        cancel=getattr(args, "cancel", None),
+        # A front end passes its own; the terminal gets a bar, or None when it
+        # is not a terminal, was told to be quiet, or is being captured.
+        progress=_progress(args),
+        on_say=say,
+        on_position=getattr(args, "on_position", None),
+        unpinned=unpinned, on_conflict=on_conflict, on_pin=on_pin,
+        channel_names_given=typed,
+        force_ndims=getattr(args, "ndims", None),
+        channel_count=getattr(args, "channel_count", None),
+        dtype=getattr(args, "dtype", None),
+        axes_override=getattr(args, "axes", None))
+
+    args.wrote = [one.payload or {} for one in result.positions]
+    args.result = result               # the watcher reads what this collected
+    emit(result.payload)
+    return _exit_code(result)
+
+def _save_preset(args, options):
+    """Write the resolved recipe out, if --save-preset asked for it.
+
+    Before a tile is read, so a run stopped halfway still leaves the recipe it
+    was going to use - which is the whole point of asking for it during a run
+    rather than composing one by hand afterwards.
+    """
+    where = getattr(args, "save_preset", None)
+    if not where:
+        return None
+    path = options.save(Path(where))
+    say("recipe written to %s" % path)
+    return path
+
+
+def cmd_pull(args):
+    return _pull_experiment(args, resume=getattr(args, "resume", False))
+
+
+def cmd_sync(args):
+    return _pull_experiment(args, resume=not args.no_resume)
+
+
+def cmd_watch(args):
+    out = Path(args.out) if args.out else None
+    log = (out / lv200watch.HEARTBEAT_FILENAME) if out else None
+
+    if args.status:
+        if log is None:
+            raise LV200Error("watch --status needs the -o folder the watcher "
+                             "writes into")
+        status = lv200watch.heartbeat_status(log, interval=args.poll_interval)
+        emit(status, ["  %s" % status["message"]] +
+             (["  %d poll(s), %d file(s) written, %d failure(s)"
+               % (status["polls"], status["files_written"], status["failures"])]
+              if status["found"] else []))
+        return 0 if status.get("found") and not status.get("stale") else 1
+
+    experiment = _resolve_experiment(args)
+    source, _ = parse_target(args.target)
+    opts = config.resolve_options(
+        cli=_given(args), key=config.experiment_key(source, experiment.name),
+        preset=args.preset, source=source)
+    if not opts.channel_names and experiment.channel_names:
+        opts = opts.replace(channel_names=tuple(experiment.channel_names))
+
+    # The run's own cadence is the natural floor for the poll interval; there
+    # is nothing to find between two frames. Taken from the recipe, so a preset
+    # can carry "collect this run a week at a time".
+    # A given --interval IS the run's frame interval, so it wins over one
+    # derived from timestamps. It used to be ignored here, which only went
+    # unnoticed because the derived value was itself always None.
+    frame_interval = opts.interval_s or _frame_interval(experiment)
+    interval = opts.poll_interval_s or max((frame_interval or 1800.0) / 2.0, 60.0)
+
+    def fetch(_experiment):
+        # `watch` has no --dry-run and no --resume of its own: it always
+        # collects, and always through the ledger, which is what makes a held
+        # chunk safe to hold.
+        args.dry_run = False
+        args.sink = []
+        _pull_experiment(args, resume=True)
+        return [w["path"] for one in getattr(args, "wrote", ())
+                for w in one.get("written", ())]
+
+    watcher = args.client.watch(
+        experiment, opts, interval=interval, pull=fetch,
+        store=(StateStore.for_output(out, scope=opts.state_scope)
+               if out else None),
+        frame_interval=frame_interval, heartbeat=log,
+        on_poll=lambda r: _say_poll(r, interval),
+        # No thread: `watch` on the command line IS the foreground, and Ctrl-C
+        # is how it stops. A caller with something else to do meanwhile gets a
+        # thread from `client.watch(start=True)` instead.
+        start=False)
+
+    # A front end with a Stop button needs the watcher itself, so it can ask
+    # what is being held once polling has stopped. Nothing on the command line
+    # sets this.
+    took = getattr(args, "on_watcher", None)
+    if took:
+        took(watcher)
+
+    if args.flush:
+        result = watcher.flush()
+        emit({"flushed": [str(p) for p in result.wrote]})
+        return 0 if result.wrote else 1
+
+    say("watching %s every %s, holding until %s"
+        % (experiment.name, _mins(interval), opts.batch_description()))
+    if args.once:
+        result = watcher.poll()
+        emit(result.to_dict())
+        return 0 if result.wrote else (2 if not result.reachable else 1)
+
+    say("  Ctrl-C to stop. %s records every poll." % (log or "nothing"))
+    # The caller's own stop event when there is one - a window's Stop button
+    # cannot press Ctrl-C.
+    stop = getattr(args, "stop", None) or threading.Event()
+    try:
+        polls = watcher.run(stop_event=stop)
+    except KeyboardInterrupt:
+        stop.set()
+        say("\n  stopping - writing whatever is held")
+        polls = [watcher.flush()]
+    finally:
+        # Nothing here runs on a thread, but a caller's `on_watcher` may have
+        # started one, and a daemon thread mid-write when the interpreter exits
+        # leaves a torn file.
+        if watcher.is_running:
+            watcher.stop(wait=True)
+    emit({"polls": [p.to_dict() for p in polls]})
+    return 0 if any(p.wrote for p in polls) else 1
+
+
+def _scan_index(experiment):
+    """Which timepoints each position holds, and which parts are still open.
+
+    Headers and chunk tables only - never a tile. `scans` prints this, and
+    `_frame_interval` divides by it.
+    """
+    holders, live = {}, set()
+    for pos in experiment.positions:
+        metas = []
+        for path in pos.paths:
+            try:
+                metas.append(engine.parse_ets(path))
+            except (LV200Error, OSError, ValueError):
+                continue
+        if not metas:
+            continue
+        meta = engine.merge_parts(metas)
+        dims = meta.get("dims")
+        axes = engine.assign_axes(meta, dims[2] if dims and len(dims) > 2
+                                  else None)
+        if any(engine.is_open_part(m) for m in metas):
+            live.add(pos.name)
+        for t in engine.timepoints_in(meta, axes):
+            holders.setdefault(t, set()).add(pos.name)
+    return holders, live
+
+
+def _frame_interval(experiment, timepoints=None):
+    """Seconds between frames, from the run's own start and its newest write.
+
+    Divides by the number of TIMEPOINTS, not the number of parts. cellSens only
+    splits a long acquisition into parts occasionally, so a position with one
+    part and three hundred timepoints divided by one and yielded no interval at
+    all - which pushed `batch_after` onto its last-resort clock, the one that
+    restarts the wait every time the watcher restarts.
+    """
+    paths = [p for pos in experiment.positions for p in pos.paths]
+    if not paths:
+        return None
+    if timepoints is None:
+        timepoints = _scan_index(experiment)[0]
+    return derive_interval(paths, max(len(timepoints), 1),
+                           started=experiment.started)
+
+
+def _mins(seconds):
+    return ("%.0f s" % seconds if seconds < 120
+            else "%.0f min" % (seconds / 60.0))
+
+
+def _say_poll(result, interval):
+    if result.wrote:
+        say("  %s  wrote %d file(s)" % (_stamp(result.at), len(result.wrote)))
+    elif not result.reachable:
+        say("  %s  unreachable: %s  (retrying in %s)"
+            % (_stamp(result.at), result.error, _mins(result.backoff)))
+    elif result.waiting:
+        say("  %s  holding %d timepoint(s)" % (_stamp(result.at),
+                                               result.waiting))
+    else:
+        say("  %s  nothing new" % _stamp(result.at))
+
+
+def _stamp(at):
+    return datetime.fromtimestamp(at).strftime("%H:%M:%S")
+
+
+def cmd_preview(args):
+    experiment = _resolve_experiment(args)
+    names, source = list(experiment.channel_names or ()), "vsi"
+    key = config.experiment_key(parse_target(args.target)[0], experiment.name)
+    pinned = config.get_override(key).get("channel_names")
+    if pinned:
+        names, source = list(pinned), "pinned"
+
+    # Through the same precedence as a pull, so `preview --preset nightly`
+    # shows the channels `sync --preset nightly` would write rather than all of
+    # them - a preview of the wrong channels answers a question nobody asked.
+    opts, _source, _key = _recipe(args, experiment.name)
+
+    preview = args.client.preview(
+        experiment, lo=args.stretch[0], hi=args.stretch[1],
+        project=args.project, names=names, name_source=source,
+        channels=list(opts.channels) if opts.channels else None,
+        progress=_progress(args))
+
+    images = preview.images()
+    say("read %d tile(s) for %d position(s)"
+        % (preview.reads, len(preview.positions)))
+
+    written = []
+    out = Path(args.out) if args.out else None
+    if out:
+        out.mkdir(parents=True, exist_ok=True)
+        for image in images:
+            dest = out / ("%s_C%d.png" % (image.position, image.channel))
+            written.append(lv200preview.save_png(image, dest))
+        if not args.no_sheet:
+            sheet = out / "contact-sheet.png"
+            lv200preview.contact_sheet(images, sheet, title=experiment.name)
+            written.append(sheet)
+
+    lines = []
+    for image in images:
+        note = ("mean of %d frames" % len(image.frames) if image.projected
+                else "t=%d" % (image.frames[0] if image.frames else 0))
+        lines.append("  %-40s %s  %s" % (image.label, note,
+                                         image.stats.get("kind", "")))
+    for path in written:
+        lines.append("  wrote %s" % path.name)
+    emit({"experiment": experiment.name, "tiles_read": preview.reads,
+          "images": [{"position": i.position, "channel": i.channel,
+                      "name": i.channel_name, "name_source": i.name_source,
+                      "frames": list(i.frames), "projected": i.projected,
+                      "kind": i.stats.get("kind", ""),
+                      "vrange": list(i.vrange)} for i in images],
+          "written": [str(p) for p in written]}, lines)
+    return 0 if images else 1
+
+
+def cmd_timeline(args):
+    """Read and optionally save only the anchors admitted by one byte budget."""
+    experiment = _resolve_experiment(args)
+    names = list(experiment.channel_names or ())
+    key = config.experiment_key(parse_target(args.target)[0], experiment.name)
+    pinned = config.get_override(key).get("channel_names")
+    if pinned:
+        names = list(pinned)
+    kinds = {
+        index: ("bioluminescence" if "lum" in str(name).lower() else "other")
+        for index, name in enumerate(names)
+    }
+    budget = max(0, int(float(args.budget_mib) * (1 << 20)))
+    source = args.client.timeline(
+        experiment,
+        names=names,
+        byte_budget=budget,
+        projection_frames=max(1, int(args.project)),
+        channel_kinds=kinds,
+        classify=not bool(names),
+        preview_cache=args.preview_cache,
+        persist=not args.no_proxy,
+        local=args.local,
+        mirror=args.mirror,
+    )
+    written = []
+    frames = []
+    try:
+        positions = source.position_names
+        position = str(args.position) if args.position else (
+            positions[0] if positions else None)
+        if position not in positions:
+            raise InvalidSelection(
+                "no position %r; choose one of %s" % (
+                    position, ", ".join(positions) or "none"))
+        channels = source.channels_for(position)
+        channel = int(args.channel) if args.channel is not None else (
+            channels[0] if channels else None)
+        if channel not in channels:
+            raise InvalidSelection(
+                "%s has no channel %r; choose one of %s" % (
+                    position, channel,
+                    ", ".join("C%d" % value for value in channels) or "none"))
+        anchors = source.initial_indices(
+            byte_budget=budget, position=position, channel=channel)
+        for index in anchors:
+            frames.append(source.get_frame(
+                position, channel, index, lo=args.stretch[0],
+                hi=args.stretch[1], prefetch=False))
+
+        if args.out:
+            out = Path(args.out)
+            out.mkdir(parents=True, exist_ok=True)
+            safe_position = re.sub(
+                r"[^A-Za-z0-9._-]+", "_", position).strip("_") or "position"
+            for frame in frames:
+                path = out / ("%s_C%d_t%d.png" % (
+                    safe_position, channel, frame.timepoint))
+                path.write_bytes(lv200preview.encode_png(frame.array))
+                written.append(path)
+
+        hits = source.cache_hits + getattr(source, "proxy_hits", 0)
+        lines = [
+            "Time preview: %d anchors, %d source tiles, %s read, "
+            "%d cache hits, %s" % (
+                len(anchors), source.source_reads,
+                human_bytes(source.source_bytes), hits,
+                source.active_provider)
+        ]
+        lines.extend("  wrote %s" % path.name for path in written)
+        emit({
+            "experiment": experiment.name,
+            "position": position,
+            "channel": channel,
+            "anchors": list(anchors),
+            "timepoints": [frame.timepoint for frame in frames],
+            "source_tiles": source.source_reads,
+            "source_bytes": source.source_bytes,
+            "cache_hits": hits,
+            "provider": source.active_provider,
+            "written": [str(path) for path in written],
+        }, lines)
+        return 0 if frames else 1
+    finally:
+        source.close()
+
+
+def cmd_gui(args):
+    """The desktop app.
+
+    Imported here and nowhere else. Importing it at module level would make
+    `pylv200 list` on a headless machine depend on a window system, and Tk is
+    the one dependency this package cannot assume.
+    """
+    from .gui.app import run
+
+    return run(target=getattr(args, "target", None),
+               dark=getattr(args, "dark", None))
+
+
+def cmd_manifest(args):
+    folder = Path(args.folder)
+    path = folder / MANIFEST_FILENAME
+    if not path.is_file():
+        raise NoDatasetFound("no %s in %s - that folder was not written by a "
+                             "pull" % (MANIFEST_FILENAME, folder))
+    data = json.loads(path.read_text(encoding="utf-8"))
+    files = data.get("files", [])
+    lines = ["  %s" % (data.get("experiment") or folder.name),
+             "  written        %s" % data.get("generated_at", "?"),
+             "  files          %d" % len(files)]
+    for record in data.get("channels", []):
+        lines.append("  C%-13d %-24s (%s)"
+                     % (record.get("index", 0), record.get("name", "?"),
+                        record.get("source", "?")))
+    for record in files:
+        lines.append("  %-30s T=%s %s"
+                     % (Path(record.get("path", "?")).name,
+                        len(record.get("timepoints", [])),
+                        record.get("format", "")))
+    emit(data, lines)
+    return 0
+
+
+def cmd_preset(args):
+    if args.name and args.delete:
+        removed = config.remove_preset(args.name)
+        emit({"deleted": args.name, "existed": removed},
+             ["  %s %s" % (args.name, "removed" if removed else "was not saved")])
+        return 0 if removed else 1
+    if args.name and args.save:
+        options = config.resolve_options(cli=_given(args))
+        config.save_preset(args.name, options)
+        _save_preset(args, options)    # `--save-preset` writes the file too
+        emit({"saved": args.name, "options": options.to_dict()},
+             ["  saved %s" % args.name])
+        return 0
+    if not args.name and getattr(args, "save_preset", None):
+        # A recipe file with no name in the store: the shape a pipeline commits
+        # beside its analysis code, where the name would mean nothing.
+        options = config.resolve_options(cli=_given(args))
+        _save_preset(args, options)
+        emit({"options": options.to_dict()}, [])
+        return 0
+    if args.name:
+        options = config.get_preset(args.name)
+        emit({"preset": args.name, "options": options.to_dict()},
+             ["  %-16s %s" % (k, v) for k, v in
+              sorted(options.to_dict().items()) if v not in (None, "", ())])
+        return 0
+    presets = config.load_presets()
+    emit({"presets": {n: o.to_dict() for n, o in presets.items()}},
+         ["  %s" % n for n in sorted(presets)] or ["  no presets are saved"])
+    return 0 if presets else 1
+
+
+def _cmd_logout(args):
+    """Remove a source's stored credential. Never reads its value."""
+    source = config.get_source(args.source)
+    config.forget_credential(source)
+    say("removed whatever Windows held for %s.\n"
+        "  A pull will now be refused until `pylv200 login %s` runs again."
+        % (source.target, source.name))
+    return 0
+
+
+def cmd_status(args):
+    """What is reachable, what a watcher is doing, and what has been written.
+
+    PyIncucyte's `status` asks its instrument how it is. House rule 1 forbids
+    that here - nothing may reach into the microscope - so this reports the
+    three things PyLV200 can honestly know: whether each configured source
+    answers, what the watcher heartbeat in an output folder says, and how much
+    the resume ledger there holds.
+    """
+    payload = {"sources": [], "experiment": None, "watcher": None,
+               "ledger": None}
+    lines, problems = [], 0
+
+    if args.target and args.target in config.load_sources():
+        # A bare configured name is a SOURCE here. `parse_target` would read it
+        # as an experiment on the only source, which is right for `sync` and
+        # wrong for a command whose first argument is documented as a source.
+        name, sources = None, {args.target: config.get_source(args.target)}
+    elif args.target:
+        source, name = parse_target(args.target)
+        sources = {source.name: source}
+    else:
+        name = None
+        sources = config.load_sources()
+        if not sources:
+            raise LV200Error(
+                "no microscope is configured, so there is nothing to report "
+                "on.\n  Run `pylv200 setup` on the microscope, or give a path.")
+
+    for label in sorted(sources):
+        source = sources[label]
+        roots = source.reachable()
+        ok = bool(roots) and all(answered for _p, answered, _why in roots)
+        problems += 0 if ok else 1
+        payload["sources"].append(
+            {"name": label, "reachable": ok, "target": source.target,
+             "roots": [{"path": p, "reachable": a, "why": w}
+                       for p, a, w in roots]})
+        lines.append("  %-16s %s" % (label, "reachable" if ok else "UNREACHABLE"))
+        for path, answered, why in roots:
+            if not answered:
+                lines.append("      %s  -- %s" % (path, why or "did not answer"))
+
+    if name:
+        experiment = args.client.experiment(name) if hasattr(args, "client") \
+            else LV200Client(sources[next(iter(sources))]).experiment(name)
+        live = experiment.is_live
+        payload["experiment"] = {"name": experiment.name,
+                                 "positions": len(experiment.positions),
+                                 "live": bool(live)}
+        lines.append("  %-16s %d position(s), %s"
+                     % (experiment.name, len(experiment.positions),
+                        "being written now" if live else "not being written"))
+
+    out = Path(args.out) if args.out else None
+    if out:
+        # 900 s is the watcher's own default cadence; a heartbeat older than
+        # three of those is what `stale` means. Give -i when the watcher was
+        # started with a different one, or a slow poll reads as a dead watcher.
+        beat = lv200watch.heartbeat_status(
+            out / lv200watch.HEARTBEAT_FILENAME,
+            interval=args.poll_interval or 900.0)
+        payload["watcher"] = beat
+        lines.append("  %-16s %s" % ("watcher", beat["message"]))
+        if beat.get("found"):
+            lines.append("      %d poll(s), %d file(s) written, %d failure(s)"
+                         % (beat["polls"], beat["files_written"],
+                            beat["failures"]))
+        if beat.get("found") and beat.get("stale"):
+            problems += 1
+
+        ledger = StateStore.for_output(out).summary()
+        payload["ledger"] = ledger
+        lines.append("  %-16s %d timepoint(s) across %d position(s)%s"
+                     % ("ledger", ledger["entries"], ledger["positions"],
+                        "" if ledger["exists"] else "   (no ledger written yet)"))
+        for one in ledger["experiments"]:
+            lines.append("      %s" % one)
+
+    emit(payload, lines)
+    # 1, not 2: "something is not healthy" is an answer, not a failure to
+    # answer. A scheduled task treats them differently.
+    return 0 if not problems else 1
+
+
+def cmd_scans(args):
+    """List the timepoints one run holds, and when each was acquired.
+
+    Named `scans` for PyIncucyte parity. `timepoints` is a hidden alias,
+    because a *timepoint* is what `--from-t`, the resume ledger and the
+    manifest column all call the same thing - the two words mean one thing
+    here, and this is the one place the PyIncucyte spelling wins.
+
+    Reads headers and chunk tables only. Never a tile.
+    """
+    experiment = _resolve_experiment(args)
+    holders, live = _scan_index(experiment)
+    interval = _frame_interval(experiment, holders)
+
+    if not holders:
+        raise NoDatasetFound("no readable .ets part under %s" % experiment.folder)
+
+    rows = engine.timepoint_times(sorted(holders), started=experiment.started,
+                                  interval_s=interval)
+    newest = rows[-1][0] if rows else None
+    every = len(experiment.positions)
+
+    lines = ["", "=== Scans for %s ===" % experiment.name, ""]
+    for t, when in rows:
+        held = len(holders[t])
+        note = "" if held == every else "   (%d of %d position(s))" % (held, every)
+        if t == newest and live:
+            # The same reasoning as --include-last: the newest tile may be
+            # mid-write, so a pull drops it unless asked not to.
+            note += "   still being acquired"
+        lines.append("  %-6d %s%s"
+                     % (t, when.strftime("%Y-%m-%d %H:%M:%S") if when
+                        else "time not known", note))
+    lines.append("")
+    lines.append("%d scan%s%s" % (len(rows), "" if len(rows) == 1 else "s",
+                                  "" if interval is None else
+                                  "; times derived from the run start and a "
+                                  "%.1f min interval" % (interval / 60.0)))
+
+    # The JSON keeps the recipe's own vocabulary: a pipeline reading this also
+    # reads the manifest, where the column is `timepoints`.
+    emit({"experiment": experiment.name,
+          "timepoints": [t for t, _ in rows],
+          "times": [w.isoformat() if w else None for _, w in rows],
+          "interval_s": interval,
+          "interval_derived": interval is not None,
+          "positions": {str(t): sorted(holders[t]) for t, _ in rows},
+          "live": sorted(live)}, lines)
+    return 0 if rows else 1
+
+
+COMMANDS = {
+    "setup": _cmd_setup, "probe": _cmd_probe, "login": _cmd_login,
+    "logout": _cmd_logout, "status": cmd_status, "scans": cmd_scans,
+    "rescan": _cmd_rescan, "sources": cmd_sources, "list": cmd_list,
+    "find": cmd_find, "plan": cmd_plan, "pull": cmd_pull, "sync": cmd_sync,
+    "watch": cmd_watch, "preview": cmd_preview, "timeline": cmd_timeline,
+    "gui": cmd_gui,
+    "manifest": cmd_manifest,
+    "preset": cmd_preset,
+}
+
+#: Accepted but hidden from --help, so each job has one obvious name.
+#: `download` and `vessels` are PyIncucyte's spellings, so muscle memory built
+#: on the sister package works here. `timepoints` is this package's own word
+#: for what `scans` lists - the manifest column, the ledger key and `--from-t`
+#: all say timepoint - and `scans` is the one place a PyIncucyte name wins,
+#: because a scan is a real event on this instrument too.
+#:
+#: Rewritten in argv rather than registered as extra subparsers, so `VERB_FLAGS`
+#: keeps naming exactly one verb per job. The desktop app builds argv against
+#: that table, and a gap in it is how two front ends start disagreeing.
+ALIASES = {"download": "sync", "vessels": "list", "timepoints": "scans"}
+
+#: PyIncucyte commands with no counterpart here, and why. Both write to the
+#: instrument or process pixels with device coefficients an LV200 has none of.
+UNAVAILABLE = {
+    "scan-now": "pylv200 never commands the microscope - it is read-only, "
+                "which is what makes it safe to run against a live experiment. "
+                "Start the acquisition in cellSens.",
+    "unmix": "there is no spectral unmixing here. LV200 channels are separate "
+             "detector channels, and the Scale and Bias coefficients an unmix "
+             "needs come from the device.",
+    "calibrate": "there are no device-supplied calibration coefficients on an "
+                 "LV200. Give --pixel-size and --interval instead.",
+}
+
+
+#: Flags whose value can legitimately begin with a minus sign. argparse sees a
+#: leading "-" and calls it an option, so `--start-from -48h` fails with
+#: "expected one argument" - a message that names the flag and not the problem.
+#: Only these three, and only when the next token really looks like a signed
+#: amount: `--positions` takes nargs="+" and a position genuinely named "-48h"
+#: must still reach it.
+NEGATIVE_VALUE_FLAGS = {"--start-from", "-s", "--end-at"}
+_NEGATIVE_VALUE = re.compile(r"^-\d+(?:\.\d+)?\s*[smhdwf]", re.IGNORECASE)
+
+
+def join_negative_values(argv):
+    """Rewrite ``--start-from -48h`` as ``--start-from=-48h`` before parsing.
+
+    `=`-joined, argparse never has to decide whether the token is an option.
+    Applied by `parse` and by `main` both, or the desktop app and a prompt
+    disagree about exactly the window forms the panel can set.
+    """
+    fixed, index = [], 0
+    while index < len(argv):
+        token = argv[index]
+        following = argv[index + 1] if index + 1 < len(argv) else None
+        if (token in NEGATIVE_VALUE_FLAGS and following
+                and _NEGATIVE_VALUE.match(following)):
+            fixed.append("%s=%s" % (token, following))
+            index += 2
+            continue
+        fixed.append(token)
+        index += 1
+    return fixed
+
+
+def resolve_alias(argv):
+    """Rewrite a PyIncucyte verb into this package's, in place of argv[0].
+
+    The global flags are all switches, so the first token that is not a flag is
+    the verb.
+    """
+    argv = list(argv)
+    for index, token in enumerate(argv):
+        if token.startswith("-"):
+            continue
+        if token in ALIASES:
+            argv[index] = ALIASES[token]
+        break
+    return argv
+
+
+def configure_logging(args):
+    """Wire --verbose and --quiet to the `pylv200` logger.
+
+    stderr, always: stdout belongs to the payload under --json, and a log line
+    on it corrupts whatever is parsing that.
+    """
+    level = (logging.DEBUG if getattr(args, "verbose", False) else
+             logging.WARNING if getattr(args, "quiet", False) else logging.INFO)
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(logging.Formatter("%(message)s"))
+    log = logging.getLogger("pylv200")
+    log.handlers = [handler]
+    log.setLevel(level)
+    return log
+
+
+#: The flat flags this used to take, and what to type instead. Jamie has been
+#: typing the old form all week; an unrecognised flag should say what replaced
+#: it rather than print a usage block.
+MIGRATED = {
+    "--input": "pull <target>  (or `pull \"D:\\path\\_Exp_\"`)",
+    "--split-channels": "pull ... --split-channels   (unchanged, on `pull`)",
+    "--no-resume": "pull   (which ignores the ledger; `sync` uses it)",
+}
+
+
+def main(argv=None):
+    """Entry point. Returns an exit code; raises nothing the user should see."""
+    argv = join_negative_values(
+        resolve_alias(sys.argv[1:] if argv is None else argv))
+    verb = next((t for t in argv if not t.startswith("-")), "")
+    if verb in UNAVAILABLE:
+        print("pylv200 has no `%s`, and will not gain one:\n  %s"
+              % (verb, UNAVAILABLE[verb]), file=sys.stderr)
+        return 2
+    # Taken from the parser itself rather than a hand-kept list: a global flag
+    # added later would otherwise be greeted by the migration message.
+    globals_ = {opt for action in build_parser()._actions
+                for opt in action.option_strings}
+    if argv and argv[0].startswith("--") and argv[0] not in globals_:
+        flag = argv[0].split("=")[0]
+        print("pylv200 now takes a subcommand.\n  %s -> pylv200 %s\n"
+              "  Try `pylv200 --help`, or `pylv200 list` to see what is there."
+              % (flag, MIGRATED.get(flag, "pull <target> %s ..." % flag)),
+              file=sys.stderr)
+        return 2
+
+    args = build_parser().parse_args(argv)
+    _JSON[0] = bool(getattr(args, "json", False))
+    configure_logging(args)
+    try:
+        return COMMANDS[args.command](args)
+    except LV200Error as exc:
+        print(exc, file=sys.stderr)
+        return 2
+    finally:
+        # A pull that raised part-way never reached its `done` event, and the
+        # half-drawn bar would otherwise be the last thing on screen, under
+        # whatever the shell printed next.
+        if _BAR[0] is not None:
+            _BAR[0].clear()
+            _BAR[0] = None
+
+
+if __name__ == "__main__":
+    sys.exit(main())