pennyrouter 0.3.46 → 0.3.47

package/README.md

@@ -334,3 +334,37 @@ 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
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pennyrouter",
-  "version": "0.3.46",
+  "version": "0.3.47",
   "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/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)

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,120 @@
+"""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
+
+
+class ProjectWorker(RestartWorker, ToolsWorker):
+    def __init__(self, client, oauth, profile, model, directory, project):
+        super().__init__(client, oauth, profile, model, directory, project)
+        self.title = "Penny: " + Path(self.cwd).name
+        self.phase = "idle"
+
+    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):
+    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()
+        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)
+            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")
+    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.")
+    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))
+
+
+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,144 @@
+"""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.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}
+        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)

package/standalone/remote/rc_tools.py

@@ -0,0 +1,171 @@
+"""Remote file-tool approval probe confined to a disposable test folder.
+
+Only Read and Edit are available; every call asks the phone. No shell, MCP,
+permission-mode changes, or arbitrary control commands are forwarded.
+"""
+
+import argparse
+import asyncio
+import copy
+from pathlib import Path
+import tempfile
+
+import httpx
+
+from rc_echo import EchoWorker, read_login
+from rc_penny import PennyClaude, PennyWorker, read_profile
+
+
+def confined_input(cwd, request, tool_input):
+    if request.get("tool_name") not in {"Read", "Edit"} or not isinstance(tool_input, dict):
+        return False
+    path = tool_input.get("file_path")
+    if not isinstance(path, str) or not path:
+        return False
+    root = Path(cwd).resolve()
+    target = Path(path)
+    if not target.is_absolute():
+        target = root / target
+    try:
+        return target.resolve().is_relative_to(root) and target.resolve() != root
+    except (OSError, ValueError):
+        return False
+
+
+class ToolsWorker(PennyWorker):
+    def __init__(self, client, oauth, profile, model, cwd):
+        super().__init__(client, oauth, profile, model, cwd)
+        self.title = "Penny file approvals test"
+        self.cwd = cwd
+        self.tools = ["Read", "Edit"]
+        self.claude = PennyClaude(profile, model, self.local_session, cwd, self.permission)
+        self.pending_permissions = {}
+        self.permission_futures = {}
+        self.inbox = asyncio.Queue(maxsize=10)
+        self.queued_ids = set()
+        self.active_turn = False
+        self.disconnect_after_turns = 0
+
+    async def permission(self, event):
+        request = event.get("request", {})
+        denied = {"behavior": "deny", "message": "Only file operations inside this test folder are permitted."}
+        if request.get("subtype") != "can_use_tool" or not confined_input(self.cwd, request, request.get("input")):
+            return denied
+        request_id = event["request_id"]
+        future = asyncio.get_running_loop().create_future()
+        saved = copy.deepcopy(event)
+        self.pending_permissions[request_id] = saved
+        self.permission_futures[request_id] = future
+        print(f"Phone approval needed: {request['tool_name']}", flush=True)
+        try:
+            await self.events({**saved, "session_id": self.local_session, "uuid": self.payload("unused")["uuid"]})
+            async with asyncio.timeout(180):
+                decision = await future
+            if decision.get("behavior") == "allow":
+                tool_input = decision.get("updatedInput", request["input"])
+                if not confined_input(self.cwd, request, tool_input):
+                    return denied
+                # Accept one tool decision, never persistent permission updates.
+                return {"behavior": "allow", "updatedInput": tool_input}
+            return {"behavior": "deny", "message": "The user denied this tool from the phone."}
+        except TimeoutError:
+            return {"behavior": "deny", "message": "Phone approval timed out."}
+        finally:
+            self.pending_permissions.pop(request_id, None)
+            self.permission_futures.pop(request_id, None)
+
+    async def handle(self, envelope):
+        event_id = envelope.get("event_id")
+        if not event_id or event_id in self.seen or event_id in self.queued_ids:
+            return
+        payload = envelope.get("payload", {})
+        kind = payload.get("type")
+        if kind == "user":
+            self.queued_ids.add(event_id)
+            await self.inbox.put(envelope)
+            return
+        if kind == "control_response":
+            await self.delivery(event_id, "received")
+            response = payload.get("response", {})
+            request_id = response.get("request_id")
+            future = self.permission_futures.get(request_id)
+            if future is not None and not future.done():
+                decision = response.get("response", {}) if response.get("subtype") == "success" else {}
+                future.set_result(decision)
+                print(f"Phone decision: {decision.get('behavior', 'deny')}", flush=True)
+            else:
+                print("Ignored unmatched permission response", flush=True)
+            await self.delivery(event_id, "processed")
+            self.seen.add(event_id)
+            return
+        if kind == "control_request" and payload.get("request", {}).get("subtype") == "interrupt":
+            await self.delivery(event_id, "received")
+            for future in self.permission_futures.values():
+                if not future.done():
+                    future.set_result({"behavior": "deny"})
+            if self.active_turn:
+                await self.claude.interrupt(payload["request_id"])
+            else:
+                await self.events(self.payload("control_response", response={
+                    "subtype": "success", "request_id": payload.get("request_id"), "response": {}}))
+            await self.delivery(event_id, "processed")
+            self.seen.add(event_id)
+            return
+        await EchoWorker.handle(self, envelope)
+
+    async def process_turns(self):
+        while not self.stopping:
+            envelope = await self.inbox.get()
+            self.active_turn = True
+            try:
+                await EchoWorker.handle(self, envelope)
+                if self.disconnect_after_turns and self.replies == self.disconnect_after_turns:
+                    self.force_reconnect.set()
+            finally:
+                self.active_turn = False
+                self.queued_ids.discard(envelope["event_id"])
+                self.inbox.task_done()
+
+
+async def run(seconds, effort="low", disconnect_after_turns=0):
+    profile, model = read_profile()
+    async with httpx.AsyncClient(headers={"anthropic-version": "2023-06-01",
+        "User-Agent": "penny-rc-file-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.")
+        with tempfile.TemporaryDirectory(prefix="penny-rc-files-") as cwd:
+            (Path(cwd) / "note.txt").write_text("original test content\n")
+            worker = ToolsWorker(client, read_login(), profile, model, cwd)
+            worker.claude.effort = effort
+            worker.disconnect_after_turns = disconnect_after_turns
+            tasks = []
+            try:
+                await worker.start()
+                print("TEST FOLDER " + cwd, flush=True)
+                tasks = [asyncio.create_task(worker.listen()), asyncio.create_task(worker.heartbeat()),
+                         asyncio.create_task(worker.process_turns())]
+                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=900)
+    parser.add_argument("--effort", choices=["low", "medium", "high"], default="low")
+    parser.add_argument("--disconnect-after-turns", type=int, default=0,
+                        help="Simulate one three-second stream drop after this many completed turns")
+    args = parser.parse_args()
+    try:
+        asyncio.run(run(max(1, min(args.seconds, 1800)), args.effort, args.disconnect_after_turns))
+    except KeyboardInterrupt:
+        pass
+    except (RuntimeError, TimeoutError, httpx.HTTPError):
+        print("File approval probe stopped after a protocol, gateway, or timeout failure.")
+        raise SystemExit(1)

package/standalone/web-demo/claude-meter.mjs

@@ -84,6 +84,10 @@ function emptyTotals() {
     fresh_input: 0, output: 0, reasoning_output: 0, total: 0, cost: 0 };
 }
 
+function emptySideCalls() {
+  return { count: 0, cost: 0, cache_read: 0, cache_write: 0, fresh_input: 0, output: 0, total: 0, models: {} };
+}
+
 export class ClaudeMeter {
   constructor({ sessionId, cwd, side, role, label, variant, pricingProfile = 'standard', options = {} }) {
     this.sessionId = sessionId;
@@ -106,7 +110,7 @@ export class ClaudeMeter {
     this.transcriptPrints = new Map();
     this.chargedPrints = new Map();
     this.telemetry = new Map();
-    this.sideCalls = { count: 0, cost: 0, models: {} };
+    this.sideCalls = emptySideCalls();
     this.localReplyIds = new Set();
   }
 
@@ -162,6 +166,11 @@ export class ClaudeMeter {
       byModel.calls += 1; byModel.tokens += total; byModel.cost += cost;
       this.sideCalls.count += 1;
       this.sideCalls.cost += cost;
+      this.sideCalls.cache_read += read;
+      this.sideCalls.cache_write += write;
+      this.sideCalls.fresh_input += input;
+      this.sideCalls.output += output;
+      this.sideCalls.total += total;
     }
   }
 
@@ -287,11 +296,17 @@ export class ClaudeMeter {
     } finally { await handle.close(); }
   }
 
+  // `totals` is everything billed; `main` leaves out the side calls.
   snapshot() {
+    const side = this.sideCalls;
+    const main = { ...this.totals, cache_read: this.totals.cache_read - side.cache_read,
+      cache_write: this.totals.cache_write - side.cache_write, write_5m: this.totals.write_5m - side.cache_write,
+      fresh_input: this.totals.fresh_input - side.fresh_input, output: this.totals.output - side.output,
+      total: this.totals.total - side.total, cost: this.totals.cost - side.cost };
     return { side: this.side, role: this.role, label: this.label, variant: this.variant, options: this.options,
       harness: 'claude-code', cwd: this.cwd, pricing_profile: this.pricingProfile, session_id: this.sessionId,
       transcript_path: this.transcriptPath, model: this.model, call_count: this.calls.length,
-      totals: { ...this.totals }, local_replies: this.localReplyIds.size,
+      totals: { ...this.totals }, main, local_replies: this.localReplyIds.size,
       side_calls: { ...this.sideCalls, models: structuredClone(this.sideCalls.models) } };
   }
 }
@@ -454,7 +469,7 @@ export function galleryReport(left, right, { environment, harnessVersions }) {
   const penny = sides.find((side) => side.role === 'PENNY');
   if (!native || !penny || native.harness !== penny.harness) return null;
   const side = (snapshot) => ({ model: snapshot.model, call_count: snapshot.call_count, totals: snapshot.totals,
-    side_calls: snapshot.side_calls || { count: 0, cost: 0, models: {} } });
+    side_calls: snapshot.side_calls || emptySideCalls() });
   return JSON.stringify({ version: 1, harness: native.harness,
     harness_version: harnessVersions?.[native.harness === 'codex' ? 'codex' : 'claude'] || '',
     environment, native: side(native), penny: side(penny), finished_at: new Date().toISOString() });

package/standalone/web-demo/compare.html

@@ -31,6 +31,7 @@
     .bar .sync-on { color: var(--accent); border-color: #547a50; background: var(--accent-wash); }
     .bar .sync-off { color: #a0a0aa; border-color: #62626d; background: #292930; }
     #delta { color: var(--accent); }
+    .pane header #delta { margin-left: auto; white-space: nowrap; }
     #versions { margin-left: auto; color: #92929c; font-size: 12px; }
     #status { color: #b8b8c3; }
     @media (max-width: 760px) { .bar { overflow-x: auto; } #versions { display: none; } }
@@ -84,7 +85,7 @@
     .meter .field.read strong { color: var(--accent); }
     .meter .field.write strong { color: var(--warn); }
     .meter .field.in strong, .meter .field.out strong { color: #75ec45; }
-    .meter .field.side { color: #77777e; }
+    .meter .field.main, .meter .field.side { color: #77777e; }
     .meter .wait { display: none; color: #77777e; }
     .meter.waiting .wait { display: block; }
     .meter.waiting .field { display: none; }
@@ -214,7 +215,6 @@
     <button id="finish" disabled>Finish comparison</button>
     <button id="download-logs" hidden>Download logs</button>
     <button id="add-to-gallery" disabled title="Finish this comparison and share it in the PennyRouter gallery">Add to gallery</button>
-    <span id="delta" aria-live="polite"></span>
     <span id="versions"></span>
     <span id="status">Connecting…</span>
   </div>
@@ -225,6 +225,7 @@
         <div class="file-list" id="left-file-list" hidden><p>HTML files the agent writes will appear here.</p></div></div>
       </header><div class="meter" id="left-meter"></div><div class="terminal" id="left"></div></section>
     <section class="pane" id="right-pane"><header><strong class="label" id="right-label">PENNY</strong><span class="chip" id="right-chip" hidden></span>
+      <span id="delta" aria-live="polite"></span>
       <div class="files" id="right-files"><button class="newest" id="right-newest" hidden></button>
         <button class="count" id="right-files-count" aria-expanded="false" aria-controls="right-file-list">No files</button>
         <div class="file-list" id="right-file-list" hidden><p>HTML files the agent writes will appear here.</p></div></div>
@@ -801,6 +802,9 @@
     // Same abbreviation as hud.py: 1.2k, 3.45M.
     const abbreviate = (value) => value >= 1_000_000 ? `${(value / 1_000_000).toFixed(2)}M`
       : value >= 1_000 ? `${(value / 1_000).toFixed(1)}k` : String(value);
+    // Cents alone would round a cheap side call to $0.00.
+    const dollars = (value) => `$${value.toLocaleString('en-US',
+      { minimumFractionDigits: value < 1 ? 4 : 2, maximumFractionDigits: value < 1 ? 4 : 2 })}`;
     const reducedMotion = matchMedia('(prefers-reduced-motion: reduce)');
     const meters = {};
     const buildMeter = (side) => {
@@ -812,15 +816,16 @@
       model.append(role, name);
       root.append(model);
       const amounts = {};
-      for (const label of ['read', 'write', 'in', 'out', 'total', 'side', 'cost']) {
-        const field = document.createElement('span'); field.className = `field ${label}`;
+      // Token rows count the main thread only. Background calls Claude Code makes outside the
+      // transcript (auto-mode reviewer, titles) show only as `side` cost; the last row is main + side.
+      for (const [key, label] of [['read', 'read'], ['write', 'write'], ['in', 'in'], ['out', 'out'],
+        ['total', 'total'], ['main', 'main'], ['side', 'side'], ['cost', 'total']]) {
+        const field = document.createElement('span'); field.className = `field ${key}`;
         field.append(document.createTextNode(`${label} `));
-        amounts[label] = document.createElement('strong');
-        field.append(amounts[label]);
+        amounts[key] = document.createElement('strong');
+        field.append(amounts[key]);
         root.append(field);
       }
-      // Background calls (auto-mode reviewer, titles) that Claude Code makes outside the transcript.
-      amounts.side.parentElement.hidden = true;
       // Zeros would read as a measurement; the pane has simply not seen a turn yet.
       const wait = document.createElement('span'); wait.className = 'wait'; wait.textContent = 'waiting for first turn';
       root.append(wait);
@@ -844,7 +849,7 @@
         amounts.out.textContent = abbreviate(rolled.output);
         amounts.total.textContent = abbreviate(rolled.cache_read + rolled.cache_write +
           rolled.fresh_input + rolled.output);
-        amounts.cost.textContent = `$${meter.cost.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+        amounts.cost.textContent = dollars(meter.cost);
         if (Object.keys(rolled).some((key) => rolled[key] !== meter.targets[key])) settled = false;
       }
       if (settled) lastFrame = 0;
@@ -853,15 +858,15 @@
     const showMeter = (snapshot) => {
       const meter = meters[snapshot.side] ||= buildMeter(snapshot.side);
       const { totals } = snapshot;
+      const main = snapshot.main || totals;
       meter.role.textContent = snapshot.label || snapshot.role;
       meter.name.textContent = (snapshot.model || 'waiting').split('/').pop();
-      meter.targets = { cache_read: totals.cache_read, cache_write: totals.cache_write,
-        fresh_input: totals.fresh_input, output: totals.output };
+      meter.targets = { cache_read: main.cache_read, cache_write: main.cache_write,
+        fresh_input: main.fresh_input, output: main.output };
       meter.cost = totals.cost;
       const side = snapshot.side_calls;
-      const sideField = meter.amounts.side.parentElement;
-      sideField.hidden = !side?.count;
-      if (side?.count) meter.amounts.side.textContent = `${side.count} · $${side.cost.toFixed(2)}`;
+      meter.amounts.main.textContent = dollars(main.cost);
+      meter.amounts.side.textContent = dollars(side?.cost || 0);
       meter.root.classList.add('has-data');
       meter.root.classList.toggle('waiting', !totals.total);
       if (!frameRequest) frameRequest = requestAnimationFrame(paintMeters);
@@ -870,8 +875,10 @@
       const native = meterSnapshots.left?.totals;
       const penny = meterSnapshots.right?.totals;
       if (!native || !penny) return;
+      const nativeMain = meterSnapshots.left.main || native;
+      const pennyMain = meterSnapshots.right.main || penny;
       const cost = native.cost ? (native.cost - penny.cost) / native.cost * 100 : 0;
-      const tokens = native.total ? (native.total - penny.total) / native.total * 100 : 0;
+      const tokens = nativeMain.total ? (nativeMain.total - pennyMain.total) / nativeMain.total * 100 : 0;
       $('delta').textContent =
         `${cost > 0 ? '-' : '+'}${Math.abs(cost).toFixed(0)}% cost  ${tokens > 0 ? '-' : '+'}${Math.abs(tokens).toFixed(0)}% tok`;
     };
@@ -1159,6 +1166,7 @@
         button.disabled = true;
         button.textContent = 'Submitted to gallery';
       }
+      $('publish').hidden = true;
     };
 
     // Messages common to both servers