sessionmail 0.2.0__tar.gz → 0.2.1__tar.gz

{sessionmail-0.2.0 → sessionmail-0.2.1}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "sessionmail",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Mail for coding agents: message moves messages, pager alerts, memory is the filesystem view - three commands over one maildir.",
   "author": {
     "name": "Mike Bailey",

{sessionmail-0.2.0 → sessionmail-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sessionmail
-Version: 0.2.0
+Version: 0.2.1
 Summary: sessionmail - mail for coding agents: message, pager and memory over one maildir.
 Project-URL: Homepage, https://github.com/sessionkit/sessionmail
 Project-URL: Repository, https://github.com/sessionkit/sessionmail
@@ -104,16 +104,6 @@ message setup                    # again: it links the notmuch hook
 - **Nothing runs `notmuch new` for you.** `message mark` and `memory`
   read an empty index until something does: launchd, cron, or by hand.
 
-**Status.** `sessionmail` 0.0.1 on PyPI is a name reservation, not this
-code - a 1.3 KB placeholder with no dependencies.
-Until 0.2.0 ships, install from source instead of the `uv tool install
-sessionmail` line above:
-
-```sh
-uv tool install git+https://github.com/sessionkit/sessionmail   # from the repo
-make install                                                    # from a clone
-```
-
 `message`, `pager` and `memory` all run; the specs, in the git repository
 (the release archive leaves them out), say what each verb is meant to do
 and `make progress` counts how much of it is built.

{sessionmail-0.2.0 → sessionmail-0.2.1}/README.md

@@ -85,16 +85,6 @@ message setup                    # again: it links the notmuch hook
 - **Nothing runs `notmuch new` for you.** `message mark` and `memory`
   read an empty index until something does: launchd, cron, or by hand.
 
-**Status.** `sessionmail` 0.0.1 on PyPI is a name reservation, not this
-code - a 1.3 KB placeholder with no dependencies.
-Until 0.2.0 ships, install from source instead of the `uv tool install
-sessionmail` line above:
-
-```sh
-uv tool install git+https://github.com/sessionkit/sessionmail   # from the repo
-make install                                                    # from a clone
-```
-
 `message`, `pager` and `memory` all run; the specs, in the git repository
 (the release archive leaves them out), say what each verb is meant to do
 and `make progress` counts how much of it is built.

{sessionmail-0.2.0 → sessionmail-0.2.1}/scripts/seat-agent/README.md

@@ -9,6 +9,8 @@ through `message`, which keeps the package at three commands:
 
     message seat init --registry DIR ADDRESS     mint the seat's key (was scripts/seat-init)
     message seat agent ADDRESS [SOCKET]          run its agent (was scripts/seat-agent/seat-agent)
+    message seat agent --install ADDRESS [SOCKET]   render and load the LaunchAgent
+    message seat agent --uninstall ADDRESS           unload it and remove its plist
     message seat agent --template                print the LaunchAgent template
 
 The `seat` noun is hidden from `message --help` and from the MCP tools; `message
@@ -48,8 +50,14 @@ seat --help` answers when typed.
 
 ## The template
 
+`message seat agent --install ADDRESS [SOCKET]` renders it, writes it into
+`~/Library/LaunchAgents`, loads it with `launchctl bootstrap`, and checks that the agent
+answers. `--uninstall ADDRESS` boots it out and removes the plist. Their contract
+(output, exits, the `Capability: install` marker) is in
+[`docs/message-seat.md`](../../docs/message-seat.md).
+
 `message seat agent --template` prints it, and nothing else: it never renders it, loads
-it or runs launchctl. Render it by replacing each `@PLACEHOLDER@`, then lint it:
+it or runs launchctl. To render it by hand, replace each `@PLACEHOLDER@`, then lint it:
 
     message seat agent --template |
       sed -e 's|@ADDRESS@|bot.alice|g' -e "s|@MESSAGE@|$(command -v message)|g" \
@@ -68,9 +76,9 @@ ProgramArguments renders to `message seat agent ADDRESS SOCKET`. The placeholder
 On a host that runs `message` from an editable checkout, merging there changes the
 seat's agent at its next start.
 
-**Installing it is not done here.** Writing the plist into `~/Library/LaunchAgents` and
-running `launchctl bootstrap` is the host operator's act, by hand. No
-test and no make target in this repo does either.
+**No test and no make target loads a job on the real launchd.** The suite runs
+`--install` against a fake `launchctl` (`SESSIONMAIL_LAUNCHCTL`). A live install is the
+host operator's act: `message seat agent --install`, or the hand render above.
 
 ## The adapter's env (an example; the adapter owns it)
 

{sessionmail-0.2.0 → sessionmail-0.2.1}/src/sessionmail/_birth.py

@@ -68,6 +68,19 @@ SUBSCRIBE_VAR = "SESSIONMAIL_SUBSCRIBE"
 #: one: the detached generator's line.
 BORN_FILE = "born"
 
+#: What a generator line says on a mail-drop host, suffix or none: the drop
+#: builds no maps, so no generator runs there (`_seat._run_generator`'s own
+#: words for it; `tests/test_birth.py` holds the two equal).
+DROP_REGEN = "generator not run: the carrier is the mail drop; it reads the maps per send"
+
+
+def _on_drop(env: Mapping[str, str] | None) -> bool:
+    """Whether the carrier is the mail drop. Decides what a generator line
+    SAYS, never what runs."""
+    from . import _settings
+    return _settings.carrier(env).kind == "drop"
+
+
 #: Who births when the caller does not say: the subscription journal's `argv`.
 VIA_LISTEN = "pager listen"
 
@@ -350,13 +363,19 @@ def ensure_session_box(session: str, seat: "Seat | None", *,
                                   f"{stale}, left by an earlier run of this session; its row "
                                   f"goes at the next regen")
     if has_session and seat is not None:
-        live, why = _seat.doorbell(seat.address, session, env)
+        if detach and _settings.carrier(env).kind == "drop":
+            # The drop's doorbell runs the generator (`_drop.prepare`), and a
+            # detaching call never waits on it; the listen asks instead.
+            live, why = None, "not measured at session start; the first pager listen measures it"
+        else:
+            live, why = _seat.doorbell(seat.address, session, env)
         regen_said = ""
         if (birth.born or live is False) and detach:
             _detach(birth, session, env, root, record_source)
             regen_said = birth.regen_line
         elif (birth.born or live is False) and birth.suffix_unknown:
-            regen_said = "generator NOT run (MagicDNS suffix unknown)"
+            regen_said = (DROP_REGEN if _on_drop(env)
+                          else "generator NOT run (MagicDNS suffix unknown)")
         elif birth.born or live is False:
             regen_said = _seat.regen_maps(root, env=env)
             birth.regen, birth.regen_line = "ran", regen_said
@@ -384,7 +403,8 @@ def ensure_session_box(session: str, seat: "Seat | None", *,
         # included: the whole generator, detached, routes the boxes too.
         _detach(birth, session, env, root, record_source)
     elif owed and birth.suffix_unknown:
-        birth.sub_lines.append("  map        : NOT rebuilt - MagicDNS suffix unknown; the "
+        birth.sub_lines.append(f"  map        : {DROP_REGEN}" if _on_drop(env) else
+                               "  map        : NOT rebuilt - MagicDNS suffix unknown; the "
                                "subscriptions stand, and the next rebuild with a suffix "
                                "routes them")
     elif owed:
@@ -429,8 +449,11 @@ def _main(argv: list[str] | None = None) -> int:
         # The hook did not ask for the suffix (it costs the hook's
         # budget), so the child asks, and never runs the generator without
         # one: the record's line 2 says so instead.
+        # On a mail-drop host no generator runs either way, so the line
+        # names the carrier, not the suffix.
         suffix, why = _magicdns.lookup()
         line = (_seat.regen_maps(Path(args.regen)) if suffix is not None
+                else DROP_REGEN if _on_drop(None)
                 else f"generator NOT run (MagicDNS suffix unknown: {why})")
     except Exception as exc:  # noqa: BLE001 - regen_maps never raises; a child that dies says why
         line = f"generator failed in the background: {exc}"
@@ -443,8 +466,8 @@ def _main(argv: list[str] | None = None) -> int:
     return 0
 
 
-__all__ = ["BORN_FILE", "SUBSCRIBE_VAR", "Birth", "BornRecord", "birth_subscriptions", "born_record",
-           "detach_regen", "ensure_session_box", "read_born"]
+__all__ = ["BORN_FILE", "DROP_REGEN", "SUBSCRIBE_VAR", "Birth", "BornRecord", "birth_subscriptions",
+           "born_record", "detach_regen", "ensure_session_box", "read_born"]
 
 
 if __name__ == "__main__":

{sessionmail-0.2.0 → sessionmail-0.2.1}/src/sessionmail/_drop.py

@@ -132,6 +132,11 @@ class Maps:
     #: The domain a bare From is qualified with (`origin`); set by the
     #: sender's drop pre-flight, empty when nothing asked.
     origin: str = ""
+    #: Why the generator refused the alias print (`generator exit N: its
+    #: last stderr line`), set by `prepare`; empty when it printed. The
+    #: alias map is then empty, and a reader that must tell "no row" from
+    #: "no map" (the doorbell) reads this.
+    alias_refused: str = ""
 
 
 def selected(env: Mapping[str, str]) -> bool:
@@ -183,16 +188,18 @@ def origin(env: Mapping[str, str], host: str, notes: list[str] | None = None) ->
     - Else the FQDN from the ONE suffix definition (`_magicdns`), the form
       postfix writes when `myorigin = $myhostname`, and a form
       `_voice.host_forms` accepts.
-    - Else the short host, said in NOTES: the real generator refuses with
-      no suffix before the drop gets here, so only a generator that asks
-      for none (a test's fake) reaches it."""
+    - Else the short host. A host with no tailnet gets here on every send
+      (the generator's no-fqdn rows), and there the short host is right, so
+      nothing is said (`_magicdns.drop_without_tailnet`). Any other host
+      (a malformed operator suffix, or a tailscale that is there but does
+      not answer) is said in NOTES."""
     given = (env.get(ORIGIN_VAR) or "").strip() or _settings.file_text("postfix.origin", env)
     if given:
         return given
     found, _why = _magicdns.lookup(env)
     if found:
         return f"{host}.{found}"
-    if notes is not None:
+    if notes is not None and not _magicdns.drop_without_tailnet(env):
         notes.append(f"⚠  {_magicdns.UNKNOWN} - a bare From is qualified with the short "
                      f"host only (@{host})")
     return host
@@ -308,9 +315,9 @@ def prepare(env: Mapping[str, str]) -> Maps:
     if done.returncode == 0:
         maps.alias = _rows(done.stdout)
     else:
-        maps.notes.append(f"⚠  no alias map (generator exit {done.returncode}: "
-                          f"{_last(done.stderr)}) - seat mail lands in the seat's own box "
-                          "only; no session box gets its doorbell copy")
+        maps.alias_refused = f"generator exit {done.returncode}: {_last(done.stderr)}"
+        maps.notes.append(f"⚠  no alias map ({maps.alias_refused}) - seat mail lands in the "
+                          "seat's own box only; no session box gets its doorbell copy")
     return maps
 
 

sessionmail-0.2.1/src/sessionmail/_launchd.py

@@ -0,0 +1,426 @@
+"""The seat agent's LaunchAgent: render it, load it, unload it.
+
+`message seat agent --install ADDRESS [SOCKET]` and `--uninstall ADDRESS`.
+A seat with no Claude session (a bot) signs through its own ssh-agent, and
+that agent has to come back after a reboot: launchd keeps it alive. This
+module renders the packaged template (`seat/seat-agent.plist.template`),
+writes it into `~/Library/LaunchAgents`, loads it with `launchctl
+bootstrap`, and checks the effect: the agent answers on its socket and
+holds seat.pub's key. `--uninstall` boots the job out and removes the plist.
+It never touches the key, the registry or the cert.
+
+Streams and exits follow `seat init`'s convention:
+
+- stdout: the success report only (`--install`'s KEY=VALUE lines).
+- stderr: narration, refusals (`REFUSED - ... Nothing was written.`) and
+  failures (`FAILED - ...`, naming what was put back).
+- 0 done · 1 launchctl failed, a plist write or removal failed, or the
+  agent never answered, rolled back · 2 usage or refused, nothing written.
+
+`launchctl` is `$SESSIONMAIL_LAUNCHCTL` when set and not empty, else
+`/bin/launchctl`: the same seam as `SESSIONMAIL_SENDMAIL`. The test suite
+points it at a fake for every test, so no test reaches the real launchd.
+"""
+
+from __future__ import annotations
+
+import os
+import plistlib
+import re
+import shlex
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+from dataclasses import dataclass
+from typing import IO, Mapping
+from xml.sax.saxutils import escape
+
+PROG = "message seat agent"
+
+EX_OK = 0
+EX_FAILED = 1
+EX_REFUSED = 2
+
+#: The seam: a launchctl of the caller's choosing (a test's fake).
+LAUNCHCTL_VAR = "SESSIONMAIL_LAUNCHCTL"
+DEFAULT_LAUNCHCTL = "/bin/launchctl"
+
+#: The kit's launchd family for mail, as the template's Label has it.
+LABEL_PREFIX = "dev.sessionkit.mail.seat-agent."
+#: The wrapper's own rules (seat/seat-agent): the address, and the socket
+#: cap. macOS's sun_path is 104 bytes with its NUL.
+ADDRESS_RE = re.compile(r"^[a-z0-9][a-z0-9._-]*$")
+SOCK_MAX = 103
+PLACEHOLDER = re.compile(r"@([A-Z_]+)@")
+
+#: How long the agent has to answer after a load, and the job to go after
+#: a bootout. Module values, so a test can shorten them in-process.
+ANSWER_SECONDS = 10.0
+GONE_SECONDS = 5.0
+POLL_SECONDS = 0.1
+#: How many lines of the job's log a failure quotes.
+LOG_TAIL = 8
+
+#: The packaged template, beside this module's real path.
+TEMPLATE = os.path.join(os.path.dirname(os.path.realpath(__file__)), "seat",
+                        "seat-agent.plist.template")
+
+
+class Refused(Exception):
+    """Exit 2: usage or refused, nothing written."""
+
+
+class Failed(Exception):
+    """Exit 1: a tool failed; the message names what was put back."""
+
+
+@dataclass(frozen=True)
+class Job:
+    address: str
+    label: str
+    plist: str          # ~/Library/LaunchAgents/<label>.plist
+    socket: str
+    pub: str
+    key: str
+    log: str            # <log_dir>/seat-agent.<address>.log
+    log_dir: str
+    sessionmail_home: str
+    message: str        # `command -v message`, not resolved
+    domain: str         # gui/<uid>
+
+    @property
+    def target(self) -> str:
+        return f"{self.domain}/{self.label}"
+
+
+def label_for(address: str) -> str:
+    return LABEL_PREFIX + address
+
+
+def launchctl_path(env: Mapping[str, str]) -> str:
+    return env.get(LAUNCHCTL_VAR) or DEFAULT_LAUNCHCTL
+
+
+def launchctl(env: Mapping[str, str], *args: str) -> subprocess.CompletedProcess:
+    """Run launchctl ARGS (the seam's, else /bin/launchctl), output captured.
+    A launchctl that cannot be started is a Failed, before anything moves."""
+    path = launchctl_path(env)
+    try:
+        return subprocess.run([path, *args], capture_output=True, text=True,
+                              stdin=subprocess.DEVNULL, env=dict(env), check=False)
+    except OSError as exc:
+        raise Failed(f"launchctl could not run ({path}: {exc.strerror or exc})") from exc
+
+
+def _words(done: subprocess.CompletedProcess) -> str:
+    said = " ".join((done.stderr or done.stdout or "").split())
+    return f"rc {done.returncode}" + (f": {said}" if said else "")
+
+
+def _sessionmail_home(env: Mapping[str, str], home: str) -> str:
+    """As the wrapper reads it: $SESSIONMAIL_HOME, a leading ~ expanded, else
+    $HOME/.sessionmail. Absolute, as the template wants it."""
+    value = env.get("SESSIONMAIL_HOME") or os.path.join(home, ".sessionmail")
+    if value == "~" or value.startswith("~/"):
+        value = home + value[1:]
+    return os.path.abspath(value)
+
+
+def _check_platform() -> None:
+    if sys.platform != "darwin":
+        raise Refused(f"launchd only: this is {sys.platform}, not macOS; run "
+                      f"`{PROG} ADDRESS [SOCKET]` under your own service manager")
+
+
+def _check_address(address: str) -> None:
+    if "+" in address:
+        raise Refused(f"'{address}' has a '+': a seat is named with a dot (bot.alice), "
+                      "as `message seat init` mints it")
+    if not ADDRESS_RE.match(address):
+        raise Refused(f"'{address}' is not a seat address")
+
+
+def _home(env: Mapping[str, str]) -> str:
+    home = env.get("HOME", "")
+    if not os.path.isabs(home):
+        raise Refused("HOME is unset or not absolute: the LaunchAgent lives under "
+                      "$HOME/Library/LaunchAgents")
+    return home
+
+
+def plan(address: str, socket: str | None, env: Mapping[str, str]) -> Job:
+    """The job for ADDRESS, every install check made; nothing is written."""
+    _check_platform()
+    _check_address(address)
+    home = _home(env)
+    sm_home = _sessionmail_home(env, home)
+    key_home = os.path.join(sm_home, "seat-keys", address)
+    key = os.path.join(key_home, "id_ed25519")
+    pub = os.path.join(key_home, "seat.pub")
+    if not os.path.isdir(key_home):
+        raise Refused(f"no key home {key_home}: mint the seat first "
+                      f"(message seat init --registry DIR {address})")
+    for path in (key, pub):
+        if not os.path.isfile(path):
+            raise Refused(f"no {os.path.basename(path)} at {path}: mint the seat first "
+                          f"(message seat init --registry DIR {address})")
+    if socket is None:
+        socket = os.path.join(key_home, "agent.sock")
+    elif not os.path.isabs(socket):
+        raise Refused(f"SOCKET {socket!r} is not an absolute path: launchd starts the "
+                      "job in /, so name it in full")
+    size = len(socket.encode())
+    if size > SOCK_MAX:
+        raise Refused(f"socket path is {size} bytes; macOS binds {SOCK_MAX} at most "
+                      "(104 with its NUL). Name a shorter SOCKET")
+    if not os.path.isdir(os.path.dirname(socket)):
+        raise Refused(f"no directory {os.path.dirname(socket)} for the socket")
+    message = shutil.which("message", path=env["PATH"]) if env.get("PATH") else None
+    if message is None:
+        raise Refused("`message` is not on PATH: launchd runs `message seat agent`, "
+                      "by the path `command -v message` prints")
+    label = label_for(address)
+    log_dir = os.path.join(home, "Library", "Logs")
+    return Job(address=address, label=label,
+               plist=os.path.join(home, "Library", "LaunchAgents", f"{label}.plist"),
+               socket=socket, pub=pub, key=key,
+               log=os.path.join(log_dir, f"seat-agent.{address}.log"), log_dir=log_dir,
+               sessionmail_home=sm_home, message=os.path.abspath(message),
+               domain=f"gui/{os.getuid()}")
+
+
+def render(template: bytes, job: Job) -> bytes:
+    """The template with its five placeholders filled, each value XML-escaped.
+    One pass, so a value is never itself read for a placeholder. An unknown
+    placeholder, a render plistlib cannot read, or a Label that is not the
+    job's is refused."""
+    values = {"ADDRESS": job.address, "MESSAGE": job.message,
+              "SESSIONMAIL_HOME": job.sessionmail_home, "SOCKET": job.socket,
+              "LOG_DIR": job.log_dir}
+    text = template.decode("utf-8")
+    unknown = sorted(set(PLACEHOLDER.findall(text)) - set(values))
+    if unknown:
+        raise Refused("the packaged template holds a placeholder this sessionmail does not "
+                      f"fill ({', '.join('@' + u + '@' for u in unknown)}): a broken install")
+    out = PLACEHOLDER.sub(lambda m: escape(values[m.group(1)]), text).encode("utf-8")
+    try:
+        parsed = plistlib.loads(out)
+    except Exception as exc:  # plistlib raises several kinds on a bad document
+        raise Refused(f"the rendered LaunchAgent is not a valid plist ({exc})") from exc
+    if parsed.get("Label") != job.label:
+        raise Refused(f"the rendered Label is {parsed.get('Label')!r}, not {job.label!r}")
+    return out
+
+
+def loaded(job_target: str, env: Mapping[str, str]) -> bool:
+    """`launchctl print TARGET`: rc 0 means the job is loaded."""
+    return launchctl(env, "print", job_target).returncode == 0
+
+
+def _read(path: str) -> bytes | None:
+    try:
+        with open(path, "rb") as f:
+            return f.read()
+    except FileNotFoundError:
+        return None
+
+
+def _write(path: str, data: bytes) -> None:
+    """Write DATA at PATH, 0644, through a temp file and os.replace."""
+    os.makedirs(os.path.dirname(path), mode=0o755, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(prefix=".seat-agent.", dir=os.path.dirname(path))
+    try:
+        with os.fdopen(fd, "wb") as f:
+            f.write(data)
+        os.chmod(tmp, 0o644)
+        os.replace(tmp, path)
+    except BaseException:
+        if os.path.exists(tmp):
+            os.unlink(tmp)
+        raise
+
+
+def answers(job: Job, env: Mapping[str, str]) -> bool:
+    """The agent on the socket lists seat.pub's key. A clean env: only this
+    socket, never the caller's SSH_AUTH_SOCK."""
+    ssh_add = shutil.which("ssh-add", path=env.get("PATH", "")) or "/usr/bin/ssh-add"
+    try:
+        with open(job.pub) as f:
+            blob = f.read().split()[1]
+    except (OSError, IndexError):
+        return False
+    clean = {"PATH": "/usr/bin:/bin", "HOME": env.get("HOME", "/"), "SSH_AUTH_SOCK": job.socket}
+    try:
+        done = subprocess.run([ssh_add, "-L"], capture_output=True, text=True, env=clean,
+                              stdin=subprocess.DEVNULL, timeout=5, check=False)
+    except (OSError, subprocess.TimeoutExpired):
+        return False
+    return done.returncode == 0 and blob in done.stdout
+
+
+def _wait(predicate, seconds: float) -> bool:
+    deadline = time.monotonic() + seconds
+    while True:
+        if predicate():
+            return True
+        if time.monotonic() >= deadline:
+            return False
+        time.sleep(POLL_SECONDS)
+
+
+def _log_tail(job: Job) -> str:
+    try:
+        with open(job.log, errors="replace") as f:
+            lines = f.read().splitlines()[-LOG_TAIL:]
+    except OSError:
+        return f"(no log at {job.log})"
+    return f"the last lines of {job.log}:\n" + "\n".join("  " + line for line in lines)
+
+
+def report(job: Job) -> str:
+    """The stdout contract: KEY=VALUE, shell-quoted, for `eval`."""
+    pairs = (("SEAT_LABEL", job.label), ("SEAT_PLIST", job.plist), ("SEAT_SOCKET", job.socket),
+             ("SEAT_PUB", job.pub), ("SEAT_LOG", job.log))
+    return "".join(f"{k}={shlex.quote(v)}\n" for k, v in pairs)
+
+
+def install(address: str, socket: str | None = None, *, env: Mapping[str, str] | None = None,
+            out: IO[str] | None = None, err: IO[str] | None = None) -> int:
+    env = os.environ if env is None else env
+    out = sys.stdout if out is None else out
+    err = sys.stderr if err is None else err
+    try:
+        return _install(address, socket, env, out, err)
+    except Refused as exc:
+        err.write(f"{PROG}: REFUSED - {exc}. Nothing was written.\n")
+        return EX_REFUSED
+    except Failed as exc:
+        err.write(f"{PROG}: FAILED - {exc}\n")
+        return EX_FAILED
+
+
+def _install(address: str, socket: str | None, env: Mapping[str, str],
+             out: IO[str], err: IO[str]) -> int:
+    job = plan(address, socket, env)
+    with open(TEMPLATE, "rb") as f:
+        rendered = render(f.read(), job)
+    existing = _read(job.plist)
+    is_loaded = loaded(job.target, env)
+    if is_loaded and existing == rendered:
+        if not _wait(lambda: answers(job, env), ANSWER_SECONDS):
+            raise Failed(f"{job.label} is loaded but its agent does not answer on {job.socket} "
+                         f"with seat.pub's key; the job was left as found (this run did not "
+                         f"load it). {_log_tail(job)}")
+        err.write(f"{PROG}: {job.label} already installed; the agent answers on {job.socket}\n")
+        out.write(report(job))
+        return EX_OK
+    if is_loaded:
+        why = "with a different plist" if existing is not None else f"with no plist at {job.plist}"
+        raise Refused(f"a job already holds {job.label} ({why}): run "
+                      f"`{PROG} --uninstall {address}` first")
+    if existing is not None and existing != rendered:
+        raise Refused(f"a different plist is at {job.plist}: run "
+                      f"`{PROG} --uninstall {address}` first; a job's plist is never overwritten")
+
+    wrote = existing is None
+    # An OSError here is a FAILED line, never a traceback. _write leaves no temp
+    # file and no plist behind, and nothing has been loaded yet. A plist that was
+    # there before this run is never touched, so the line says it is kept.
+    path = job.log_dir
+    try:
+        os.makedirs(job.log_dir, exist_ok=True)
+        path = job.plist
+        if wrote:
+            _write(job.plist, rendered)
+    except OSError as exc:
+        kept = ("no plist was left" if wrote
+                else f"the plist at {job.plist} was there before this run and is kept")
+        raise Failed(f"could not write {path} ({exc.strerror or exc}); nothing was "
+                     f"loaded and {kept}") from exc
+    done = launchctl(env, "bootstrap", job.domain, job.plist)
+    if done.returncode != 0:
+        put_back = _remove_ours(job, wrote)
+        raise Failed(f"launchctl bootstrap {job.domain} {job.plist} failed ({_words(done)}); "
+                     f"{put_back}")
+    if not _wait(lambda: answers(job, env), ANSWER_SECONDS):
+        off = launchctl(env, "bootout", job.target)
+        booted = ("booted it out" if off.returncode == 0
+                  else f"its bootout failed too ({_words(off)})")
+        put_back = _remove_ours(job, wrote)
+        raise Failed(f"loaded {job.label}, but its agent did not answer on {job.socket} with "
+                     f"seat.pub's key within {ANSWER_SECONDS:g} s; {booted}; {put_back}. "
+                     f"{_log_tail(job)}")
+    err.write(f"{PROG}: installed and loaded {job.label}; the agent answers on {job.socket}\n")
+    out.write(report(job))
+    return EX_OK
+
+
+def _remove_ours(job: Job, wrote: bool) -> str:
+    if not wrote:
+        return f"the plist at {job.plist} was there before this run and is kept"
+    try:
+        os.unlink(job.plist)
+    except FileNotFoundError:
+        pass
+    except OSError as exc:
+        return f"the plist this run wrote could NOT be removed ({job.plist}: {exc.strerror})"
+    return f"the plist this run wrote is removed ({job.plist})"
+
+
+def uninstall(address: str, *, env: Mapping[str, str] | None = None,
+              err: IO[str] | None = None) -> int:
+    env = os.environ if env is None else env
+    err = sys.stderr if err is None else err
+    try:
+        return _uninstall(address, env, err)
+    except Refused as exc:
+        err.write(f"{PROG}: REFUSED - {exc}. Nothing was changed.\n")
+        return EX_REFUSED
+    except Failed as exc:
+        err.write(f"{PROG}: FAILED - {exc}\n")
+        return EX_FAILED
+
+
+def _uninstall(address: str, env: Mapping[str, str], err: IO[str]) -> int:
+    _check_platform()
+    _check_address(address)
+    home = _home(env)
+    label = label_for(address)
+    plist = os.path.join(home, "Library", "LaunchAgents", f"{label}.plist")
+    target = f"gui/{os.getuid()}/{label}"
+    existing = _read(plist)
+    if existing is not None:
+        try:
+            theirs = plistlib.loads(existing).get("Label")
+        except Exception:
+            theirs = None
+        if theirs != label:
+            raise Refused(f"the plist at {plist} has Label {theirs!r}, not {label!r}: "
+                          "not this tool's to remove")
+    said = []
+    if loaded(target, env):
+        off = launchctl(env, "bootout", target)
+        if off.returncode != 0:
+            raise Failed(f"launchctl bootout {target} failed ({_words(off)}); "
+                         f"the plist is kept" + (f" at {plist}" if existing is not None else ""))
+        if not _wait(lambda: not loaded(target, env), GONE_SECONDS):
+            raise Failed(f"{label} is still loaded {GONE_SECONDS:g} s after its bootout; "
+                         "the plist is kept" + (f" at {plist}" if existing is not None else ""))
+        said.append(f"booted out {label}")
+    if existing is not None:
+        try:
+            os.unlink(plist)
+        except FileNotFoundError:
+            pass
+        except OSError as exc:
+            done = f"{'; '.join(said)}; but " if said else ""
+            raise Failed(f"{done}could not remove {plist} ({exc.strerror or exc}); "
+                         "the plist is kept") from exc
+        said.append(f"removed {plist}")
+    if not said:
+        err.write(f"{PROG}: nothing installed for {address}\n")
+    else:
+        err.write(f"{PROG}: {'; '.join(said)}\n")
+    return EX_OK