pennyrouter 0.3.46 → 0.3.48

package/README.md

@@ -334,3 +334,60 @@ It does not delete PennyRouter accounts, credits, or remote API keys.
 ## License
 
 MIT
+
+### Experimental phone control
+
+`penny remote [project-folder]` starts a fresh Claude phone session backed by
+Penny. Keep the terminal running and open the printed `claude.ai/code` link on
+your phone. Claude subscription login and a healthy configured Penny gateway
+are required. This launcher uses an experimental, undocumented Remote Control
+protocol and currently supports macOS and Linux with Python 3.11+ and `httpx`.
+It does not start or restart a gateway.
+
+For a packaged installation, set up the Python environment once:
+
+```sh
+python3 -m venv ~/.config/pennyrouter/remote-venv
+~/.config/pennyrouter/remote-venv/bin/python -m pip install httpx
+```
+
+Alternatively set `PENNY_REMOTE_PYTHON` to an existing Python 3.11+ environment
+with `httpx`. Repository development uses the gateway virtual environment.
+
+Only Read and Edit tools are enabled, confined to the selected project; each
+operation asks for approval on the phone. Shell commands and file creation are
+not supported yet. Stop interrupts the current turn. Ctrl+C disconnects while
+preserving the phone session and local transcript. The launcher prints a
+`penny remote --resume <state-folder>` command to reopen that same conversation.
+Resume requires a completed turn; an unfinished checkpoint blocks replay.
+Archive sessions you no longer need through Claude. Transcripts remain locally
+in the printed state folder (by default `~/.config/pennyrouter/remote/<id>`).
+
+From this repository, without updating the installed Penny command:
+
+```sh
+node packages/pennyrouter-cli/bin/penny.js remote /path/to/project
+```
+
+#### Hand off a terminal conversation
+
+Finish the current turn and exit the local `penny claude` chat. From that same
+project directory, run:
+
+```sh
+penny remote --continue
+```
+
+This selects the most recently saved local Claude session in that project.
+Alternatively, `penny remote --local-session <UUID>` selects an exact session.
+The bridge resumes the original native transcript and places its visible text
+history in the new phone conversation. Tool results and reasoning remain in
+Claude's native context; only visible chat text is mirrored into the phone UI.
+An active local session or an unfinished final turn blocks the handoff.
+
+To return to terminal chat, disconnect the bridge with Ctrl+C and run the
+printed `penny claude --resume <UUID>` command from the same project. The phone
+turns are saved in that original transcript. This is a sequential handoff;
+the interactive terminal and the bridge cannot run the same session together.
+The bridge continues to offer only its current Read/Edit tools, even when the
+original terminal conversation used additional tools.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pennyrouter",
-  "version": "0.3.46",
+  "version": "0.3.48",
   "description": "Install and manage PennyRouter local coding-agent integrations.",
   "homepage": "https://pennyrouter.com",
   "bugs": {
@@ -25,7 +25,7 @@
   ],
   "scripts": {
     "start": "node ./bin/pennyrouter.js",
-    "check": "node --check ./bin/pennyrouter.js && node --check ./bin/penny.js && find src -name '*.js' -print0 | xargs -0 -n1 node --check && node --test src/cli.test.js && node src/session.test.js && node src/statusline.test.js && node src/harnesses/claude-code.test.js && node src/harnesses/codex.test.js && node src/harnesses/opencode.test.js && node src/launch.test.js && node src/thread-session.test.js && node src/thread-session-codex.test.js && node src/mcp-register.test.js && node src/mcp.test.js"
+    "check": "node --check ./bin/pennyrouter.js && node --check ./bin/penny.js && find src -name '*.js' -print0 | xargs -0 -n1 node --check && node --test src/cli.test.js src/remote.test.js && node src/session.test.js && node src/statusline.test.js && node src/harnesses/claude-code.test.js && node src/harnesses/codex.test.js && node src/harnesses/opencode.test.js && node src/launch.test.js && node src/thread-session.test.js && node src/thread-session-codex.test.js && node src/mcp-register.test.js && node src/mcp.test.js"
   },
   "dependencies": {
     "@xterm/addon-fit": "^0.10.0",

package/src/cli.js

@@ -6,6 +6,7 @@ import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import { aiderHarness } from "./harnesses/aider.js";
 import { runMcpServer } from "./mcp.js";
+import { runPennyRemote } from "./remote.js";
 import { mcpStatus, registerMcp } from "./mcp-register.js";
 
 /** The harnesses that can run an MCP server. The other supported harnesses cannot. */
@@ -119,6 +120,10 @@ const PENNY_COMMAND_BY_HARNESS = Object.fromEntries(
 const LAUNCHABLE_HARNESS_IDS = Object.keys(PENNY_COMMAND_BY_HARNESS);
 
 export async function main(argv = process.argv.slice(2)) {
+  if (argv[0] === "remote") {
+    process.exitCode = await runPennyRemote(argv.slice(1));
+    return;
+  }
   const { command, flags } = parseArgs(argv);
 
   if (flags.help || command === "help") {

package/src/launch.js

@@ -21,6 +21,7 @@ import { basename, dirname, join, resolve } from "node:path";
 import { randomUUID } from "node:crypto";
 
 import { configureClaudeCodeStatusline } from "./statusline.js";
+import { runPennyRemote } from "./remote.js";
 import {
   fetchClaudeCodeModels,
   upgradeClaudeCodeModelValue,
@@ -273,6 +274,12 @@ async function copyRuntime() {
   // command so it can use the exact unnamespaced name in every Claude session.
   await rm(join(destination, "claude-plugin"), { recursive: true, force: true });
   await cp(join(source, "package.json"), join(destination, "package.json"), { force: true });
+  const remoteSource = join(source, "standalone", "remote");
+  if (await stat(remoteSource).then(() => true, () => false)) {
+    const remoteDestination = join(destination, "standalone", "remote");
+    await rm(remoteDestination, { recursive: true, force: true });
+    await cp(remoteSource, remoteDestination, { recursive: true, force: true });
+  }
 }
 
 // npx and local installs hoist dependencies above the package, so walk up like Node's resolver.
@@ -1555,7 +1562,8 @@ async function runPennyCompare(args) {
 export async function runPenny(argv = process.argv.slice(2)) {
   const harness = argv[0];
   if (!harness || harness === "help" || harness === "--help" || harness === "-h") {
-    console.log("Usage: penny <claude|codex|opencode|compare> [arguments...]");
+    console.log("Usage: penny <claude|codex|opencode|compare|remote> [arguments...]");
+    console.log("       penny remote [project] opens an experimental phone-controlled session.");
     console.log("       penny compare launches Penny Compare; install it with `npx pennyrouter compare`.");
     console.log("       penny <claude|codex|opencode> [--penny-profile <name>] [native arguments...]");
     console.log("       --private / --cloud select the like-named profile.");
@@ -1563,6 +1571,7 @@ export async function runPenny(argv = process.argv.slice(2)) {
     return 0;
   }
   if (harness === "compare") return runPennyCompare(argv.slice(1));
+  if (harness === "remote") return runPennyRemote(argv.slice(1));
   if (!["claude", "codex", "opencode"].includes(harness)) {
     throw new Error(`Unknown Penny command "${harness}". Try penny claude, penny codex, penny opencode, or penny compare.`);
   }

package/src/remote.js

@@ -0,0 +1,40 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, resolve, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export function remoteRuntime(packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..')) {
+  const repository = resolve(packageRoot, '../..');
+  const developmentScript = join(repository, 'scripts/interactive_probe/rc_project.py');
+  const developmentPython = join(repository, 'apps/gateway/.venv/bin/python');
+  const configRoot = join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'pennyrouter');
+  const python = process.env.PENNY_REMOTE_PYTHON ||
+    (existsSync(developmentPython) ? developmentPython : join(configRoot, 'remote-venv/bin/python'));
+  return { python, script: existsSync(developmentScript) ? developmentScript :
+    join(packageRoot, 'standalone/remote/rc_project.py') };
+}
+
+export async function runPennyRemote(args) {
+  if (process.platform === 'win32') throw new Error('Penny remote currently requires macOS or Linux.');
+  const { python, script } = remoteRuntime();
+  if (!existsSync(script)) throw new Error('Penny remote runtime is missing. Refresh your Penny installation.');
+  const checked = spawnSync(python, ['-c', 'import sys; assert sys.version_info >= (3, 11); import httpx'],
+    { stdio: 'pipe' });
+  if (checked.error || checked.status !== 0) {
+    throw new Error('Penny remote needs Python 3.11+ with httpx. Create ~/.config/pennyrouter/remote-venv with python3 -m venv, then install httpx there; or set PENNY_REMOTE_PYTHON to an existing environment.');
+  }
+  console.log('Penny remote (experimental)');
+  const child = spawn(python, ['-u', script, ...args], { stdio: 'inherit' });
+  // Ctrl+C reaches both processes in a terminal. Let Python disconnect cleanly.
+  const onInterrupt = () => {};
+  process.on('SIGINT', onInterrupt);
+  try {
+    return await new Promise((done, fail) => {
+      child.once('error', fail);
+      child.once('exit', (code, signal) => done(code ?? (signal === 'SIGINT' ? 130 : 1)));
+    });
+  } finally {
+    process.removeListener('SIGINT', onInterrupt);
+  }
+}

package/src/remote.test.js

@@ -0,0 +1,37 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { remoteRuntime } from './remote.js';
+
+test('installed remote runtime uses packaged script and explicit Python', () => {
+  const before = process.env.PENNY_REMOTE_PYTHON;
+  process.env.PENNY_REMOTE_PYTHON = '/chosen/python';
+  try {
+    const runtime = remoteRuntime('/nonexistent/package');
+    assert.equal(runtime.python, '/chosen/python');
+    assert.equal(runtime.script, '/nonexistent/package/standalone/remote/rc_project.py');
+  } finally {
+    if (before === undefined) delete process.env.PENNY_REMOTE_PYTHON;
+    else process.env.PENNY_REMOTE_PYTHON = before;
+  }
+});
+
+test('repository checkout uses its probe and gateway environment', () => {
+  const folder = mkdtempSync(join(tmpdir(), 'penny-remote-runtime-'));
+  const before = process.env.PENNY_REMOTE_PYTHON;
+  delete process.env.PENNY_REMOTE_PYTHON;
+  try {
+    mkdirSync(join(folder, 'scripts/interactive_probe'), { recursive: true });
+    mkdirSync(join(folder, 'apps/gateway/.venv/bin'), { recursive: true });
+    writeFileSync(join(folder, 'scripts/interactive_probe/rc_project.py'), '');
+    writeFileSync(join(folder, 'apps/gateway/.venv/bin/python'), '');
+    const runtime = remoteRuntime(join(folder, 'packages/pennyrouter-cli'));
+    assert.equal(runtime.script, join(folder, 'scripts/interactive_probe/rc_project.py'));
+    assert.equal(runtime.python, join(folder, 'apps/gateway/.venv/bin/python'));
+  } finally {
+    rmSync(folder, { recursive: true, force: true });
+    if (before !== undefined) process.env.PENNY_REMOTE_PYTHON = before;
+  }
+});

package/standalone/penny-compare

@@ -102,10 +102,10 @@ choose() {
 claude_models=(default opus sonnet haiku fable)
 
 # The current Codex catalog (apps/gateway/pennyrouter/main.py, _CODEX_NATIVE_MODELS), newest
-# first. That tuple also carries three PennyRouter-only aliases (gpt-penny-deepseek/glm/grok)
+# first, without its legacy GPT-5.4 rows. That tuple also carries three PennyRouter-only aliases (gpt-penny-deepseek/glm/grok)
 # that route to other providers entirely; those are left out here since a native Codex pane would
 # reject them, making an "identical model on both sides" comparison impossible.
-codex_models=(default gpt-5.6-sol gpt-5.6-terra gpt-5.6-luna gpt-5.5 gpt-5.4 gpt-5.4-mini)
+codex_models=(default gpt-6.1-sol gpt-6-astra gpt-6-sol gpt-6-luna gpt-5.6-sol gpt-5.6-terra gpt-5.6-luna gpt-5.5)
 
 # OpenCode's configured default is the only portable alias; users can pass a full
 # provider/model id with --model when both panes must use a specific model.

package/standalone/rates.json

@@ -1,6 +1,6 @@
 {
  "source": "bifrost_datasheet",
- "generated_at": "2026-09-29T15:31:58+00:00",
+ "generated_at": "2026-10-04T20:39:28+00:00",
  "order": [
   "input",
   "cache_read",
@@ -1027,6 +1027,25 @@
     ]
    }
   },
+  "gpt-6.1-sol": {
+   "rates": [
+    2e-06,
+    1e-07,
+    2.5e-06,
+    2.5e-06,
+    1e-05
+   ],
+   "above": {
+    "threshold": 272000,
+    "rates": [
+     4e-06,
+     2e-07,
+     5e-06,
+     5e-06,
+     1.5e-05
+    ]
+   }
+  },
   "gpt-daybreak-blue-latest": {
    "rates": [
     4e-06,

package/standalone/remote/rc_echo.py

@@ -0,0 +1,298 @@
+"""Experimental, text-only worker for Anthropic's captured Remote Control protocol.
+
+No inference, tools, shell execution, or gateway changes. Uses a fresh session and
+the current user's full-scope Claude login; credentials remain in memory. This is
+an undocumented protocol probe, not supported native Claude Code integration.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import os
+from pathlib import Path
+import subprocess
+import sys
+import time
+import uuid
+
+import httpx
+
+BASE = "https://api.anthropic.com"
+MODEL = "claude-sonnet-5-5"
+REPLY = "Penny echo bridge received your phone message. No model or tools were used."
+
+
+def read_login() -> str:
+    """Read an existing login without refreshing or persisting credentials."""
+    credentials = Path(os.environ.get("CLAUDE_CONFIG_DIR", str(Path.home() / ".claude"))) / ".credentials.json"
+    if credentials.exists():
+        data = json.loads(credentials.read_text())
+    elif sys.platform == "darwin":
+        result = subprocess.run(
+            ["security", "find-generic-password", "-s", "Claude Code-credentials", "-w"],
+            capture_output=True, text=True, check=False,
+        )
+        if result.returncode:
+            raise RuntimeError("Cannot read Claude login. Sign in with Claude Code /login first.")
+        data = json.loads(result.stdout)
+    else:
+        raise RuntimeError("No Claude login found. Sign in with Claude Code /login first.")
+    oauth = data.get("claudeAiOauth", {})
+    if oauth.get("expiresAt", 0) < (time.time() + 600) * 1000:
+        raise RuntimeError("Claude login expires too soon. Refresh it through Claude Code /login.")
+    token = oauth.get("accessToken", "")
+    if not token.startswith("sk-ant-oat"):
+        raise RuntimeError("A Claude subscription OAuth login is required.")
+    return token
+
+
+class EchoWorker:
+    def __init__(self, client: httpx.AsyncClient, oauth: str):
+        self.client = client
+        self.oauth = oauth
+        self.worker_token = ""
+        self.session = ""
+        self.local_session = str(uuid.uuid4())
+        self.epoch = 0
+        self.seen: set[str] = set()
+        self.stopping = False
+        self.replies = 0
+        self.title = "Penny echo bridge test"
+        self.model = MODEL
+        self.tools = []
+        self.cwd = "/private/tmp"
+        self.last_event_id = ""
+        self.force_reconnect = asyncio.Event()
+        self.stream_connections = 0
+
+    async def api(self, method: str, path: str, body=None, *, account=False):
+        # Retry only the worker operations, not account-level session creation.
+        # Event bodies keep their original UUIDs across retries for server deduplication.
+        for attempt in range(5):
+            try:
+                response = await self.client.request(method, BASE + path,
+                    headers={"Authorization": "Bearer " + (self.oauth if account else self.worker_token)},
+                    timeout=30,
+                    **({"json": body} if body is not None else {}))
+            except httpx.TransportError:
+                if account or attempt == 4:
+                    raise
+            else:
+                if account or response.status_code not in {429, 500, 502, 503, 504} or attempt == 4:
+                    break
+            await asyncio.sleep(min(2 ** attempt, 8))
+        if not response.is_success:
+            # Never include raw bodies/headers: private API errors may contain credentials.
+            raise RuntimeError(f"{method} {path.rsplit('/', 1)[-1]} returned HTTP {response.status_code}")
+        return response.json() if response.content else {}
+
+    @property
+    def path(self):
+        return f"/v1/code/sessions/{self.session}"
+
+    def payload(self, kind, **fields):
+        return {"type": kind, "session_id": self.local_session, "uuid": str(uuid.uuid4()), **fields}
+
+    async def events(self, *payloads):
+        result = await self.api("POST", self.path + "/worker/events", {
+            "worker_epoch": self.epoch, "events": [{"payload": p} for p in payloads]})
+        print(f"Published {','.join(p['type'] for p in payloads)}; subscribers={result.get('has_subscribers')}", flush=True)
+
+    async def delivery(self, event_id, status):
+        await self.api("POST", self.path + "/worker/events/delivery", {
+            "worker_epoch": self.epoch, "updates": [{"event_id": event_id, "status": status}]})
+
+    async def status(self, status):
+        await self.api("PUT", self.path + "/worker", {
+            "worker_epoch": self.epoch, "worker_status": status,
+            "requires_action_details": None})
+
+    async def start(self):
+        result = await self.api("POST", "/v1/code/sessions", {
+            "title": self.title, "bridge": {}, "tags": ["remote-control-repl", "penny-echo-probe"],
+            "config": {"cwd": self.cwd, "model": self.model, "sources": [], "outcomes": [],
+                       "reuse_outcome_branches": False}}, account=True)
+        self.session = result["session"]["id"]
+        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.api("GET", self.path + "/worker")
+        await self.api("PUT", self.path + "/worker", {
+            "worker_epoch": self.epoch, "external_metadata": {"permission_mode": "default", "model": self.model}})
+        await self.status("idle")
+        await self.events(self.payload("system", subtype="init", cwd=self.cwd, tools=self.tools,
+            mcp_servers=[], model=self.model, permissionMode="default", apiKeySource="none",
+            output_style="default", agents=[], skills=[], plugins=[], slash_commands=[],
+            terminal_slash_commands=[], capabilities=[], analytics_disabled=True,
+            product_feedback_disabled=True))
+        print(f"OPEN https://claude.ai/code/{self.session}", flush=True)
+
+    async def handle(self, envelope):
+        event_id = envelope.get("event_id")
+        if not event_id or event_id in self.seen:
+            return
+        payload = envelope.get("payload", {})
+        kind = payload.get("type")
+        await self.delivery(event_id, "received")
+        print(f"Received {kind}" + (f"/{payload.get('request', {}).get('subtype')}" if kind == "control_request" else ""), flush=True)
+        if kind == "control_request":
+            request = payload.get("request", {})
+            subtype = request.get("subtype")
+            response = {"request_id": payload.get("request_id"), "subtype": "success"}
+            if subtype == "initialize":
+                response["response"] = {"commands": [], "agents": [], "output_style": "normal",
+                    "available_output_styles": ["normal"], "models": [], "account": {},
+                    "pid": os.getpid(), "inbound_read_receipts": True,
+                    "current_model": self.model, "current_permission_mode": "default"}
+                response.update(pending_permission_requests=list(getattr(self, "pending_permissions", {}).values()),
+                                pending_user_dialog_requests=[])
+            elif subtype == "end_session":
+                response["response"] = {}
+                self.stopping = True
+            else:
+                response.update(subtype="error", error="Echo probe supports only text messages and initialization.")
+            await self.events(self.payload("control_response", response=response))
+        elif kind == "user":
+            await self.delivery(event_id, "processing")
+            await self.status("running")
+            # Client-origin messages already exist in the remote transcript. Posting
+            # them again with a worker UUID creates a second visible input bubble.
+            await self.answer(payload)
+            await self.status("idle")
+            self.replies += 1
+        else:
+            raise RuntimeError("Unexpected inbound event type; stopping the echo probe.")
+        await self.delivery(event_id, "processed")
+        self.seen.add(event_id)
+
+    async def answer(self, payload):
+        message = {"id": "msg_" + uuid.uuid4().hex, "type": "message", "role": "assistant",
+                   "model": MODEL, "content": [], "stop_reason": None,
+                   "stop_sequence": None, "usage": {"input_tokens": 0, "output_tokens": 0}}
+        stream = [{"type": "message_start", "message": message},
+            {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}},
+            {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": REPLY}},
+            {"type": "content_block_stop", "index": 0},
+            {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence": None},
+             "usage": {"output_tokens": 0}}, {"type": "message_stop"}]
+        await self.events(*(self.payload("stream_event", event=e, parent_tool_use_id=None) for e in stream))
+        await self.events(self.payload("assistant", parent_tool_use_id=None,
+            message={**message, "content": [{"type": "text", "text": REPLY}], "stop_reason": "end_turn"}),
+            self.payload("result", subtype="success", result=REPLY, is_error=False,
+                user_message_uuid=payload.get("uuid"), duration_ms=0, duration_api_ms=0,
+                total_cost_usd=0, usage={"input_tokens": 0, "output_tokens": 0}, modelUsage={},
+                permission_denials=[], num_turns=1, stop_reason="end_turn", terminal_reason="completed"))
+
+    async def heartbeat(self):
+        while not self.stopping:
+            result = await self.api("POST", self.path + "/worker/heartbeat", {
+                "session_id": self.session, "worker_epoch": self.epoch,
+                "supports_heartbeat_probe": False, "current_interval_seconds": 20, "idle_seconds": 0})
+            await asyncio.sleep(max(5, min(60, result.get("heartbeat_interval_seconds", 20))))
+
+    async def _listen_once(self):
+        headers = {"Authorization": "Bearer " + self.worker_token, "Accept": "text/event-stream"}
+        if self.last_event_id:
+            headers["Last-Event-ID"] = self.last_event_id
+        async with self.client.stream("GET", BASE + self.path + "/worker/events/stream",
+            headers=headers) as response:
+            if response.status_code != 200:
+                if response.status_code in {429, 500, 502, 503, 504}:
+                    raise httpx.ReadError("Transient worker stream failure")
+                raise RuntimeError(f"Worker stream returned HTTP {response.status_code}")
+            self.stream_connections += 1
+            print(f"Worker stream connected #{self.stream_connections}; resuming={bool(self.last_event_id)}", flush=True)
+            data = []
+            frame_id = ""
+            async for line in response.aiter_lines():
+                if line.startswith("data:"):
+                    data.append(line[5:].lstrip())
+                elif line.startswith("id:"):
+                    frame_id = line[3:].strip()
+                elif not line and data:
+                    await self.handle(json.loads("\n".join(data)))
+                    if frame_id:
+                        self.last_event_id = frame_id
+                    data = []
+                    frame_id = ""
+                    if self.stopping:
+                        return
+
+    async def listen(self):
+        failures = 0
+        while not self.stopping:
+            reader = asyncio.create_task(self._listen_once())
+            forced = asyncio.create_task(self.force_reconnect.wait())
+            cursor_before = self.last_event_id
+            try:
+                done, _ = await asyncio.wait([reader, forced], return_when=asyncio.FIRST_COMPLETED)
+                if forced in done:
+                    self.force_reconnect.clear()
+                    print("Simulating a three-second worker stream drop; keeping Claude alive", flush=True)
+                else:
+                    try:
+                        reader.result()
+                    except httpx.TransportError:
+                        pass
+                    if self.stopping:
+                        return
+                failures = 1 if self.last_event_id != cursor_before else failures + 1
+                if failures >= 5:
+                    raise RuntimeError("Worker stream reconnect attempts exhausted.")
+            finally:
+                reader.cancel()
+                forced.cancel()
+                await asyncio.gather(reader, forced, return_exceptions=True)
+            await asyncio.sleep(3 if forced in done else min(2 ** (failures - 1), 8))
+
+    async def close(self):
+        self.stopping = True
+        if not self.session:
+            return
+        try:
+            if self.worker_token:
+                await self.api("PUT", self.path + "/worker", {
+                    "worker_epoch": self.epoch, "connection_status": "disconnected"})
+        except (RuntimeError, httpx.HTTPError):
+            print("Worker disconnect update failed; attempting to archive the test session.", flush=True)
+        try:
+            await self.api("POST", self.path + "/archive", {}, account=True)
+            print(f"Archived test session; replies={self.replies}", flush=True)
+        except (RuntimeError, httpx.HTTPError):
+            print("Test session cleanup failed; archive Penny echo bridge test in Claude manually.", flush=True)
+        self.oauth = self.worker_token = ""
+
+
+async def run(seconds):
+    async with httpx.AsyncClient(headers={"anthropic-version": "2023-06-01",
+        "User-Agent": "penny-rc-echo-probe/0.1"}, timeout=httpx.Timeout(30, read=None), trust_env=False) as client:
+        worker = EchoWorker(client, read_login())
+        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, help="Test lifetime (default: 10 minutes)")
+    args = parser.parse_args()
+    try:
+        asyncio.run(run(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.", file=sys.stderr)
+        sys.exit(1)