pennyrouter 0.3.46 → 0.3.48

package/standalone/remote/rc_local.py

@@ -0,0 +1,110 @@
+"""Locate a completed native Claude transcript for an explicit terminal handoff."""
+
+import json
+import os
+from pathlib import Path
+import re
+import uuid
+
+
+def claude_directory():
+    return Path(os.environ.get("CLAUDE_CONFIG_DIR", str(Path.home() / ".claude"))).expanduser().resolve()
+
+
+def project_directory(config_dir, project):
+    return Path(config_dir) / "projects" / re.sub(r"[^a-zA-Z0-9]", "-", str(Path(project).resolve()))
+
+
+def ensure_inactive(config_dir, session_id):
+    for path in (Path(config_dir) / "sessions").glob("*.json"):
+        try:
+            record = json.loads(path.read_text())
+        except (OSError, ValueError):
+            continue
+        if record.get("sessionId") != session_id:
+            continue
+        pid = record.get("pid")
+        if not isinstance(pid, int) or pid <= 0:
+            continue
+        try:
+            os.kill(pid, 0)
+        except ProcessLookupError:
+            continue
+        except PermissionError:
+            pass
+        raise RuntimeError("This Claude session is still running. Finish its turn and exit the local chat first.")
+
+
+def read_local(project, session_id=None, config_dir=None):
+    config_dir = Path(config_dir or claude_directory()).resolve()
+    folder = project_directory(config_dir, project)
+    if session_id:
+        try:
+            session_id = str(uuid.UUID(session_id))
+        except ValueError:
+            raise RuntimeError("Local session ID must be a UUID.") from None
+        source = folder / (session_id + ".jsonl")
+        if not source.is_file():
+            raise RuntimeError("Local Claude session was not found in this project.")
+    else:
+        files = list(folder.glob("*.jsonl"))
+        if not files:
+            raise RuntimeError("No local Claude conversations were found for this project.")
+        source = max(files, key=lambda p: p.stat().st_mtime_ns)
+        session_id = source.stem
+        try:
+            uuid.UUID(session_id)
+        except ValueError:
+            raise RuntimeError("Latest local transcript has an invalid session ID.") from None
+    ensure_inactive(config_dir, session_id)
+    records = []
+    try:
+        with source.open() as handle:
+            for line in handle:
+                record = json.loads(line)
+                if not record.get("isSidechain"):
+                    records.append(record)
+    except (OSError, ValueError):
+        raise RuntimeError("Cannot read a complete local Claude transcript.") from None
+    messages = [r for r in records if r.get("type") in {"user", "assistant"} and not r.get("isMeta")]
+    if not messages or messages[-1].get("type") != "assistant" or messages[-1].get("message", {}).get("stop_reason") not in {"end_turn", "stop_sequence", "max_tokens"}:
+        raise RuntimeError("The local conversation has no completed final turn. Finish it in Claude before handing it off.")
+    if any(r.get("sessionId") != session_id or Path(r.get("cwd", "")).resolve() != Path(project).resolve() for r in messages):
+        raise RuntimeError("Transcript session or project does not match the requested handoff.")
+    # Follow the last branch; older abandoned branches should not appear on the phone.
+    indexed = {r["uuid"]: r for r in records if r.get("uuid")}
+    current = messages[-1]
+    chain, visited = [], set()
+    while current:
+        record_id = current.get("uuid")
+        if not record_id or record_id in visited:
+            raise RuntimeError("Local transcript contains an invalid message chain.")
+        visited.add(record_id)
+        chain.append(current)
+        current = indexed.get(current.get("parentUuid"))
+    chain.reverse()
+    return {"session_id": session_id, "config_dir": str(config_dir),
+            "model": messages[-1]["message"].get("model"), "records": chain}
+
+
+def phone_history(records, session_id):
+    """Mirror visible text, retaining UUIDs. Native resume keeps the full local context."""
+    for record in records:
+        kind = record.get("type")
+        if kind not in {"user", "assistant"} or record.get("isMeta"):
+            continue
+        message = record.get("message", {})
+        content = message.get("content", [])
+        if isinstance(content, str):
+            text = content
+        else:
+            text = "\n".join(block.get("text", "") for block in content if block.get("type") == "text")
+        if not text.strip():
+            continue
+        clean = {"role": kind, "content": text if kind == "user" else [{"type": "text", "text": text}]}
+        if kind == "assistant":
+            clean.update(id=message.get("id", "msg_" + record["uuid"].replace("-", "")),
+                         type="message", model=message.get("model"), stop_reason="end_turn",
+                         stop_sequence=None, usage={"input_tokens": 0, "output_tokens": 0})
+        yield {"type": kind, "uuid": record["uuid"], "session_id": session_id,
+               "message": clean, "parent_tool_use_id": None}

package/standalone/remote/rc_penny.py

@@ -0,0 +1,205 @@
+"""Text-only Remote Control probe backed by one persistent Penny Claude process.
+
+Uses the active Penny profile and an existing gateway. Tools, hooks, plugins, MCP,
+and session persistence are disabled; conversation continuity lives in the child.
+"""
+
+import argparse
+import asyncio
+import json
+import os
+from pathlib import Path
+import tempfile
+
+import httpx
+
+from rc_echo import BASE, EchoWorker, read_login
+
+
+def read_profile():
+    config_root = Path(os.environ.get("XDG_CONFIG_HOME", str(Path.home() / ".config")))
+    config = json.loads((config_root / "pennyrouter/config.json").read_text())
+    profile = config.get("profiles", {}).get(config.get("active_profile"), {})
+    if not profile.get("api_key") or not profile.get("gateway_base_url"):
+        raise RuntimeError("No active Penny profile with gateway and API key found.")
+    return profile, config.get("harnesses", {}).get("claude", {}).get("models", {}).get("sonnet", "claude-sonnet-5-5")
+
+
+class PennyClaude:
+    def __init__(self, profile, model, session_id, cwd, permission_handler=None):
+        self.profile, self.model, self.session_id, self.cwd = profile, model, session_id, cwd
+        self.process = None
+        self.stderr_task = None
+        self.permission_handler = permission_handler
+        self.effort = "low"
+        self.input_lock = asyncio.Lock()
+        self.interrupt_requested = False
+        self.persistence_dir = None
+        self.resume = False
+
+    async def start(self):
+        env = {k: v for k, v in os.environ.items() if not k.startswith("ANTHROPIC_")
+               and k not in {"CLAUDE_CODE_OAUTH_TOKEN", "CLAUDECODE", "HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY"}}
+        env.update(ANTHROPIC_BASE_URL=self.profile["gateway_base_url"],
+                   ANTHROPIC_API_KEY=self.profile["api_key"],
+                   CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC="1")
+        if self.persistence_dir:
+            env["CLAUDE_CONFIG_DIR"] = str(self.persistence_dir)
+        session_args = (["--resume", self.session_id] if self.resume else ["--session-id", self.session_id])
+        if not self.persistence_dir:
+            session_args.append("--no-session-persistence")
+        permissions = (["--permission-prompts", "host", "--permission-prompt-tool", "stdio",
+                        "--permission-mode", "default", "--settings",
+                        json.dumps({"permissions": {"ask": ["Read", "Edit"]}})]
+                       if self.permission_handler else ["--permission-prompts", "none"])
+        self.process = await asyncio.create_subprocess_exec(
+            "claude", "--bare", "-p", "--input-format", "stream-json", "--output-format", "stream-json",
+            "--verbose", "--include-partial-messages", *session_args,
+            "--model", self.model, "--effort", self.effort,
+            "--tools", "Read,Edit" if self.permission_handler else "", "--strict-mcp-config",
+            "--mcp-config", '{"mcpServers":{}}', *permissions,
+            "--disable-slash-commands", "--setting-sources", "",
+            stdin=asyncio.subprocess.PIPE, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE,
+            cwd=self.cwd, env=env, limit=4 * 1024 * 1024)
+        # Drain diagnostic output so it cannot block the child, without logging credentials.
+        self.stderr_task = asyncio.create_task(self.drain_stderr())
+        if self.permission_handler:
+            # The SDK handshake activates the bidirectional permission channel.
+            request_id = self.session_id + "-init"
+            await self.send({"type": "control_request", "request_id": request_id,
+                             "request": {"subtype": "initialize", "hooks": None}})
+            async with asyncio.timeout(60):
+                while True:
+                    line = await self.process.stdout.readline()
+                    if not line:
+                        raise RuntimeError("Claude exited during permission-channel initialization.")
+                    event = json.loads(line)
+                    response = event.get("response", {})
+                    if event.get("type") == "control_response" and response.get("request_id") == request_id:
+                        if response.get("subtype") != "success":
+                            raise RuntimeError("Claude refused permission-channel initialization.")
+                        break
+
+    async def drain_stderr(self):
+        while await self.process.stderr.read(4096):
+            pass
+
+    async def send(self, payload):
+        async with self.input_lock:
+            self.process.stdin.write((json.dumps(payload) + "\n").encode())
+            await self.process.stdin.drain()
+
+    async def interrupt(self, request_id):
+        self.interrupt_requested = True
+        await self.send({"type": "control_request", "request_id": request_id,
+                         "request": {"subtype": "interrupt"}})
+
+    async def turn(self, message):
+        self.interrupt_requested = False
+        if self.process is None:
+            await self.start()
+        content = message.get("content")
+        if not isinstance(content, str):
+            raise RuntimeError("This probe accepts text-only phone messages.")
+        await self.send({"type": "user", "message": {"role": "user", "content": content},
+                         "session_id": self.session_id, "parent_tool_use_id": None})
+        async with asyncio.timeout(300 if self.permission_handler else 120):
+            while True:
+                line = await self.process.stdout.readline()
+                if not line:
+                    raise RuntimeError("Penny Claude exited before completing the turn.")
+                event = json.loads(line)
+                kind = event.get("type")
+                if (kind == "result" and event.get("is_error") and self.interrupt_requested
+                        and event.get("terminal_reason") == "aborted_streaming"):
+                    # Claude's interrupted SDK turn carries an error flag even though
+                    # the persistent process remains usable. Only an explicitly
+                    # requested interrupt with this terminal reason is non-fatal.
+                    event = {**event, "subtype": "success", "is_error": False,
+                             "result": "Stopped by user."}
+                    event.pop("errors", None)
+                if kind == "control_request" and self.permission_handler:
+                    decision = await self.permission_handler(event)
+                    await self.send({"type": "control_response", "response": {
+                        "subtype": "success", "request_id": event["request_id"], "response": decision}})
+                    continue
+                if kind == "control_response" and self.permission_handler:
+                    yield event
+                if kind == "user" and isinstance(event.get("message", {}).get("content"), list):
+                    yield event
+                if kind in {"stream_event", "assistant", "result"}:
+                    yield event
+                if kind == "result":
+                    if event.get("is_error"):
+                        raise RuntimeError("Penny Claude reported a failed turn; see the phone result.")
+                    return
+
+    async def close(self):
+        if self.process is not None and self.process.returncode is None:
+            self.process.terminate()
+            try:
+                await asyncio.wait_for(self.process.wait(), 5)
+            except asyncio.TimeoutError:
+                self.process.kill()
+                await self.process.wait()
+        if self.stderr_task is not None:
+            await self.stderr_task
+
+
+class PennyWorker(EchoWorker):
+    def __init__(self, client, oauth, profile, model, cwd):
+        super().__init__(client, oauth)
+        self.title = "Penny live bridge test"
+        self.model = model
+        self.claude = PennyClaude(profile, model, self.local_session, cwd)
+
+    async def answer(self, payload):
+        async for event in self.claude.turn(payload["message"]):
+            event = {**event, "session_id": self.local_session}
+            event.setdefault("uuid", self.payload("unused")["uuid"])
+            if event["type"] == "result":
+                event["user_message_uuid"] = payload.get("uuid")
+            await self.events(event)
+
+    async def close(self):
+        try:
+            await self.claude.close()
+        finally:
+            await super().close()
+
+
+async def run(seconds):
+    profile, model = read_profile()
+    async with httpx.AsyncClient(headers={"anthropic-version": "2023-06-01",
+        "User-Agent": "penny-rc-text-probe/0.1"}, timeout=httpx.Timeout(30, read=None), trust_env=False) as client:
+        # A failing health check never starts or restarts a gateway.
+        response = await client.get(profile["gateway_base_url"].rstrip("/") + "/health", timeout=5)
+        if response.status_code != 200:
+            raise RuntimeError("Configured Penny gateway is not healthy.")
+        with tempfile.TemporaryDirectory(prefix="penny-rc-text-") as cwd:
+            worker = PennyWorker(client, read_login(), profile, model, cwd)
+            tasks = []
+            try:
+                await worker.start()
+                tasks = [asyncio.create_task(worker.listen()), asyncio.create_task(worker.heartbeat())]
+                done, _ = await asyncio.wait(tasks, timeout=seconds, return_when=asyncio.FIRST_COMPLETED)
+                for task in done:
+                    task.result()
+            finally:
+                for task in tasks:
+                    task.cancel()
+                await asyncio.gather(*tasks, return_exceptions=True)
+                await worker.close()
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--seconds", type=int, default=600)
+    args = parser.parse_args()
+    try:
+        asyncio.run(run(max(1, min(args.seconds, 1800))))
+    except KeyboardInterrupt:
+        pass
+    except (RuntimeError, TimeoutError, httpx.HTTPError):
+        print("Penny text probe failed; check gateway availability and Claude login. No gateway was restarted.")
+        raise SystemExit(1)

package/standalone/remote/rc_project.py

@@ -0,0 +1,167 @@
+"""Experimental Penny project launcher with phone Read/Edit approvals and Stop.
+
+Sessions persist after Ctrl+C. Resume is supported only at completed-turn boundaries.
+"""
+
+import argparse
+import asyncio
+import fcntl
+import json
+import os
+from pathlib import Path
+import shlex
+import uuid
+
+import httpx
+
+from rc_echo import EchoWorker, read_login
+from rc_penny import read_profile
+from rc_restart import RestartWorker
+from rc_tools import ToolsWorker
+from rc_local import ensure_inactive, phone_history, read_local
+
+
+class ProjectWorker(RestartWorker, ToolsWorker):
+    def __init__(self, client, oauth, profile, model, directory, project, local=None):
+        super().__init__(client, oauth, profile, model, directory, project)
+        self.title = "Penny: " + Path(self.cwd).name
+        self.phase = "idle"
+        self.history = []
+        if self.resuming:
+            saved = json.loads(self.state_path.read_text())
+            if saved.get("native_config_dir"):
+                self.extra_state = {"native_config_dir": saved["native_config_dir"],
+                                    "history_synced": saved.get("history_synced", False)}
+                ensure_inactive(saved["native_config_dir"], self.local_session)
+                self.claude.persistence_dir = Path(saved["native_config_dir"])
+                self.claude.resume = True
+                if not self.extra_state["history_synced"]:
+                    local = read_local(project, self.local_session, saved["native_config_dir"])
+        if local:
+            self.local_session = local["session_id"]
+            self.claude.session_id = self.local_session
+            self.claude.persistence_dir = Path(local["config_dir"])
+            self.claude.resume = True
+            self.extra_state = {"native_config_dir": local["config_dir"], "history_synced": False}
+            self.history = list(phone_history(local["records"], self.local_session))
+
+    async def start(self):
+        await super().start()
+        if self.extra_state and not self.extra_state["history_synced"]:
+            for offset in range(0, len(self.history), 20):
+                await self.events(*self.history[offset:offset + 20])
+            self.extra_state["history_synced"] = True
+            self.save("idle")
+        print("Local session: " + self.local_session, flush=True)
+        print("Return to terminal: penny claude --resume " + self.local_session, flush=True)
+
+    async def handle(self, envelope):
+        event_id = envelope.get("event_id")
+        is_new_user = (event_id and event_id not in self.seen and event_id not in self.queued_ids
+                       and envelope.get("payload", {}).get("type") == "user")
+        if is_new_user:
+            self.phase = "busy"
+            self.save(self.phase)
+        await ToolsWorker.handle(self, envelope)
+        self.save(self.phase)
+
+    async def process_turns(self):
+        while not self.stopping:
+            envelope = await self.inbox.get()
+            self.active_turn = True
+            try:
+                await EchoWorker.handle(self, envelope)
+                self.queued_ids.discard(envelope["event_id"])
+                self.phase = "busy" if self.queued_ids else "idle"
+                self.save(self.phase)
+                print("Turn saved." if self.phase == "idle" else "Next turn queued.", flush=True)
+            finally:
+                self.active_turn = False
+                self.inbox.task_done()
+
+
+async def run(project, state_dir, effort, local_session=None, continue_local=False):
+    directory = Path(state_dir).resolve()
+    directory.mkdir(mode=0o700, parents=True, exist_ok=True)
+    with (directory / "lock").open("w") as lock:
+        try:
+            fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            raise RuntimeError("This remote session is already running.") from None
+        profile, model = read_profile()
+        local = None
+        state_path = directory / "bridge.json"
+        if local_session or continue_local:
+            if state_path.exists():
+                raise RuntimeError("Use a fresh state folder for a local session handoff.")
+            local = read_local(project, local_session)
+            model = local["model"] or model
+        elif state_path.exists():
+            saved = json.loads(state_path.read_text())
+            if saved.get("native_config_dir"):
+                model = saved["model"]
+        async with httpx.AsyncClient(headers={"anthropic-version": "2023-06-01",
+            "User-Agent": "penny-rc-project/0.1"}, timeout=httpx.Timeout(30, read=None), trust_env=False) as client:
+            response = await client.get(profile["gateway_base_url"].rstrip("/") + "/health", timeout=5)
+            if response.status_code != 200:
+                raise RuntimeError("Configured Penny gateway is not healthy.")
+            worker = ProjectWorker(client, read_login(), profile, model, directory, project, local)
+            worker.claude.effort = effort
+            tasks = []
+            try:
+                await worker.start()
+                print("PROJECT " + worker.cwd, flush=True)
+                print("Read/Edit ask on your phone. Stop cancels the current turn. Ctrl+C disconnects.", flush=True)
+                print("Resume: penny remote --resume " + shlex.quote(str(directory)), flush=True)
+                tasks = [asyncio.create_task(worker.listen()), asyncio.create_task(worker.heartbeat()),
+                         asyncio.create_task(worker.process_turns())]
+                done, _ = await asyncio.wait(tasks, return_when=asyncio.FIRST_COMPLETED)
+                for task in done:
+                    task.result()
+            finally:
+                for task in tasks:
+                    task.cancel()
+                await asyncio.gather(*tasks, return_exceptions=True)
+                await worker.close()
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("project", nargs="?", default=None, help="Project folder (defaults to current directory)")
+    parser.add_argument("--resume", metavar="STATE_FOLDER", help="Resume a saved Penny remote session")
+    parser.add_argument("--state-dir", help="State folder for a new session")
+    local_group = parser.add_mutually_exclusive_group()
+    local_group.add_argument("--continue", dest="continue_local", action="store_true",
+                             help="Hand off the latest completed local Claude conversation in this project")
+    local_group.add_argument("--local-session", metavar="UUID", help="Hand off a specific local Claude session")
+    parser.add_argument("--effort", choices=["low", "medium", "high"], default="low")
+    args = parser.parse_args()
+    if args.resume and args.state_dir:
+        parser.error("Use --resume or --state-dir, not both.")
+    if args.resume and (args.local_session or args.continue_local):
+        parser.error("Use --resume for a bridge session, or --continue/--local-session for a local handoff.")
+    config_root = Path(os.environ.get("XDG_CONFIG_HOME", str(Path.home() / ".config")))
+    directory = args.resume or args.state_dir or str(config_root / "pennyrouter/remote" / str(uuid.uuid4()))
+    project = args.project
+    if args.resume:
+        state_path = Path(directory).expanduser() / "bridge.json"
+        if not state_path.is_file():
+            parser.error("No saved remote session found in that folder.")
+        saved = json.loads(state_path.read_text())
+        project = project or saved["cwd"]
+    else:
+        project = project or str(Path.cwd())
+        if (Path(directory).expanduser() / "bridge.json").exists():
+            parser.error("State folder already contains a session; use --resume.")
+    asyncio.run(run(Path(project).expanduser(), Path(directory).expanduser(), args.effort,
+                    args.local_session, args.continue_local))
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except KeyboardInterrupt:
+        print("Disconnected. The session remains available to resume.")
+    except (RuntimeError, TimeoutError, httpx.HTTPError) as error:
+        print(str(error) if isinstance(error, RuntimeError) else "Remote session stopped after a network or timeout failure.")
+        raise SystemExit(1)

package/standalone/remote/rc_restart.py

@@ -0,0 +1,145 @@
+"""Completed-turn restart probe. State survives exit; credentials are never saved.
+
+Run with a fresh --state-dir, send one phone message, then rerun the same command.
+Tools are disabled. An unfinished turn blocks resume rather than being replayed.
+"""
+
+import argparse
+import asyncio
+import fcntl
+import json
+import os
+from pathlib import Path
+
+import httpx
+
+from rc_echo import BASE, read_login
+from rc_penny import PennyWorker, read_profile
+
+
+class RestartWorker(PennyWorker):
+    def __init__(self, client, oauth, profile, model, directory, project=None):
+        self.directory = Path(directory).resolve()
+        self.extra_state = {}
+        self.directory.mkdir(mode=0o700, parents=True, exist_ok=True)
+        self.state_path = self.directory / "bridge.json"
+        cwd = Path(project).resolve() if project else self.directory / "workspace"
+        if project:
+            if not cwd.is_dir():
+                raise RuntimeError("Project folder does not exist.")
+        else:
+            cwd.mkdir(mode=0o700, exist_ok=True)
+        super().__init__(client, oauth, profile, model, str(cwd))
+        self.cwd = str(cwd)
+        self.title = "Penny restart recovery test"
+        self.completed = False
+        self.resuming = self.state_path.exists()
+        if self.resuming:
+            state = json.loads(self.state_path.read_text())
+            if state["phase"] != "idle":
+                raise RuntimeError("An unfinished turn was recorded. Resume is blocked to avoid replaying it.")
+            if state["model"] != model:
+                raise RuntimeError("Resume requires the original model configuration.")
+            if state.get("cwd", str(cwd)) != str(cwd):
+                raise RuntimeError("Resume requires the original project folder.")
+            self.session = state["remote_session"]
+            self.local_session = state["local_session"]
+            self.last_event_id = state["cursor"]
+            self.seen = set(state["seen"])
+            self.replies = state["replies"]
+            self.claude.session_id = self.local_session
+            self.claude.resume = self.replies > 0
+        self.claude.persistence_dir = self.directory / "claude"
+        self.claude.persistence_dir.mkdir(mode=0o700, exist_ok=True)
+
+    def save(self, phase):
+        state = {"version": 1, "phase": phase, "remote_session": self.session,
+                 "local_session": self.local_session, "model": self.model,
+                 "cursor": self.last_event_id, "seen": sorted(self.seen), "replies": self.replies,
+                 "cwd": self.cwd, **self.extra_state}
+        temporary = self.state_path.with_suffix(".tmp")
+        descriptor = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        with os.fdopen(descriptor, "w") as handle:
+            json.dump(state, handle)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, self.state_path)
+
+    async def start(self):
+        if not self.resuming:
+            await super().start()
+        else:
+            bridge = await self.api("POST", self.path + "/bridge", {}, account=True)
+            if bridge["api_base_url"].rstrip("/") != BASE:
+                raise RuntimeError("Unexpected worker host; refusing to forward credentials.")
+            self.worker_token = bridge["worker_jwt"]
+            self.epoch = int(bridge["worker_epoch"])
+            await self.status("idle")
+            print(f"RESUMED https://claude.ai/code/{self.session}", flush=True)
+        self.save("idle")
+
+    async def handle(self, envelope):
+        is_turn = envelope.get("payload", {}).get("type") == "user" and envelope.get("event_id") not in self.seen
+        if is_turn:
+            self.save("busy")
+        await super().handle(envelope)
+        self.save("idle")
+        if is_turn:
+            self.completed = True
+            self.stopping = True
+            print("Completed turn saved. Restart this command to continue on the same phone link.", flush=True)
+
+    async def close(self):
+        self.stopping = True
+        await self.claude.close()
+        # Preserve the remote session instead of the disposable probes' archive policy.
+        if self.worker_token:
+            await self.api("PUT", self.path + "/worker", {
+                "worker_epoch": self.epoch, "connection_status": "disconnected"})
+        self.oauth = self.worker_token = ""
+
+
+async def run(directory, seconds):
+    directory = Path(directory).resolve()
+    directory.mkdir(mode=0o700, parents=True, exist_ok=True)
+    with (directory / "lock").open("w") as lock:
+        try:
+            fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            raise RuntimeError("Another restart probe is using this state folder.") from None
+        profile, model = read_profile()
+        async with httpx.AsyncClient(headers={"anthropic-version": "2023-06-01",
+            "User-Agent": "penny-rc-restart-probe/0.1"}, timeout=httpx.Timeout(30, read=None), trust_env=False) as client:
+            response = await client.get(profile["gateway_base_url"].rstrip("/") + "/health", timeout=5)
+            if response.status_code != 200:
+                raise RuntimeError("Configured Penny gateway is not healthy.")
+            worker = RestartWorker(client, read_login(), profile, model, directory)
+            tasks = []
+            try:
+                await worker.start()
+                tasks = [asyncio.create_task(worker.listen()), asyncio.create_task(worker.heartbeat())]
+                done, _ = await asyncio.wait(tasks, timeout=seconds, return_when=asyncio.FIRST_COMPLETED)
+                for task in done:
+                    task.result()
+                if worker.completed:
+                    # The stream cursor advances after handle() returns.
+                    worker.save("idle")
+            finally:
+                for task in tasks:
+                    task.cancel()
+                await asyncio.gather(*tasks, return_exceptions=True)
+                await worker.close()
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--state-dir", required=True)
+    parser.add_argument("--seconds", type=int, default=900)
+    args = parser.parse_args()
+    try:
+        asyncio.run(run(args.state_dir, max(1, min(args.seconds, 1800))))
+    except KeyboardInterrupt:
+        pass
+    except (RuntimeError, httpx.HTTPError) as error:
+        print(str(error) if isinstance(error, RuntimeError) else "Network request failed.")
+        raise SystemExit(1)