pennyrouter 0.3.33 → 0.3.36

package/README.md

@@ -80,16 +80,19 @@ OpenRouter key. PennyRouter-funded provider keys are never an installed-harness
 
 ## Explicit Penny Commands
 
-Penny Compare is bundled with the CLI on macOS and Linux. It is installed automatically as part
+Penny Compare is bundled with the CLI on macOS, Linux, and Windows. It is installed automatically as part
 of `npx pennyrouter install`; to install or refresh it separately, run:
 
 ```sh
 npx pennyrouter compare
 ```
 
-The installer puts `penny-compare` and `penny-session` on PATH alongside the `penny` launcher.
-Use `penny-compare` for a side-by-side run or `penny-session` for one Penny-routed session.
-The bundle requires `tmux`, Python 3.10+, and the harnesses being compared.
+On macOS/Linux, the installer puts `penny-compare` and `penny-session` on PATH alongside `penny`.
+These commands require `tmux`, Python 3.10+, and the harnesses being compared. On Windows,
+`penny-compare` starts a local browser terminal with native Claude and `penny claude` side by
+side. Its live token and cost readouts use Claude transcripts, with no tmux or Python install.
+Open the local URL printed by the command. Sync is Ctrl+Shift+S; Exit and save report is
+Ctrl+Shift+X. The Windows path currently supports Claude Code comparisons.
 
 On macOS and Linux, a normal install adds a small `penny` launcher under `~/.local/bin`.
 On Windows it installs `penny.cmd` under `%LOCALAPPDATA%\\PennyRouter\\bin` and adds that
@@ -97,6 +100,7 @@ directory to the user PATH:
 
 ```bash
 penny claude
+penny claude --stats
 penny claude desktop
 penny claude desktop gateway
 penny claude desktop native
@@ -108,6 +112,9 @@ penny codex desktop native
 penny opencode
 ```
 
+`penny claude --stats` launches Claude Code with Penny Compare's live single-session token and
+cost readout. Other arguments still pass through, so `penny claude --stats --resume` works.
+
 Arguments are passed through to the native harness, so commands such as `penny claude --resume`,
 `penny codex resume --last`, and `penny opencode --continue` work normally. By default, bare
 `claude`, `codex`, and `opencode` remain

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pennyrouter",
-  "version": "0.3.33",
+  "version": "0.3.36",
   "description": "Install and manage PennyRouter local coding-agent integrations.",
   "homepage": "https://pennyrouter.com",
   "bugs": {
@@ -27,5 +27,11 @@
     "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"
   },
+  "dependencies": {
+    "@xterm/addon-fit": "^0.10.0",
+    "@xterm/xterm": "^5.5.0",
+    "node-pty": "^1.0.0",
+    "ws": "^8.18.0"
+  },
   "license": "MIT"
 }

package/src/cli.js

@@ -135,10 +135,12 @@ export async function main(argv = process.argv.slice(2)) {
     const result = await installPennyCompare();
     if (!result.installed) {
       if (result.supported) throw new Error("Penny Compare is not included in this CLI package.");
-      throw new Error("Penny Compare requires macOS or Linux with tmux and Python 3.10+.");
+      throw new Error("Penny Compare requires macOS, Linux, or Windows.");
     }
     console.log(`Penny Compare installed at ${result.path}`);
-    console.log("Run `penny-compare` or `penny-session` to use it.");
+    console.log(process.platform === "win32"
+      ? "Run `penny-compare`, then open the local URL it prints."
+      : "Run `penny-compare` or `penny-session` to use it.");
     return;
   }
 

package/src/launch.js

@@ -276,7 +276,7 @@ async function copyRuntime() {
 
 /** Install the bundled, repository-independent Penny Compare tools. */
 export async function installPennyCompare() {
-  if (!(process.platform === "darwin" || process.platform === "linux")) {
+  if (!(process.platform === "darwin" || process.platform === "linux" || process.platform === "win32")) {
     return { supported: false, installed: false, path: pennyCompareDir() };
   }
   const source = join(packageRoot(), "standalone");
@@ -298,6 +298,24 @@ export async function installPennyCompare() {
   }
   await mkdir(join(destination, "reports"), { recursive: true, mode: 0o700 });
   await mkdir(pennyBinDir(), { recursive: true, mode: 0o755 });
+  if (process.platform === "win32") {
+    const modules = join(destination, "web-demo", "node_modules");
+    for (const name of ["@xterm/addon-fit", "@xterm/xterm", "node-pty", "ws"]) {
+      const target = join(modules, name);
+      await mkdir(dirname(target), { recursive: true });
+      await cp(join(packageRoot(), "node_modules", name), target, { recursive: true });
+    }
+    const link = join(pennyBinDir(), "penny-compare.cmd");
+    const marker = "@REM PennyRouter-managed compare launcher";
+    let previous = "";
+    try { previous = await readFile(link, "utf8"); } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+    if (!previous || previous.startsWith(marker)) {
+      await writeFile(link, `${marker}\r\n@echo off\r\nnode "${join(destination, "web-demo", "server.mjs")}" --compare %*\r\n`);
+    }
+    return { supported: true, installed: true, path: destination };
+  }
   for (const entry of ["penny-compare", "penny-session", "penny-compare-viewer"]) {
     const link = join(pennyBinDir(), entry);
     const target = join(destination, entry);
@@ -1240,6 +1258,25 @@ export function extractProfileArgs(args) {
   return { profile, args: rest };
 }
 
+/**
+ * Remove the launcher-only stats flag while preserving every native harness argument.
+ * A bare `--` ends Penny's option parsing, so a later `--stats` still reaches the harness.
+ */
+export function extractStatsArgs(args) {
+  const rest = [];
+  let stats = false;
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--") {
+      rest.push(...args.slice(i));
+      break;
+    }
+    if (arg === "--stats") stats = true;
+    else rest.push(arg);
+  }
+  return { stats, args: rest };
+}
+
 function assertNoConflictingArgs(harness, args) {
   if (harness === "claude" && args.some((arg) => arg === "--settings" || arg.startsWith("--settings="))) {
     throw new Error("penny claude manages --settings; remove that flag or run native claude.");
@@ -1416,23 +1453,63 @@ async function waitForChild(child) {
   });
 }
 
+/** Launch Penny Claude inside Penny Compare's single-session token readout. */
+export async function runPennyClaudeStats(args, profile) {
+  if (!(process.platform === "darwin" || process.platform === "linux")) {
+    throw new Error("penny claude --stats is supported on macOS and Linux.");
+  }
+  const panePath = join(pennyCompareDir(), "pane.py");
+  try {
+    await stat(panePath);
+  } catch {
+    throw new Error(
+      "Penny's stats display is not installed. Run `npx pennyrouter compare` and try again.",
+    );
+  }
+  const child = spawn("python3", [
+    panePath,
+    "penny-claude",
+    "--side",
+    "single",
+    "--cwd",
+    process.cwd(),
+    "--harness-args-json",
+    JSON.stringify(["--penny-profile", profile, ...args]),
+  ], {
+    cwd: process.cwd(),
+    env: process.env,
+    stdio: "inherit",
+  });
+  const result = await waitForChild(child);
+  if (result.signal) return 128 + (osConstants.signals[result.signal] || 0);
+  return result.code ?? 1;
+}
+
 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> [--penny-profile <name>] [native arguments...]");
     console.log("       --private / --cloud select the like-named profile.");
+    console.log("       penny claude --stats adds the live single-session token readout.");
     return 0;
   }
   if (!["claude", "codex", "opencode"].includes(harness)) {
     throw new Error(`Unknown harness "${harness}". Try penny claude, penny codex, or penny opencode.`);
   }
-  const selection = extractProfileArgs(argv.slice(1));
+  const statsSelection = extractStatsArgs(argv.slice(1));
+  if (statsSelection.stats && harness !== "claude") {
+    throw new Error("--stats is currently supported only by penny claude.");
+  }
+  const selection = extractProfileArgs(statsSelection.args);
   argv = [harness, ...selection.args];
   const config = await loadPennyConfig({
     profile: selection.profile,
     requireExisting: Boolean(selection.profile),
   });
   if (harness === "claude" && argv[1]?.toLowerCase() === "desktop") {
+    if (statsSelection.stats) {
+      throw new Error("--stats applies to Claude Code sessions, not Claude Desktop.");
+    }
     const option = argv[2]?.toLowerCase();
     if (option === "--restore" || option === "restore") {
       if (argv.length > 3) {
@@ -1469,6 +1546,9 @@ export async function runPenny(argv = process.argv.slice(2)) {
     }
     return runClaudeDesktop(config, { logs, mode });
   }
+  if (statsSelection.stats) {
+    return runPennyClaudeStats(argv.slice(1), config.profile);
+  }
   if (harness === "codex" && argv[1]?.toLowerCase() === "desktop") {
     const option = argv[2]?.toLowerCase();
     const mode = option === "native" || option === "--native" ? "native" : "gateway";

package/standalone/pane.py

@@ -51,7 +51,7 @@ NATIVE_PROXY_TOKEN_ENV = "PENNY_COMPARE_NATIVE_AUTH_TOKEN"
 class Readout:
     """Paints the fixed block at the top of the pane."""
 
-    def __init__(self, harness, title, delta_path=None, provider=None, label=None,
+    def __init__(self, harness, title, delta_path=None, label=None,
                  session_id=None, side=None, variant=None, pricing_profile="standard"):
         self.harness = harness
         # The pane's fixed role ("NATIVE"/"PENNY"). It keys the files the two panes use to
@@ -60,8 +60,6 @@ class Readout:
         # What the readout actually shows, which the user may rename.
         self.label = label or title
         self.delta_path = delta_path
-        # For Codex, whether this pane's session should be the PennyRouter-routed one.
-        self.provider = provider
         # Claude accepts a caller-supplied session id, so its transcript can be selected exactly
         # instead of inferred from timing, model names, or Penny's global title handoff files.
         self.session_id = session_id
@@ -142,13 +140,14 @@ class Readout:
     def resolve(self):
         """Pin this pane to the transcript its own harness created.
 
-        Both panes run in the same working directory, so the newest session there is ambiguous
-        between them, and resolving by timing alone can label the two backwards.
+        Claude is launched with an explicit session id, making its transcript path deterministic.
+        Codex and OpenCode are selected from files created after this pane launched, narrowed by
+        cwd, with pane claims preventing two local panes from adopting the same transcript.
 
-        Claude is launched with an explicit session id, making both its native and Penny
-        transcript paths deterministic. Codex has no equivalent launch flag, but records the
-        provider in its session header, so each Codex pane takes the session matching how it was
-        started.
+        Do not filter Codex by provider here. Subscription-backed Penny sessions deliberately
+        record ``model_provider = openai``, and a hosted gateway cannot create a claim file on
+        this machine. That filter rejects the correct local JSONL for both penny-session and the
+        normal compare layout, where cwd/time/claiming already identify it.
         """
         if self.path and os.path.exists(self.path):
             return self.path
@@ -163,8 +162,7 @@ class Readout:
         # session, so require one created afterwards rather than adopting the newest on disk.
         taken = self._peers() | self._preexisting
         candidate = newest_session(self.harness, os.getcwd(),
-                                   since=self.started, exclude=taken,
-                                   provider=self.provider)
+                                   since=self.started, exclude=taken)
         if candidate and not self._claim(candidate):
             return None
         self.path = candidate
@@ -346,6 +344,8 @@ def main():
                         help="start both panes on one model so the comparison is like for like")
     parser.add_argument("--label", default=None,
                         help="name shown on this pane's readout (default: NATIVE or PENNY)")
+    parser.add_argument("--cwd", default=None,
+                        help="working directory selected by the compare launcher")
     parser.add_argument("--side", choices=("left", "right", "single"),
                         help="stable pane position used by the final report")
     parser.add_argument("--pricing-profile", choices=("standard", "govcloud"),
@@ -353,8 +353,26 @@ def main():
     parser.add_argument("--native-proxy", action="store_true",
                         help=f"route the NATIVE pane through {NATIVE_PROXY_URL_ENV} / "
                              f"{NATIVE_PROXY_TOKEN_ENV} instead of going direct")
+    parser.add_argument("--harness-args-json", default="[]",
+                        help=argparse.SUPPRESS)
     args = parser.parse_args()
 
+    try:
+        harness_args = json.loads(args.harness_args_json)
+        if not isinstance(harness_args, list) or not all(
+                isinstance(value, str) for value in harness_args):
+            raise ValueError("expected a JSON array of strings")
+    except (json.JSONDecodeError, ValueError) as error:
+        sys.stderr.write(f"penny-compare: invalid harness arguments: {error}\n")
+        return 2
+
+    if args.cwd:
+        try:
+            os.chdir(os.path.expanduser(args.cwd))
+        except OSError as error:
+            sys.stderr.write(f"penny-compare: cannot enter {args.cwd}: {error}\n")
+            return 1
+
     harness, command, title = VARIANTS[args.variant]
     session_id = None
     if harness == "claude-code":
@@ -364,20 +382,14 @@ def main():
         # Passed to the harness rather than set in the environment, so Penny's own model
         # configuration is not overridden on the penny side.
         command = command + ["--model", args.model]
+    command = command + harness_args
 
     rows = shutil.get_terminal_size().lines
     # Reserve the top rows for the readout and confine scrolling to what is left.
     sys.stdout.write(f"\033[2J\033[{hud.ROWS + 1};{rows}r\033[{hud.ROWS + 1};1H")
     sys.stdout.flush()
 
-    # Codex and OpenCode have no caller-assigned session id, so they identify their transcript by the provider
-    # recorded in the session header instead.
-    is_penny = command[0] == "penny"
     readout = Readout(harness, title, args.delta_file,
-                      # OpenCode owns provider/model selection inside its own TUI. The
-                      # penny-opencode spelling is only a launch convenience, not a reliable
-                      # provider identity like Codex's session header is.
-                      provider=is_penny if harness == "codex" else None,
                       label=args.label,
                       session_id=session_id,
                       side=args.side,

package/standalone/penny-compare

@@ -236,6 +236,8 @@ workdir_left="${dir_left:-$PWD/native}"
 workdir_left="${workdir_left/#\~/$HOME}"
 workdir_right="${dir_right:-$PWD/penny}"
 workdir_right="${workdir_right/#\~/$HOME}"
+workdir_left_arg=" --cwd $(printf '%q' "$workdir_left")"
+workdir_right_arg=" --cwd $(printf '%q' "$workdir_right")"
 
 # --native-proxy only means anything on a NATIVE Claude or Codex pane;
 # a penny-* pane already owns its own proxy routing and ignores the flag either way.
@@ -265,10 +267,10 @@ wire_args="${wire:+ $wire}${wire_both:+ $wire_both}${wire_https:+ $wire_https}"
 
 tmux new-session -d -s "$session" -c "$workdir_left" -x "$(tput cols)" -y "$(tput lines)" \
   -e PENNY_COMPARE_STATE="$state" \
-  "$here/pane.py $left --side left --pricing-profile $pricing_profile${model:+ --model $model}${native_proxy_left:+ $native_proxy_left}${label_left_arg}${wire_args}"
+  "$here/pane.py $left --side left --pricing-profile $pricing_profile${workdir_left_arg}${model:+ --model $model}${native_proxy_left:+ $native_proxy_left}${label_left_arg}${wire_args}"
 tmux split-window -h -t "$session" -c "$workdir_right" \
   -e PENNY_COMPARE_STATE="$state" \
-  "$here/pane.py $right --side right --pricing-profile $pricing_profile --delta-file $delta${model:+ --model $model}${native_proxy_right:+ $native_proxy_right}${label_right_arg}${wire_args}"
+  "$here/pane.py $right --side right --pricing-profile $pricing_profile --delta-file $delta${workdir_right_arg}${model:+ --model $model}${native_proxy_right:+ $native_proxy_right}${label_right_arg}${wire_args}"
 
 # The comparison belongs to neither pane, so a small watcher derives it from both.
 tmux new-window -d -t "$session" -n delta "$here/delta.py '$state' '$delta'"

package/standalone/report.py

@@ -75,7 +75,8 @@ def centered(lines: list[str]) -> str:
 def main() -> int:
     state = Path(sys.argv[1])
     reports = Path(sys.argv[2])
-    session = sys.argv[3]
+    json_mode = len(sys.argv) > 3 and sys.argv[3] == "--json"
+    session = None if json_mode else sys.argv[3]
     try:
         started = (state / "started").stat().st_mtime
     except OSError:
@@ -111,6 +112,12 @@ def main() -> int:
     destination = reports / f"compare-{finished.strftime('%Y%m%d-%H%M%S-%f')}.json"
     destination.write_text(json.dumps(report, indent=2) + "\n")
 
+    if json_mode:
+        print(json.dumps({"path": str(destination), "savings": savings,
+                          "native": {"calls": native["call_count"], "totals": native_totals},
+                          "penny": {"calls": penny["call_count"], "totals": penny_totals}}))
+        return 0
+
     lines = [
         "PENNY COMPARISON",
         "",

package/standalone/web-demo/README.md

@@ -0,0 +1,30 @@
+# Live terminal preview
+
+From this directory:
+
+```sh
+npm install
+npm start
+```
+
+Open `http://127.0.0.1:8789`. The page starts two real shells in the current directory. Type `claude` in either pane to run Claude Code. With sync on, the same keys go to both panes. Click a pane to focus it; use **Sync** or Ctrl+Shift+S to toggle broadcast input. **Exit** or Ctrl+Shift+X ends both sessions.
+
+To launch Claude Code in both panes immediately:
+
+```sh
+npm start -- --claude
+```
+
+To run the current Penny Compare measurement code in the panes:
+
+```sh
+npm start -- --compare
+```
+
+This starts native Claude on the left and `penny claude` on the right. On macOS/Linux, it uses the existing Python session reader, cost model, HUD, and delta calculation. On Windows, it reads Claude transcripts and prices calls in Node, with no Python or tmux requirement. Exit saves a JSON report under `apps/compare/reports` and prints the summary in the left pane. Both platforms need Claude Code and the `penny` command on `PATH`.
+
+The Windows path currently supports Claude Code comparisons. Codex and OpenCode transcript readers are still in the Python path.
+
+To exercise the Windows measurement path on macOS/Linux, use `npm start -- --compare-node`.
+
+The demo requires Claude Code on `PATH` for that option. Closing or reloading the page ends both sessions. The local server listens only on `127.0.0.1`; it does not start a PennyRouter gateway.

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

@@ -0,0 +1,174 @@
+import { mkdir, open, readdir, stat, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+// Mirrors the standard Claude rates in ../pricing.py (USD per token).
+const rates = {
+  'claude-opus-5': [5e-6, .5e-6, 6.25e-6, 10e-6, 25e-6],
+  'claude-sonnet-5': [3e-6, .3e-6, 3.75e-6, 6e-6, 15e-6],
+  'claude-haiku-4-5': [1e-6, .1e-6, 1.25e-6, 2e-6, 5e-6],
+};
+
+function rateFor(model) {
+  const normalized = String(model || '').replace(/^.*\//, '').replace('[1m]', '');
+  const key = Object.keys(rates).find((name) => normalized.startsWith(name));
+  return rates[key] || rates['claude-sonnet-5'];
+}
+
+function emptyTotals() {
+  return { cache_read: 0, cache_write: 0, write_5m: 0, write_1h: 0,
+    fresh_input: 0, output: 0, reasoning_output: 0, total: 0, cost: 0 };
+}
+
+export class ClaudeMeter {
+  constructor({ sessionId, cwd, side, role }) {
+    this.sessionId = sessionId;
+    this.cwd = cwd;
+    this.side = side;
+    this.role = role;
+    this.root = join(homedir(), '.claude', 'projects');
+    this.files = new Map();
+    this.ids = new Set();
+    this.calls = [];
+    this.totals = emptyTotals();
+    this.model = '';
+    this.transcriptPath = null;
+    this.started = Date.now() / 1000;
+  }
+
+  async findTranscript() {
+    if (this.transcriptPath) return this.transcriptPath;
+    let projects;
+    try { projects = await readdir(this.root, { withFileTypes: true }); } catch { return null; }
+    for (const project of projects) {
+      if (!project.isDirectory()) continue;
+      const candidate = join(this.root, project.name, `${this.sessionId}.jsonl`);
+      try { await stat(candidate); this.transcriptPath = candidate; return candidate; } catch { /* next */ }
+    }
+    // Claude can occasionally place a session under a different transcript filename.
+    // Its first JSONL record still carries the session ID.
+    for (const project of projects) {
+      if (!project.isDirectory()) continue;
+      let entries;
+      try { entries = await readdir(join(this.root, project.name)); } catch { continue; }
+      for (const entry of entries) {
+        if (!entry.endsWith('.jsonl')) continue;
+        const path = join(this.root, project.name, entry);
+        let handle;
+        try {
+          handle = await open(path, 'r');
+          const buffer = Buffer.alloc(4096);
+          const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+          const first = buffer.subarray(0, bytesRead).toString('utf8').split('\n', 1)[0];
+          if (JSON.parse(first).sessionId === this.sessionId) {
+            this.transcriptPath = path;
+            return path;
+          }
+        } catch { /* next */ } finally { await handle?.close(); }
+      }
+    }
+    return null;
+  }
+
+  async poll() {
+    const transcript = await this.findTranscript();
+    if (!transcript) return this.snapshot();
+    const paths = [transcript];
+    const collect = async (dir) => {
+      let children;
+      try { children = await readdir(dir, { withFileTypes: true }); } catch { return; }
+      for (const child of children) {
+        const path = join(dir, child.name);
+        if (child.isDirectory()) await collect(path);
+        else if (child.name.endsWith('.jsonl')) paths.push(path);
+      }
+    };
+    await collect(join(transcript.slice(0, -6), 'subagents'));
+    for (const path of paths) await this.readAppended(path);
+    return this.snapshot();
+  }
+
+  async readAppended(path) {
+    let size;
+    try { ({ size } = await stat(path)); } catch { return; }
+    let offset = this.files.get(path) || 0;
+    if (size < offset) offset = 0;
+    if (size === offset) return;
+    const handle = await open(path, 'r');
+    try {
+      const buffer = Buffer.alloc(size - offset);
+      const { bytesRead } = await handle.read(buffer, 0, buffer.length, offset);
+      const text = buffer.subarray(0, bytesRead).toString('utf8');
+      const end = text.lastIndexOf('\n');
+      if (end < 0) return;
+      this.files.set(path, offset + Buffer.byteLength(text.slice(0, end + 1)));
+      for (const line of text.slice(0, end).split('\n')) {
+        let obj;
+        try { obj = JSON.parse(line); } catch { continue; }
+        const message = obj.message;
+        const usage = message?.usage;
+        if (!usage || typeof usage !== 'object') continue;
+        if (message.id && this.ids.has(message.id)) continue;
+        if (message.id) this.ids.add(message.id);
+        const read = Number(usage.cache_read_input_tokens) || 0;
+        const write = Number(usage.cache_creation_input_tokens) || 0;
+        let write5 = Number(usage.cache_creation?.ephemeral_5m_input_tokens) || 0;
+        const write1 = Number(usage.cache_creation?.ephemeral_1h_input_tokens) || 0;
+        if (!write5 && !write1) write5 = write;
+        const input = Number(usage.input_tokens) || 0;
+        const output = Number(usage.output_tokens) || 0;
+        const model = message.model || this.model;
+        const prices = rateFor(model);
+        const cost = input * prices[0] + read * prices[1] + write5 * prices[2] +
+          write1 * prices[3] + output * prices[4];
+        const call = { timestamp: obj.timestamp || null, recorded_at: Date.now() / 1000,
+          model, cache_read: read, cache_write: write, write_5m: write5, write_1h: write1,
+          fresh_input: input, output, reasoning_output: 0,
+          total: read + write + input + output, cost,
+          context_tokens: read + write + input,
+          pricing_profile: 'standard',
+          rates_per_million: Object.fromEntries(
+            ['input', 'cache_read', 'cache_write_5m', 'cache_write_1h', 'output']
+              .map((name, index) => [name, prices[index] * 1_000_000])),
+        };
+        this.calls.push(call);
+        this.model = model;
+        this.totals.cache_read += read;
+        this.totals.cache_write += write;
+        this.totals.write_5m += write5;
+        this.totals.write_1h += write1;
+        this.totals.fresh_input += input;
+        this.totals.output += output;
+        this.totals.total += call.total;
+        this.totals.cost += cost;
+      }
+    } finally { await handle.close(); }
+  }
+
+  snapshot() {
+    return { side: this.side, role: this.role, label: this.role, variant: this.side === 'left' ? 'claude' : 'penny-claude',
+      harness: 'claude-code', cwd: this.cwd, pricing_profile: 'standard', session_id: this.sessionId,
+      transcript_path: this.transcriptPath, model: this.model, call_count: this.calls.length,
+      totals: { ...this.totals } };
+  }
+}
+
+export async function saveReport(left, right, reportsDir) {
+  const native = left.snapshot();
+  const penny = right.snapshot();
+  const savings = {
+    cost: native.totals.cost - penny.totals.cost,
+    tokens: native.totals.total - penny.totals.total,
+    cost_percent: native.totals.cost ? (native.totals.cost - penny.totals.cost) / native.totals.cost * 100 : 0,
+    token_percent: native.totals.total ? (native.totals.total - penny.totals.total) / native.totals.total * 100 : 0,
+  };
+  const report = { created_at: new Date().toISOString(),
+    measured_from_epoch: Math.min(left.started, right.started), pricing_profile: 'standard',
+    left: { ...native, calls: left.calls }, right: { ...penny, calls: right.calls },
+    savings_native_minus_penny: savings };
+  await mkdir(reportsDir, { recursive: true });
+  const path = join(reportsDir, `compare-${new Date().toISOString().replace(/[:.]/g, '-')}.json`);
+  await writeFile(path, `${JSON.stringify(report, null, 2)}\n`);
+  return { path, savings, native: { calls: native.call_count, totals: native.totals },
+    penny: { calls: penny.call_count, totals: penny.totals } };
+}

package/standalone/web-demo/fix-pty-permissions.mjs

@@ -0,0 +1,17 @@
+import { chmod, stat } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+
+// node-pty 1.1.0's macOS prebuild is packaged with a non-executable helper.
+// Its native binding can load, but every PTY launch then fails at posix_spawnp.
+if (process.platform === 'darwin') {
+  const require = createRequire(import.meta.url);
+  const packageDir = dirname(require.resolve('node-pty/package.json'));
+  const helper = join(packageDir, 'prebuilds', `darwin-${process.arch}`, 'spawn-helper');
+  try {
+    const { mode } = await stat(helper);
+    await chmod(helper, mode | 0o111);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error; // Source builds use build/Release instead.
+  }
+}

package/standalone/web-demo/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "penny-compare-terminal-demo",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "node server.mjs",
+    "postinstall": "node fix-pty-permissions.mjs"
+  },
+  "dependencies": {
+    "@xterm/addon-fit": "^0.10.0",
+    "@xterm/xterm": "^5.5.0",
+    "node-pty": "^1.0.0",
+    "ws": "^8.18.0"
+  }
+}

package/standalone/web-demo/server.mjs

@@ -0,0 +1,227 @@
+import { createServer } from 'node:http';
+import { randomUUID } from 'node:crypto';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { spawn, execFile } from 'node:child_process';
+import { join, dirname } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+import { WebSocketServer } from 'ws';
+import pty from 'node-pty';
+import { ClaudeMeter, saveReport } from './claude-meter.mjs';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const compareDir = dirname(here);
+const execFileAsync = promisify(execFile);
+const args = process.argv.slice(2);
+const claude = args.includes('--claude');
+const nodeMeter = args.includes('--compare-node') ||
+  (args.includes('--compare') && process.platform === 'win32');
+const compare = args.includes('--compare') || nodeMeter;
+const pythonCompare = compare && !nodeMeter && process.platform !== 'win32';
+const portArg = args.find((arg) => /^--port=\d+$/.test(arg));
+const port = Number(portArg?.slice(7) ?? 8789);
+if (args.some((arg) => !['--claude', '--compare', '--compare-node', portArg].includes(arg)) ||
+    (claude && compare) || port < 1 || port > 65535) {
+  console.error('Usage: npm start -- [--claude | --compare | --compare-node] [--port=8789]');
+  process.exit(1);
+}
+
+const files = new Map([
+  ['/', ['terminal-preview.html', 'text/html; charset=utf-8']],
+  ['/xterm.css', ['node_modules/@xterm/xterm/css/xterm.css', 'text/css; charset=utf-8']],
+  ['/xterm.js', ['node_modules/@xterm/xterm/lib/xterm.js', 'text/javascript; charset=utf-8']],
+  ['/addon-fit.js', ['node_modules/@xterm/addon-fit/lib/addon-fit.js', 'text/javascript; charset=utf-8']],
+]);
+
+const server = createServer(async (request, response) => {
+  const file = files.get(request.url);
+  if (!file) { response.writeHead(404).end(); return; }
+  try {
+    const body = await readFile(join(here, file[0]));
+    response.writeHead(200, { 'Content-Type': file[1], 'Cache-Control': 'no-store' }).end(body);
+  } catch (error) {
+    console.error(error);
+    response.writeHead(500).end('Could not load demo asset');
+  }
+});
+
+const wss = new WebSocketServer({ noServer: true, maxPayload: 64 * 1024 });
+server.on('upgrade', (request, socket, head) => {
+  const allowedOrigins = new Set([`http://127.0.0.1:${port}`, `http://localhost:${port}`]);
+  if (request.url !== '/terminal' || !allowedOrigins.has(request.headers.origin)) {
+    socket.write('HTTP/1.1 403 Forbidden\r\n\r\n');
+    socket.destroy();
+    return;
+  }
+  wss.handleUpgrade(request, socket, head, (ws) => wss.emit('connection', ws));
+});
+
+function launchCommand(side, state, sessionId) {
+  if (pythonCompare) {
+    const variant = side === 'left' ? 'claude' : 'penny-claude';
+    const args = [join(compareDir, 'pane.py'), variant, '--side', side,
+      '--cwd', process.cwd(), '--pricing-profile', 'standard'];
+    if (side === 'right') args.push('--delta-file', join(state, 'delta.txt'));
+    return ['python3', args];
+  }
+  if (nodeMeter) {
+    if (process.platform === 'win32') {
+      const shell = process.env.ComSpec || 'cmd.exe';
+      return [shell, ['/d', '/s', '/c', side === 'left'
+        ? `claude --session-id ${sessionId}` : `penny claude --session-id ${sessionId}`]];
+    }
+    const shell = process.env.SHELL || '/bin/sh';
+    return [shell, ['-lc', `exec ${side === 'left' ? 'claude' : 'penny claude'} --session-id ${sessionId}`]];
+  }
+  if (process.platform === 'win32') {
+    const shell = process.env.ComSpec || 'cmd.exe';
+    return claude ? [shell, ['/d', '/s', '/c', 'claude']] : [shell, []];
+  }
+  const shell = process.env.SHELL || '/bin/sh';
+  return claude ? [shell, ['-lc', 'exec claude']] : [shell, []];
+}
+
+wss.on('connection', (ws) => {
+  const sessions = new Map();
+  const meters = new Map();
+  const snapshots = new Map();
+  let state;
+  let delta;
+  let meterTimer;
+  let polling = false;
+  let closed = false;
+  let exiting = false;
+  const ready = pythonCompare ? mkdtemp(join(tmpdir(), 'penny-compare-web-')).then(async (dir) => {
+    state = dir;
+    await writeFile(join(dir, 'started'), '');
+    await writeFile(join(dir, 'delta.txt'), '');
+  }) : Promise.resolve();
+  const send = (message) => {
+    if (ws.readyState === ws.OPEN) ws.send(JSON.stringify(message));
+  };
+  const pollMeters = async () => {
+    if (polling || closed) return;
+    polling = true;
+    try {
+      for (const meter of meters.values()) {
+        const snapshot = await meter.poll();
+        snapshots.set(meter.side, snapshot);
+        send({ type: 'meter', data: snapshot });
+      }
+      const left = snapshots.get('left');
+      const right = snapshots.get('right');
+      if (left && right) {
+        const base = left.totals;
+        const current = right.totals;
+        send({ type: 'delta', cost: base.cost ? (current.cost - base.cost) / base.cost * 100 : 0,
+          tokens: base.total ? (current.total - base.total) / base.total * 100 : 0 });
+      }
+    } catch (error) {
+      send({ type: 'error', side: 'left', error: `Meter: ${error.message}` });
+    } finally { polling = false; }
+  };
+  const dispose = () => {
+    if (closed) return;
+    closed = true;
+    for (const session of sessions.values()) {
+      try { session.kill(); } catch { /* already exited */ }
+    }
+    sessions.clear();
+    if (meterTimer) clearInterval(meterTimer);
+    if (delta) delta.kill();
+    if (state) void rm(state, { recursive: true, force: true });
+  };
+  const handle = async (raw) => {
+    let message;
+    try { message = JSON.parse(raw); } catch { return; }
+    if (message.type === 'exit') {
+      if (exiting) return;
+      exiting = true;
+      if (pythonCompare && state) {
+        try {
+          const { stdout } = await execFileAsync('python3', [join(compareDir, 'report.py'),
+            state, join(compareDir, 'reports'), '--json']);
+          send({ type: 'report', ...JSON.parse(stdout) });
+        } catch (error) {
+          send({ type: 'report-error', error: error.message });
+        }
+      } else if (nodeMeter) {
+        try {
+          await pollMeters();
+          const left = meters.get('left');
+          const right = meters.get('right');
+          if (!left || !right) throw new Error('Both compare panes must start before a report can be saved.');
+          send({ type: 'report', ...await saveReport(left, right, join(compareDir, 'reports')) });
+        } catch (error) {
+          send({ type: 'report-error', error: error.message });
+        }
+      }
+      dispose();
+      ws.close();
+      return;
+    }
+    if (!['left', 'right'].includes(message.side)) return;
+    const size = (value, max) => Number.isInteger(value) && value >= 2 && value <= max;
+    if (message.type === 'start' && !sessions.has(message.side) &&
+        size(message.cols, 500) && size(message.rows, 200)) {
+      try {
+        await ready;
+        if (closed) return;
+        if (pythonCompare && !delta) {
+          delta = spawn('python3', [join(compareDir, 'delta.py'), state, join(state, 'delta.txt')],
+            { stdio: 'ignore' });
+          delta.on('error', (error) => send({ type: 'error', side: 'right', error: error.message }));
+        }
+        const sessionId = nodeMeter ? randomUUID() : undefined;
+        const [command, commandArgs] = launchCommand(message.side, state, sessionId);
+        const env = { ...process.env, TERM: 'xterm-256color',
+          ...(pythonCompare ? { PENNY_COMPARE_STATE: state } : {}) };
+        if (compare && message.side === 'left') {
+          for (const key of ['ANTHROPIC_BASE_URL', 'ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_API_KEY']) {
+            delete env[key];
+          }
+        }
+        const session = pty.spawn(command, commandArgs, {
+          name: 'xterm-256color', cols: message.cols, rows: message.rows,
+          cwd: process.cwd(), env,
+        });
+        sessions.set(message.side, session);
+        if (nodeMeter) {
+          meters.set(message.side, new ClaudeMeter({ sessionId, cwd: process.cwd(),
+            side: message.side, role: message.side === 'left' ? 'NATIVE' : 'PENNY' }));
+          send({ type: 'meter-mode' });
+          if (!meterTimer) meterTimer = setInterval(() => { void pollMeters(); }, 1000);
+        }
+        session.onData((data) => send({ type: 'output', side: message.side, data }));
+        session.onExit(({ exitCode }) => {
+          sessions.delete(message.side);
+          send({ type: 'exit', side: message.side, code: exitCode });
+        });
+      } catch (error) {
+        send({ type: 'error', side: message.side, error: error.message });
+      }
+    } else if (message.type === 'input' && typeof message.data === 'string' &&
+               message.data.length <= 16384) {
+      sessions.get(message.side)?.write(message.data);
+    } else if (message.type === 'resize' && size(message.cols, 500) && size(message.rows, 200)) {
+      sessions.get(message.side)?.resize(message.cols, message.rows);
+    }
+  };
+  ws.on('message', (raw) => { void handle(raw); });
+  ws.on('close', dispose);
+  ws.on('error', dispose);
+});
+
+server.listen(port, '127.0.0.1', () => {
+  const url = `http://127.0.0.1:${port}`;
+  console.log(`Penny Compare live terminal demo: ${url}`);
+  console.log(compare ? 'Native Claude and Penny Claude panes with transcript HUDs.' :
+    claude ? 'Each pane starts Claude Code.' : 'Each pane starts a shell. Type claude to run Claude Code.');
+  if (process.platform === 'win32') {
+    execFile(process.env.ComSpec || 'cmd.exe', ['/d', '/s', '/c', `start "" "${url}"`],
+      { windowsHide: true }, (error) => {
+        if (error) console.error(`Could not open the browser automatically: ${error.message}`);
+      });
+  }
+});

package/standalone/web-demo/terminal-preview.html

@@ -0,0 +1,160 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Penny Compare — terminal preview</title>
+  <link rel="stylesheet" href="/xterm.css">
+  <style>
+    :root { color-scheme: dark; font: 14px/1.2 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+    * { box-sizing: border-box; }
+    html, body { height: 100%; margin: 0; background: #111116; color: #d7d7dd; }
+    body { display: flex; flex-direction: column; overflow: hidden; }
+    .status { height: 25px; flex: none; display: flex; align-items: center; justify-content: center; gap: 1.2rem; background: #262629; color: #9ded83; font-size: 12px; white-space: nowrap; }
+    .status button { appearance: none; border: 0; background: none; color: inherit; font: inherit; cursor: pointer; padding: 0; }
+    .status button:hover { color: #fff; }
+    .panes { display: grid; grid-template-columns: minmax(0, 1fr) minmax(0, 1fr); flex: 1; min-height: 0; }
+    .pane { min-width: 0; min-height: 0; overflow: hidden; background: #16161b; }
+    .pane + .pane { border-left: 1px solid #4d4d52; }
+    .pane.focused { box-shadow: inset 0 0 0 1px #6a6a72; }
+    .terminal { width: 100%; height: 100%; padding: 4px 7px; }
+    .pane { position: relative; }
+    .meter { display: none; position: absolute; top: 4px; right: 13px; z-index: 2;
+      width: 190px; white-space: pre; color: #9ded83; line-height: 1.15; font-size: 13px;
+      pointer-events: none; }
+    .pane.metered .meter { display: block; }
+    .delta { display: none; position: absolute; top: 4px; right: 220px; z-index: 2;
+      color: #9ded83; white-space: nowrap; pointer-events: none; }
+    .pane.metered .delta { display: block; }
+    .xterm { height: 100%; }
+    .xterm-viewport { scrollbar-width: thin; }
+    @media (max-width: 720px) { .status { justify-content: flex-start; overflow-x: auto; padding: 0 8px; } }
+  </style>
+</head>
+<body>
+  <div class="status">
+    <button id="sync">SYNC ON  ^⇧S</button>
+    <button id="exit">EXIT  ^⇧X</button>
+    <span id="connection" style="color:#77777e">connecting…</span>
+  </div>
+  <main class="panes">
+    <section class="pane focused"><div class="meter" id="left-meter"></div><div class="terminal" id="native"></div></section>
+    <section class="pane"><div class="delta" id="delta"></div><div class="meter" id="right-meter"></div><div class="terminal" id="penny"></div></section>
+  </main>
+  <script src="/xterm.js"></script>
+  <script src="/addon-fit.js"></script>
+  <script>
+    const options = {
+      fontFamily: 'SFMono-Regular, Menlo, Consolas, monospace', fontSize: 13,
+      lineHeight: 1.15, cursorBlink: true, cursorStyle: 'block',
+      allowTransparency: false, scrollback: 1000,
+      theme: { background: '#16161b', foreground: '#d7d7dd', cursor: '#d7d7dd',
+        selectionBackground: '#4b5369', black: '#24242a', red: '#e88b8b',
+        green: '#9ded83', yellow: '#e6c583', blue: '#8eaeeb', magenta: '#c8a7e8',
+        cyan: '#8ed1cf', white: '#d7d7dd' }
+    };
+    const native = new Terminal(options);
+    const penny = new Terminal(options);
+    const fit = { left: new FitAddon.FitAddon(), right: new FitAddon.FitAddon() };
+    native.loadAddon(fit.left);
+    penny.loadAddon(fit.right);
+    native.open(document.getElementById('native'));
+    penny.open(document.getElementById('penny'));
+    let sync = true;
+    const panes = document.querySelectorAll('.pane');
+    const send = message => { if (socket.readyState === WebSocket.OPEN) socket.send(JSON.stringify(message)); };
+    const socket = new WebSocket(`ws://${location.host}/terminal`);
+    const setFocus = index => { panes.forEach((p, i) => p.classList.toggle('focused', i === index)); (index ? penny : native).focus(); };
+    const setSync = value => {
+      sync = value;
+      document.getElementById('sync').textContent = sync ? 'SYNC ON  ^⇧S' : 'sync off  ^⇧S';
+    };
+    const exit = () => {
+      send({ type: 'exit' });
+      document.getElementById('connection').textContent = 'saving report…';
+      document.getElementById('exit').disabled = true;
+    };
+    function resize() {
+      for (const [side, terminal] of [['left', native], ['right', penny]]) {
+        fit[side].fit();
+        send({ type: 'resize', side, cols: terminal.cols, rows: terminal.rows });
+      }
+    }
+    socket.addEventListener('open', () => {
+      document.getElementById('connection').textContent = 'live PTYs';
+      resize();
+      for (const [side, terminal] of [['left', native], ['right', penny]]) {
+        send({ type: 'start', side, cols: terminal.cols, rows: terminal.rows });
+      }
+      setFocus(0);
+    });
+    socket.addEventListener('message', event => {
+      const message = JSON.parse(event.data);
+      const terminal = message.side === 'left' ? native : penny;
+      if (message.type === 'output') terminal.write(message.data);
+      if (message.type === 'exit') terminal.write(`\r\n[process exited: ${message.code}]\r\n`);
+      if (message.type === 'error') terminal.write(`\r\n[launch failed: ${message.error}]\r\n`);
+      if (message.type === 'meter-mode') {
+        panes.forEach(pane => pane.classList.add('metered'));
+        resize();
+      }
+      if (message.type === 'meter') {
+        const data = message.data;
+        const total = data.totals;
+        document.getElementById(`${data.side}-meter`).textContent =
+          `${data.role}  ${(data.model || 'waiting').split('/').pop()}\n` +
+          `read   ${total.cache_read.toLocaleString().padStart(11)}\n` +
+          `write  ${total.cache_write.toLocaleString().padStart(11)}\n` +
+          `in     ${total.fresh_input.toLocaleString().padStart(11)}\n` +
+          `out    ${total.output.toLocaleString().padStart(11)}\n` +
+          `total  ${total.total.toLocaleString().padStart(11)}\n` +
+          `cost   $${total.cost.toFixed(2).padStart(10)}`;
+      }
+      if (message.type === 'delta') {
+        document.getElementById('delta').textContent =
+          `${message.cost.toFixed(0)}% cost  ${message.tokens.toFixed(0)}% tok`;
+      }
+      if (message.type === 'report') {
+        const savings = message.savings;
+        const metric = (amount, percent, unit) =>
+          `${unit}${unit ? Math.abs(amount).toFixed(2) : Math.abs(amount).toLocaleString()}` +
+          ` ${amount >= 0 ? 'saved' : 'extra'} (${Math.abs(percent).toFixed(1)}%)`;
+        native.write(`\r\n\x1b[1;32mPENNY COMPARISON\x1b[0m\r\n` +
+          `${metric(savings.tokens, savings.token_percent, '')} tokens\r\n` +
+          `${metric(savings.cost, savings.cost_percent, '$')}\r\n` +
+          `Report: ${message.path}\r\n`);
+        document.getElementById('connection').textContent = 'report saved';
+      }
+      if (message.type === 'report-error') {
+        native.write(`\r\n[report failed: ${message.error}]\r\n`);
+        document.getElementById('connection').textContent = 'report failed';
+      }
+    });
+    socket.addEventListener('close', () => {
+      if (!document.getElementById('exit').disabled) {
+        document.getElementById('connection').textContent = 'disconnected — reload to reconnect';
+      }
+    });
+    const resizeObserver = new ResizeObserver(resize);
+    panes.forEach(pane => resizeObserver.observe(pane));
+    document.getElementById('sync').onclick = () => setSync(!sync);
+    document.getElementById('exit').onclick = exit;
+    document.addEventListener('keydown', event => {
+      if (!event.ctrlKey || !event.shiftKey || event.altKey || event.metaKey) return;
+      if (event.code === 'KeyS') { event.preventDefault(); event.stopPropagation(); setSync(!sync); }
+      if (event.code === 'KeyX') { event.preventDefault(); event.stopPropagation(); exit(); }
+    }, true);
+    panes[0].addEventListener('pointerdown', () => setFocus(0));
+    panes[1].addEventListener('pointerdown', () => setFocus(1));
+    native.onData(data => {
+      send({ type: 'input', side: 'left', data });
+      if (sync) send({ type: 'input', side: 'right', data });
+    });
+    penny.onData(data => {
+      send({ type: 'input', side: 'right', data });
+      if (sync) send({ type: 'input', side: 'left', data });
+    });
+    setFocus(0);
+  </script>
+</body>
+</html>