kache-ssh 0.1.0__py3-none-any.whl

kache/agent.py

@@ -0,0 +1,594 @@
+"""The gatekeeper: Kache's agent on every device.
+
+It is an SSH server (asyncssh) that only listens to paired devices:
+  * an unknown device may only say hello and ask to pair; the request pops
+    up as a yes/no question in this device's Kache terminal;
+  * a paired device may send orders. Every order goes into this device's
+    feed with the exact command and who sent it, runs in the device's own
+    shell, streams its output back, and when it fails the gatekeeper
+    collects evidence and sends it back to the sender;
+  * Kache terminals subscribe to telemetry (health numbers) and to the feed.
+
+Internal requests are SSH exec commands starting with "kache:"; anything
+else is an order and is executed exactly as written.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import codecs
+import json
+import os
+import re
+import shlex
+import shutil
+import time
+from collections import deque
+from dataclasses import dataclass
+from pathlib import Path
+
+import asyncssh
+import psutil
+
+from . import PROTOCOL, SCHEMA, __version__
+from .config import (Paths, device_settings, now_stamp, os_description, save_json,
+                     save_trusted, trusted_keys)
+from .evidence import collect, first_token, new_id
+from .keys import fingerprint, load_or_create_key, pairing_code, public_key_text
+from .network import advertised_addresses, listen_hosts, tailscale_status
+from .telemetry import Telemetry
+
+TRAILER = "\x1eKACHE "  # last stderr line of an order: {"exit", "duration", "evidence", "cwd"}
+POSIX_BUILTINS = {
+    ".", ":", "[", "alias", "bg", "break", "builtin", "cd", "command", "continue", "declare", "echo", "eval",
+    "exec", "exit", "export", "false", "fg", "for", "function", "hash", "history", "if", "jobs", "kill",
+    "let", "local", "printf", "pwd", "read", "readonly", "return", "set", "shift", "source", "test", "time",
+    "times", "trap", "true", "type", "typeset", "ulimit", "umask", "unalias", "unset", "until", "wait", "while",
+}
+
+
+@dataclass
+class Peer:
+    fingerprint: str
+    public_key: str
+    addr: str
+    trusted: bool
+    own: bool
+    name: str
+
+
+def shell_for_os() -> str:
+    if os.name == "nt":
+        return shutil.which("pwsh") or shutil.which("powershell") or "powershell.exe"
+    return os.environ.get("SHELL") or "/bin/sh"
+
+
+def shell_argv(shell: str, command: str, script_path: Path | None = None) -> list[str]:
+    if os.name == "nt":
+        # The order runs from a UTF-8 script file: no Windows quoting traps,
+        # and errors come out as text (-EncodedCommand turns them into CLIXML).
+        # UTF-8 output also switches the hidden console's code page, so native
+        # programs print å, ä, ö correctly. The tail turns a failing cmdlet or
+        # native program into a non-zero exit code.
+        script = ("$ProgressPreference='SilentlyContinue'\n"
+                  "[Console]::OutputEncoding=[Text.Encoding]::UTF8\n"
+                  "$OutputEncoding=[Text.Encoding]::UTF8\n"
+                  f"{command}\n"
+                  "$kacheOk=$?;if($LASTEXITCODE){exit $LASTEXITCODE}elseif(-not $kacheOk){exit 1}\n")
+        assert script_path is not None
+        script_path.parent.mkdir(parents=True, exist_ok=True)
+        script_path.write_text(script, encoding="utf-8-sig")
+        return [shell, "-NoLogo", "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-File", str(script_path)]
+    return [shell, "-c", command]
+
+
+def order_environment() -> dict:
+    env = dict(os.environ)
+    env.setdefault("PYTHONIOENCODING", "utf-8")  # Python writes UTF-8 to the pipe, not the ANSI code page
+    env.setdefault("PYTHONUNBUFFERED", "1")      # and prints show up live, not in 8 KB blocks
+    return env
+
+
+def kill_tree(pid: int) -> None:
+    try:
+        parent = psutil.Process(pid)
+    except psutil.Error:
+        return
+    for proc in parent.children(recursive=True) + [parent]:
+        try:
+            proc.kill()
+        except psutil.Error:
+            pass
+
+
+class _Server(asyncssh.SSHServer):
+    """One per connection; remembers which key authenticated it."""
+
+    def __init__(self, gatekeeper: "Gatekeeper") -> None:
+        self.gk = gatekeeper
+        self.conn = None
+        self.peer: Peer | None = None
+
+    def connection_made(self, conn) -> None:
+        self.conn = conn
+        self.gk.connections.add(conn)
+
+    def connection_lost(self, exc) -> None:
+        self.gk.connections.discard(self.conn)
+
+    def begin_auth(self, username: str) -> bool:
+        return True
+
+    def public_key_auth_supported(self) -> bool:
+        return True
+
+    def validate_public_key(self, username: str, key: asyncssh.SSHKey) -> bool:
+        # Every key may connect; what it may do is decided per request.
+        fp = key.get_fingerprint("sha256")
+        entry = self.gk.trusted.get(fp)
+        own = fp == self.gk.fingerprint
+        peername = self.conn.get_extra_info("peername") or ("?", 0)
+        self.peer = Peer(
+            fingerprint=fp, public_key=key.export_public_key().decode("ascii").strip(),
+            addr=str(peername[0]), trusted=own or entry is not None, own=own,
+            name="this device" if own else (entry or {}).get("name", "unknown"))
+        return True
+
+
+class Gatekeeper:
+    def __init__(self, paths: Paths, port: int | None = None, host: str | None = None, log=None) -> None:
+        self.paths = paths
+        self.key = load_or_create_key(paths.key_file)
+        self.fingerprint = fingerprint(self.key)
+        settings = device_settings(paths)
+        self.name = settings["name"]
+        self.port = settings["port"] if port is None else port
+        self.fixed_host = host  # tests and `kache agent --host` pin one interface
+        self.listen = settings.get("listen", "all")
+        self.hosts: list[str] = []
+        self.addresses: list[str] = []
+        self.tailscale: dict | None = None
+        self.connections: set = set()
+        self.trusted = trusted_keys(paths)
+        self.telemetry = Telemetry(str(Path.home().anchor or "/"))
+        self.shell = shell_for_os()
+        self.log = log or (lambda text: None)
+        self.subscribers: set[asyncio.Queue] = set()
+        self.history: deque = deque(maxlen=300)
+        self.pending: dict[str, dict] = {}
+        self.sessions: dict[tuple[str, str], str] = {}
+        self.server = None
+        self.stopped = asyncio.Event()
+        self._tasks: list[asyncio.Task] = []
+
+    # ---------------------------------------------------------------- life
+    async def start(self) -> "Gatekeeper":
+        await self._refresh_network()
+        await self._bind()
+        self.telemetry.latest = await asyncio.to_thread(self.telemetry.sample)
+        self._tasks.append(asyncio.create_task(self.telemetry.run()))
+        self._tasks.append(asyncio.create_task(self._watch_network()))
+        return self
+
+    async def _bind(self) -> None:
+        hosts = [self.fixed_host] if self.fixed_host else listen_hosts(self.listen, self.tailscale)
+        if self.server is not None:
+            self.server.close()  # open connections stay up; only new ones use the new interfaces
+        self.server = await asyncssh.create_server(
+            lambda: _Server(self), hosts if len(hosts) > 1 else hosts[0], self.port,
+            server_host_keys=[self.key], process_factory=self._handle,
+            encoding="utf-8", allow_scp=False, agent_forwarding=False,
+            x11_forwarding=False, keepalive_interval=15, line_editor=False)
+        if self.port == 0:
+            self.port = self.server.get_port() or self.server.sockets[0].getsockname()[1]
+        self.hosts = hosts
+        self.log(f"gatekeeper '{self.name}' listening on {', '.join(hosts)} port {self.port} ({self.fingerprint})")
+
+    async def _refresh_network(self) -> None:
+        if self.fixed_host in ("127.0.0.1", "localhost", "::1"):
+            return  # a local-only gatekeeper (tests) has nothing to advertise
+        self.tailscale = await asyncio.to_thread(tailscale_status)
+        self.addresses = await asyncio.to_thread(advertised_addresses, self.tailscale)
+
+    async def _watch_network(self) -> None:
+        """Addresses change (new Wi-Fi, Tailscale coming up after logon).
+        Keep the advertised list fresh, and in Tailscale-only mode bind to the
+        tailnet as soon as it appears."""
+        while True:
+            await asyncio.sleep(60)
+            try:
+                await self._refresh_network()
+                if not self.fixed_host and listen_hosts(self.listen, self.tailscale) != self.hosts:
+                    await self._bind()
+            except Exception as error:  # a network hiccup must not stop the gatekeeper
+                self.log(f"network refresh failed: {error!r}")
+
+    async def stop(self) -> None:
+        for task in self._tasks:
+            task.cancel()
+        if self.server:
+            self.server.close()
+        for conn in list(self.connections):
+            conn.close()
+        if self.server:
+            try:
+                await asyncio.wait_for(self.server.wait_closed(), 5)
+            except asyncio.TimeoutError:
+                pass
+
+    # ---------------------------------------------------------------- feed
+    def emit(self, event: dict) -> None:
+        event = {"v": SCHEMA, "time": time.time(), "device": self.name, "device_fp": self.fingerprint, **event}
+        self.history.append(event)
+        try:
+            if self.paths.feed_file.exists() and self.paths.feed_file.stat().st_size > 5_000_000:
+                self.paths.feed_file.replace(self.paths.feed_file.with_suffix(".old.jsonl"))
+            with self.paths.feed_file.open("a", encoding="utf-8") as handle:
+                handle.write(json.dumps(event) + "\n")
+        except OSError:
+            pass
+        for queue in list(self.subscribers):
+            if queue.full():
+                continue
+            queue.put_nowait(event)
+
+    # ---------------------------------------------------------------- requests
+    async def _handle(self, process) -> None:
+        conn = process.get_extra_info("connection")
+        owner = conn.get_owner() if conn is not None else None
+        peer = getattr(owner, "peer", None)
+        command = process.command
+        try:
+            if peer is None:
+                process.exit(1)
+                return
+            if command is None:
+                process.stderr.write("Kache sends one command at a time; interactive shells come later.\n")
+                process.exit(2)
+                return
+            if command.startswith("kache:"):
+                verb, _, argument = command[len("kache:"):].partition(" ")
+                await self._internal(verb, argument, peer, process)
+            elif not peer.trusted:
+                self._refuse(process)
+            else:
+                await self._order({"cmd": command}, peer, process)
+        except (BrokenPipeError, ConnectionError, asyncssh.Error):
+            pass
+        except Exception as error:  # never let one request kill the gatekeeper
+            self.log(f"request failed: {error!r}")
+            try:
+                process.stderr.write(f"Kache gatekeeper error: {error}\n")
+                process.exit(1)
+            except Exception:
+                pass
+
+    def _refuse(self, process) -> None:
+        process.stderr.write("This device has not been paired with you. Send a pair request first.\n")
+        process.exit(77)
+
+    async def _internal(self, verb: str, argument: str, peer: Peer, process) -> None:
+        if verb == "hello":
+            self._reply(process, self.hello(peer))
+            return
+        if verb == "pair":
+            await self._pair(peer, process, argument)
+            return
+        if not peer.trusted:
+            self._refuse(process)
+            return
+        if verb == "order":
+            await self._order(json.loads(argument or "{}"), peer, process)
+        elif verb == "telemetry":
+            await self._stream(process, telemetry=True)
+        elif verb == "feed":
+            await self._stream(process, telemetry=False)
+        elif verb == "session":
+            data = json.loads(argument or "{}")
+            self._reply(process, {"cwd": self.sessions.get((peer.fingerprint, data.get("session", "default")), str(Path.home()))})
+        elif verb == "evidence":
+            path = self.paths.evidence_dir / f"{Path(argument.strip()).name}.json"
+            if path.exists():
+                process.stdout.write(path.read_text(encoding="utf-8"))
+                process.exit(0)
+            else:
+                process.stderr.write("No such evidence on this device.\n")
+                process.exit(1)
+        elif verb == "forget":
+            removed = self.trusted.pop(peer.fingerprint, None)
+            save_trusted(self.paths, self.trusted)
+            if removed:
+                self.emit({"kind": "unpaired", "sender": self._sender(peer), "text": f"{removed.get('name')} removed itself"})
+            self._reply(process, {"removed": bool(removed)})
+        elif peer.own:
+            await self._local(verb, argument, peer, process)
+        else:
+            process.stderr.write(f"Unknown or local-only request: kache:{verb}\n")
+            process.exit(1)
+
+    async def _local(self, verb: str, argument: str, peer: Peer, process) -> None:
+        """Requests only this device's own Kache terminal may make."""
+        if verb == "pending":
+            self._reply(process, [entry["info"] for entry in self.pending.values()])
+        elif verb == "decide":
+            data = json.loads(argument or "{}")
+            entry = self.pending.get(data.get("id", ""))
+            if entry and not entry["future"].done():
+                entry["future"].set_result(bool(data.get("accept")))
+                self._reply(process, {"ok": True})
+            else:
+                self._reply(process, {"ok": False, "reason": "no such pending request"})
+        elif verb == "trusted":
+            self._reply(process, self.trusted)
+        elif verb == "revoke":
+            target = argument.strip()
+            removed = [fp for fp, entry in self.trusted.items() if fp == target or entry.get("name") == target]
+            for fp in removed:
+                self.trusted.pop(fp, None)
+            save_trusted(self.paths, self.trusted)
+            for fp in removed:
+                self.emit({"kind": "unpaired", "sender": self._sender(peer), "text": f"revoked {fp}"})
+            self._reply(process, {"removed": removed})
+        elif verb == "reload":
+            settings = device_settings(self.paths)
+            self.name = settings["name"]
+            self.trusted = trusted_keys(self.paths)
+            listen = settings.get("listen", "all")
+            if listen != self.listen:
+                self.listen = listen
+                await self._refresh_network()
+                await self._bind()
+            self._reply(process, {"name": self.name, "listen": self.listen, "hosts": self.hosts})
+        elif verb == "shutdown":
+            self._reply(process, {"ok": True})
+            self.stopped.set()
+        else:
+            process.stderr.write(f"Unknown request: kache:{verb}\n")
+            process.exit(1)
+
+    def _reply(self, process, data) -> None:
+        process.stdout.write(json.dumps(data) + "\n")
+        process.exit(0)
+
+    def hello(self, peer: Peer | None = None) -> dict:
+        return {"name": self.name, "fingerprint": self.fingerprint, "public_key": public_key_text(self.key),
+                "os": os_description(), "kache": __version__, "proto": PROTOCOL, "schema": SCHEMA,
+                "port": self.port, "addresses": self.addresses, "listen": self.listen,
+                "paired": bool(peer and peer.trusted), "own": bool(peer and peer.own)}
+
+    def _sender(self, peer: Peer, label: str | None = None, via: str | None = None) -> dict:
+        label = str(label)[:40] if label else None
+        via = str(via)[:20] if via else None
+        return {"name": peer.name, "label": label, "via": via, "fingerprint": peer.fingerprint, "addr": peer.addr}
+
+    # ---------------------------------------------------------------- streams
+    async def _stream(self, process, telemetry: bool) -> None:
+        closed = asyncio.ensure_future(process.channel.wait_closed())
+        queue: asyncio.Queue | None = None
+        try:
+            if telemetry:
+                while not closed.done():
+                    process.stdout.write(json.dumps(self.telemetry.latest) + "\n")
+                    await asyncio.wait({closed}, timeout=2.0)
+                return
+            queue = asyncio.Queue(maxsize=2000)
+            self.subscribers.add(queue)
+            for event in list(self.history)[-60:]:
+                process.stdout.write(json.dumps({**event, "replay": True}) + "\n")
+            while not closed.done():
+                getter = asyncio.ensure_future(queue.get())
+                done, _ = await asyncio.wait({getter, closed}, return_when=asyncio.FIRST_COMPLETED)
+                if getter in done:
+                    process.stdout.write(json.dumps(getter.result()) + "\n")
+                else:
+                    getter.cancel()
+        finally:
+            if queue is not None:
+                self.subscribers.discard(queue)
+            closed.cancel()
+
+    # ---------------------------------------------------------------- pairing
+    async def _pair(self, peer: Peer, process, argument: str) -> None:
+        request = json.loads(argument or "{}")
+        answer = {"name": self.name, "fingerprint": self.fingerprint, "host_key": public_key_text(self.key),
+                  "os": os_description(), "kache": __version__, "proto": PROTOCOL,
+                  "addresses": self.addresses, "port": self.port,
+                  "code": pairing_code(peer.fingerprint, self.fingerprint)}
+        if peer.own:
+            self._reply(process, {**answer, "accepted": False, "reason": "a device cannot pair with itself"})
+            return
+        if peer.trusted:
+            self._reply(process, {**answer, "accepted": True, "already": True})
+            return
+        if request.get("proto") != PROTOCOL:
+            self._reply(process, {**answer, "accepted": False,
+                                  "reason": f"Kache versions differ (this device speaks protocol {PROTOCOL}); update both with pip install -U kache-ssh"})
+            return
+        if len(self.pending) >= 5 or any(e["info"]["fingerprint"] == peer.fingerprint for e in self.pending.values()):
+            self._reply(process, {**answer, "accepted": False, "reason": "a request from you is already waiting"})
+            return
+        info = {"id": new_id("P"), "name": str(request.get("name") or "unknown")[:40], "os": request.get("os"),
+                "fingerprint": peer.fingerprint, "addr": peer.addr, "code": answer["code"], "created": time.time()}
+        future = asyncio.get_running_loop().create_future()
+        self.pending[info["id"]] = {"info": info, "future": future, "public_key": peer.public_key}
+        self.emit({"kind": "pair-request", **info})
+        try:
+            accepted = await asyncio.wait_for(asyncio.shield(future), timeout=180)
+            reason = None if accepted else "declined"
+        except asyncio.TimeoutError:
+            accepted, reason = False, "nobody answered on that device within 3 minutes"
+        finally:
+            self.pending.pop(info["id"], None)
+        if accepted:
+            self.trusted[peer.fingerprint] = {"name": info["name"], "public_key": peer.public_key, "os": info["os"],
+                                              "addr": peer.addr, "added": now_stamp()}
+            save_trusted(self.paths, self.trusted)
+            peer.trusted, peer.name = True, info["name"]
+            self.emit({"kind": "paired", "name": info["name"], "fingerprint": peer.fingerprint, "addr": peer.addr})
+        else:
+            self.emit({"kind": "pair-declined", "name": info["name"], "fingerprint": peer.fingerprint, "reason": reason})
+        self._reply(process, {**answer, "accepted": accepted, "reason": reason})
+
+    # ---------------------------------------------------------------- orders
+    async def _order(self, order: dict, peer: Peer, process) -> None:
+        command = str(order.get("cmd", "")).strip()
+        order_id = order.get("id") or new_id("O")
+        session = str(order.get("session") or "default")
+        sender = self._sender(peer, order.get("label"), order.get("via"))
+        key = (peer.fingerprint, session)
+        cwd = self.sessions.get(key) or str(Path.home())
+        order = {"id": order_id, "cmd": command, "sender": sender, "cwd": cwd, "session": session}
+        self.emit({"kind": "order", **order})
+        started = time.monotonic()
+
+        last_char = {"stdout": "\n", "stderr": "\n"}
+
+        def finish(code: int, evidence: dict | None = None, rejected: str | None = None) -> None:
+            duration = time.monotonic() - started
+            event = {"kind": "done", "id": order_id, "cmd": command, "sender": sender,
+                     "exit": code, "duration": round(duration, 3), "session": session}
+            if evidence:
+                event["evidence"] = evidence["id"]
+                event["summary"] = evidence["summary"]
+            if rejected:
+                event["rejected"] = rejected
+            self.emit(event)
+            trailer = {"exit": code, "duration": round(duration, 3), "cwd": self.sessions.get(key, cwd),
+                       "evidence": evidence["id"] if evidence else None, "summary": evidence["summary"] if evidence else None,
+                       "rejected": rejected}
+            newline = "" if last_char["stderr"] == "\n" else "\n"  # the trailer must start its own line
+            process.stderr.write(newline + TRAILER + json.dumps(trailer) + "\n")
+            process.exit(0 if code == 0 else (code if 0 < code < 256 else 255))
+
+        if "proto" in order and order.get("proto") != PROTOCOL:
+            reason = f"Kache versions differ (sender protocol {order.get('proto')}, this device {PROTOCOL}). Update both."
+            process.stderr.write(reason + "\n")
+            finish(126, rejected=reason)
+            return
+        if not command:
+            finish(0)
+            return
+        cd = self._try_cd(command, key, cwd)
+        if cd is not None:
+            ok, message = cd
+            if message:
+                process.stderr.write(message)
+            finish(0 if ok else 1)
+            return
+        refusal = self._precheck(command)
+        if refusal:
+            process.stderr.write(refusal + "\n")
+            result = {"exit": 127, "duration": 0.0, "stdout_tail": [], "stderr_tail": [refusal], "cancelled": False}
+            finish(127, self._evidence(order, result), rejected=refusal)
+            return
+
+        script = self.paths.home / "orders" / f"{re.sub(r'[^A-Za-z0-9_-]', '', str(order_id))[:40] or new_id('O')}.ps1"
+        try:
+            await self._run_child(command, cwd, script, process, order, order_id, sender, started, finish, last_char)
+        finally:
+            if os.name == "nt":
+                try:
+                    script.unlink()
+                except OSError:
+                    pass
+
+    async def _run_child(self, command, cwd, script, process, order, order_id, sender, started, finish, last_char) -> None:
+        child = await asyncio.create_subprocess_exec(
+            *shell_argv(self.shell, command, script), cwd=cwd, stdin=asyncio.subprocess.DEVNULL,
+            stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE, env=order_environment(),
+            creationflags=0x08000000 if os.name == "nt" else 0)  # CREATE_NO_WINDOW: a hidden console
+        tails = {"stdout": deque(maxlen=60), "stderr": deque(maxlen=60)}
+
+        async def pump(stream, out, name: str) -> None:
+            decoder = codecs.getincrementaldecoder("utf-8")(errors="replace")
+            partial = ""
+            while True:
+                chunk = await stream.read(4096)
+                if not chunk:
+                    break
+                text = decoder.decode(chunk)
+                if not text:
+                    continue
+                last_char[name] = text[-1]
+                try:
+                    out.write(text)
+                except (BrokenPipeError, ConnectionError, asyncssh.Error):
+                    pass
+                partial += text
+                *lines, partial = partial.split("\n")
+                tails[name].extend(line.rstrip("\r") for line in lines)
+            if partial:
+                tails[name].append(partial.rstrip("\r"))
+
+        pumps = asyncio.ensure_future(asyncio.gather(pump(child.stdout, process.stdout, "stdout"),
+                                                     pump(child.stderr, process.stderr, "stderr")))
+        closed = asyncio.ensure_future(process.channel.wait_closed())
+        cancelled = False
+        done, _ = await asyncio.wait({pumps, closed}, return_when=asyncio.FIRST_COMPLETED)
+        if pumps not in done:
+            cancelled = True  # the sender hung up (Ctrl+C on their side)
+            kill_tree(child.pid)
+            await pumps
+        closed.cancel()
+        code = await child.wait()
+        result = {"exit": code, "duration": time.monotonic() - started, "stdout_tail": list(tails["stdout"]),
+                  "stderr_tail": list(tails["stderr"]), "cancelled": cancelled}
+        evidence = self._evidence(order, result) if (code != 0 or cancelled) else None
+        if cancelled:
+            self.emit({"kind": "done", "id": order_id, "cmd": command, "sender": sender, "exit": code,
+                       "duration": round(result["duration"], 3), "cancelled": True, "session": order["session"],
+                       "evidence": evidence["id"] if evidence else None,
+                       "summary": evidence["summary"] if evidence else None})
+            return
+        finish(code, evidence)
+
+    def _evidence(self, order: dict, result: dict) -> dict:
+        bundle = collect(order, result, self.telemetry.latest, self.name, self.shell)
+        save_json(self.paths.evidence_dir / f"{bundle['id']}.json", bundle)
+        self.emit({"kind": "evidence", "id": bundle["id"], "order": order["id"], "cmd": order["cmd"],
+                   "sender": order["sender"], "summary": bundle["summary"], "exit": bundle["exit"]})
+        return bundle
+
+    def _try_cd(self, command: str, key, cwd: str):
+        """`cd` moves the sender's session, so the next order starts there,
+        just like typing in a real terminal on this device."""
+        match = re.fullmatch(r"(cd|chdir|Set-Location|sl)(?:\s+(.+))?", command.strip(), re.I)
+        if not match:
+            return None
+        argument = (match.group(2) or "").strip().strip("\"'")
+        if not argument or argument == "~":
+            target = Path.home()
+        else:
+            target = Path(os.path.expandvars(os.path.expanduser(argument)))
+            if not target.is_absolute():
+                target = Path(cwd) / target
+        try:
+            target = target.resolve()
+        except OSError:
+            pass
+        if target.is_dir():
+            self.sessions[key] = str(target)
+            return True, ""
+        return False, f"cd: no such folder on {self.name}: {argument}\n"
+
+    def _precheck(self, command: str) -> str | None:
+        """Refuse orders that cannot work here, before running anything.
+        PowerShell resolves cmdlets and aliases itself, so on Windows the
+        gatekeeper lets the shell decide and explains the failure afterwards."""
+        if os.name == "nt":
+            return None
+        token = first_token(command)
+        if not token or token in POSIX_BUILTINS or "/" in token or "=" in token or token.startswith(("(", "{", "$")):
+            return None
+        if shutil.which(token):
+            return None
+        return f"Refused by the gatekeeper on {self.name}: '{token}' is not installed here ({os_description()})."
+
+
+async def run_agent(paths: Paths, port: int | None = None, host: str | None = None) -> None:
+    gatekeeper = await Gatekeeper(paths, port=port, host=host, log=lambda t: print(t, flush=True)).start()
+    print(f"Kache gatekeeper for '{gatekeeper.name}' is running on port {gatekeeper.port}. Ctrl+C stops it.", flush=True)
+    try:
+        await gatekeeper.stopped.wait()
+    finally:
+        await gatekeeper.stop()