pennyrouter 0.3.44 → 0.3.46

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pennyrouter",
-  "version": "0.3.44",
+  "version": "0.3.46",
   "description": "Install and manage PennyRouter local coding-agent integrations.",
   "homepage": "https://pennyrouter.com",
   "bugs": {

package/src/launch.test.js

@@ -107,7 +107,7 @@ async function main() {
     assert.equal(second.changed, false);
     assert.equal(await fileMode(pennyShimPath()), 0o755);
     assert.ok(fs.existsSync(path.join(pennyRuntimeDir(), "bin", "penny.js")));
-    for (const asset of ["terminal-unicode.js", "artifacts.mjs", "artifact-preview.html", "telemetry.mjs", "gallery-submit.mjs", "compare.html",
+    for (const asset of ["terminal-unicode.js", "artifacts.mjs", "artifact-preview.html", "telemetry.mjs", "gallery-submit.mjs", "pane-options.mjs", "compare.html",
       "node_modules/@xterm/addon-unicode11/lib/addon-unicode11.js"]) {
       assert.ok(fs.existsSync(path.join(pennyCompareDir(), "web-demo", asset)), `compare installs ${asset}`);
     }

package/standalone/usage.py

@@ -214,6 +214,13 @@ class UsageReader:
                 return
             state.counted.add(mid)
 
+        # A reply the gateway answered itself carries an estimate of the whole context as fresh
+        # input, and nothing was billed for it. The gateway marks these replies with a
+        # `penny_local_` request id and a `msg_swallow_` message id.
+        if (str(obj.get("requestId") or "").startswith("penny_local_")
+                or str(mid or "").startswith("msg_swallow_")):
+            return
+
         read = int(usage.get("cache_read_input_tokens") or 0)
         write = int(usage.get("cache_creation_input_tokens") or 0)
         creation = usage.get("cache_creation") or {}

package/standalone/web-demo/README.md

@@ -23,6 +23,8 @@ npm start -- --compare
 
 This opens a setup screen with the Claude/Codex pane choices, folders, labels, shared model, and environment (provider, proxy, pricing). The default is native Claude on the left and Penny Claude on the right, using `native` and `penny` folders under the directory `npm start` was run from; missing folders are created. Each pane's meter reads Claude or Codex transcripts and prices calls in Node on every platform, with no Python or tmux requirement. Claude panes also report background model calls (such as the auto-mode reviewer) to this server over local OpenTelemetry, which the meter adds as a "side" line. Exit saves a JSON report under `apps/compare/reports` and shows the final summary. The selected harness commands must be on `PATH`.
 
+A Penny Claude pane has an **Options** section under its picker, set separately for each side. **Cache TTL** chooses 5 minutes (the default) or 1 hour for the conversation cache by setting Claude Code's `FORCE_PROMPT_CACHING_5M` or `ENABLE_PROMPT_CACHING_1H` for that pane; the shared prefix is always 1 hour. The choice is shown in the pane header and saved in the report. Options are defined in `pane-options.mjs`.
+
 Use `--harness=codex` to preselect Codex in the setup screen. The pane selectors can also mix Claude and Codex; the shared model control is available when both panes use the same harness family. `--compare-node` is accepted as an older name for `--compare`.
 
 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

@@ -61,6 +61,13 @@ async function readFirstLine(path, limit = 1024 * 1024) {
 // as a background call only once its request id has stayed out of the transcript this long.
 const sideCallGraceMs = 5000;
 
+// A reply the gateway answered itself, with no model call, reports an estimate of the whole
+// context as fresh input so Claude Code's context gauge stays honest. Nothing was billed for
+// it. The gateway marks these replies with a `penny_local_` request id (which Claude Code keeps
+// in its transcript and telemetry) and a `msg_swallow_` message id.
+const isLocalReply = (requestId, messageId) =>
+  String(requestId || '').startsWith('penny_local_') || String(messageId || '').startsWith('msg_swallow_');
+
 // Without a request id (a gateway may not relay Anthropic's), a telemetry event and its
 // transcript line still carry the same usage, so that usage identifies the call.
 const usagePrint = (model, input, read, write, output) =>
@@ -78,13 +85,14 @@ function emptyTotals() {
 }
 
 export class ClaudeMeter {
-  constructor({ sessionId, cwd, side, role, label, variant, pricingProfile = 'standard' }) {
+  constructor({ sessionId, cwd, side, role, label, variant, pricingProfile = 'standard', options = {} }) {
     this.sessionId = sessionId;
     this.cwd = cwd;
     this.side = side;
     this.role = role;
     this.label = label || role;
     this.variant = variant;
+    this.options = options;
     this.pricingProfile = pricingProfiles.includes(pricingProfile) ? pricingProfile : 'standard';
     this.root = join(homedir(), '.claude', 'projects');
     this.files = new Map();
@@ -99,6 +107,7 @@ export class ClaudeMeter {
     this.chargedPrints = new Map();
     this.telemetry = new Map();
     this.sideCalls = { count: 0, cost: 0, models: {} };
+    this.localReplyIds = new Set();
   }
 
   // api_request events from this pane's telemetry (see telemetry.mjs).
@@ -116,6 +125,11 @@ export class ClaudeMeter {
     const now = Date.now();
     for (const request of this.telemetry.values()) {
       if (request.resolved) continue;
+      if (isLocalReply(request.requestId)) {
+        request.resolved = true;
+        this.localReplyIds.add(request.requestId);
+        continue;
+      }
       const { model, cache_read: read, cache_write: write, fresh_input: input, output } = request;
       const print = usagePrint(model, input, read, write, output);
       if (request.requestId ? this.requestIds.has(request.requestId) : takePrint(this.transcriptPrints, print)) {
@@ -234,6 +248,12 @@ export class ClaudeMeter {
         const input = Number(usage.input_tokens) || 0;
         const output = Number(usage.output_tokens) || 0;
         const model = message.model || this.model;
+        if (isLocalReply(obj.requestId, message.id)) {
+          this.localReplyIds.add(obj.requestId || message.id);
+          // Without a request id the matching telemetry event is recognized by its usage.
+          if (!obj.requestId) addPrint(this.transcriptPrints, usagePrint(model, input, read, write, output));
+          continue;
+        }
         if (!obj.requestId) {
           const print = usagePrint(model, input, read, write, output);
           // Already charged from telemetry when its transcript line arrived late.
@@ -268,10 +288,10 @@ export class ClaudeMeter {
   }
 
   snapshot() {
-    return { side: this.side, role: this.role, label: this.label, variant: this.variant,
+    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 },
+      totals: { ...this.totals }, local_replies: this.localReplyIds.size,
       side_calls: { ...this.sideCalls, models: structuredClone(this.sideCalls.models) } };
   }
 }

package/standalone/web-demo/compare.html

@@ -42,6 +42,10 @@
       background: var(--pane-head); border-bottom: 1px solid var(--line); border-top: 2px solid transparent; }
     .pane.focused header { border-top-color: #5d7d55; }
     .pane header .label { color: #b8b8c3; letter-spacing: .06em; }
+    .pane header .chip { padding: 1px 8px; border: 1px solid #4d4d57; border-radius: 999px; color: var(--muted);
+      font-size: 11px; white-space: nowrap; }
+    .pane-options details { margin-top: 10px; }
+    .pane-options .option + .option { margin-top: 4px; }
     .pane.focused header .label { color: var(--text); }
     .terminal { flex: 1; min-height: 0; padding: 5px 7px; }
     .xterm { height: 100%; }
@@ -98,9 +102,7 @@
       letter-spacing: 1.8px; text-transform: uppercase; }
     .card h2 { margin: 0 0 8px; font-size: 20px; font-weight: 650; letter-spacing: -.4px; }
     .card .lede { margin: 0 0 20px; color: var(--muted); }
-    .card .notice { margin: 0 0 20px; padding: 12px 14px; border-radius: 8px; background: #1d2219;
       color: #b4b4be; font-size: 12px; }
-    .card .notice strong { color: var(--text); }
     .card label { display: block; margin: 14px 0 0; color: #b8b8c1; font-size: 12px; }
     .card input:not([type=checkbox]), .card select { display: block; width: 100%; min-width: 0; margin-top: 8px;
       padding: 10px 12px; border: 1px solid #3a3a44; border-radius: 8px; background: var(--field); color: #eee;
@@ -193,17 +195,6 @@
     .card .error { margin: 14px 0 0; color: var(--error); font-size: 13px; }
     .card .error:empty { display: none; }
     .card .footnote { margin: 16px 0 0; color: var(--muted); font-size: 12px; }
-    .progress { margin: 16px 0 0; font-size: 12px; }
-    .progress:empty { display: none; }
-    .progress p { margin: 0 0 8px; color: var(--accent); }
-    .progress ol { margin: 0; padding: 0; list-style: none; display: grid; gap: 4px; font-family: var(--mono); }
-    .progress li { display: flex; gap: 8px; color: var(--dim); }
-    .progress li::before { content: '○'; width: 1em; text-align: center; }
-    .progress li.done { color: #92929c; }
-    .progress li.done::before { content: '✓'; color: var(--accent); }
-    .progress li.current { color: var(--text); }
-    .progress li.current::before { content: '›'; color: var(--accent); }
-    .progress .elapsed { margin-left: auto; color: #92929c; font-variant-numeric: tabular-nums; }
     .metrics { display: grid; grid-template-columns: 1fr 1fr; gap: 12px; margin: 18px 0; }
     .metric { padding: 14px; border-radius: 10px; background: var(--field); }
     .metric span { display: block; margin-bottom: 6px; color: var(--muted); font-size: 12px; }
@@ -222,18 +213,18 @@
       title="Type into both panes at once (Ctrl/⌘+Shift+S)">Sync off</button>
     <button id="finish" disabled>Finish comparison</button>
     <button id="download-logs" hidden>Download logs</button>
-    <button id="add-to-gallery" disabled title="Available after you finish the comparison">Add to gallery</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>
   <main class="panes">
-    <section class="pane focused" id="left-pane"><header><strong class="label" id="left-label">NATIVE</strong>
+    <section class="pane focused" id="left-pane"><header><strong class="label" id="left-label">NATIVE</strong><span class="chip" id="left-chip" hidden></span>
       <div class="files" id="left-files"><button class="newest" id="left-newest" hidden></button>
         <button class="count" id="left-files-count" aria-expanded="false" aria-controls="left-file-list">No files</button>
         <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>
+    <section class="pane" id="right-pane"><header><strong class="label" id="right-label">PENNY</strong><span class="chip" id="right-chip" hidden></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>
@@ -241,17 +232,22 @@
   </main>
 
   <section class="overlay" id="setup" hidden>
-    <form class="card" id="hosted-setup" hidden>
-      <span class="eyebrow">Live demo</span>
-      <h2>How well does PennyRouter work?</h2>
-      <p class="lede">Two real terminals, one native and one through PennyRouter, with the actual spend side by side.</p>
-      <p class="notice"><strong>Use a temporary, dedicated API key with a small spend limit.</strong>
-        Your key is used only to run this demo, is not saved to our database, and is discarded
-        when this session ends.</p>
-      <label>Compare
-        <select id="harness"><option value="claude">Claude Code</option><option value="codex">Codex</option></select></label>
-      <label><span id="key-label">Anthropic API key</span>
-        <input type="password" id="key" autocomplete="off" spellcheck="false" required></label>
+    <form class="card wide" id="local-setup" hidden>
+      <span class="eyebrow">On this machine</span>
+      <h2>Penny Compare</h2>
+      <p class="lede">Run a native harness and a PennyRouter harness side by side and measure both.</p>
+      <div class="grid">
+        <label>Left pane <select id="left-variant"></select></label>
+        <label>Right pane <select id="right-variant"></select></label>
+        <div class="pane-options" id="left-options"></div>
+        <div class="pane-options" id="right-options"></div>
+        <label>Left directory <input id="left-cwd" autocomplete="off" spellcheck="false" required></label>
+        <label>Right directory <input id="right-cwd" autocomplete="off" spellcheck="false" required></label>
+        <label>Left label <input id="left-custom-label" placeholder="NATIVE"></label>
+        <label>Right label <input id="right-custom-label" placeholder="PENNY"></label>
+      </div>
+      <label>Model (both panes)
+        <input id="model" placeholder="Harness default" autocomplete="off" spellcheck="false"></label>
       <details id="environment">
         <summary>Environment <span class="choice" id="environment-choice"></span></summary>
         <label>Provider
@@ -276,32 +272,6 @@
             <option value="govcloud" data-short="GovCloud pricing">GovCloud</option>
           </select></label>
       </details>
-      <details>
-        <summary>Optional: second account for cleaner cache metrics</summary>
-        <label><span id="penny-key-label">Anthropic API key (second account)</span>
-          <input type="password" id="penny-key" autocomplete="off" spellcheck="false"></label>
-        <p class="hint">Both terminals otherwise share one key, so they can share prompt-cache entries and blur the cache numbers. A key from a separate account keeps the Penny side's cache isolated. Leave blank to use the key above for both.</p>
-      </details>
-      <p class="error" id="hosted-error" role="alert"></p>
-      <button class="primary" id="hosted-start" disabled>Start terminals</button>
-      <div class="progress" id="progress" role="status" aria-live="polite"></div>
-    </form>
-
-    <form class="card wide" id="local-setup" hidden>
-      <span class="eyebrow">On this machine</span>
-      <h2>Penny Compare</h2>
-      <p class="lede">Run a native harness and a PennyRouter harness side by side and measure both.</p>
-      <div class="grid">
-        <label>Left pane <select id="left-variant"></select></label>
-        <label>Right pane <select id="right-variant"></select></label>
-        <label>Left directory <input id="left-cwd" autocomplete="off" spellcheck="false" required></label>
-        <label>Right directory <input id="right-cwd" autocomplete="off" spellcheck="false" required></label>
-        <label>Left label <input id="left-custom-label" placeholder="NATIVE"></label>
-        <label>Right label <input id="right-custom-label" placeholder="PENNY"></label>
-      </div>
-      <label>Model (both panes)
-        <input id="model" placeholder="Harness default" autocomplete="off" spellcheck="false"></label>
-      <div id="local-environment"></div>
       <p class="error" id="local-error" role="alert"></p>
       <button class="primary" id="local-start" type="submit" disabled>Start comparison</button>
       <p class="footnote">Exit saves a JSON report under <code>apps/compare/reports</code>.</p>
@@ -345,6 +315,7 @@
           <div class="segmented" role="radiogroup" aria-label="Featured page">
             <label><input type="radio" name="publish-cover" value="penny" checked><span>Penny page</span></label>
             <label><input type="radio" name="publish-cover" value="native"><span>Native page</span></label>
+            <label><input type="radio" name="publish-cover" value="none"><span>No page</span></label>
           </div>
           <label>Your name, as shown publicly
             <input id="publish-name" maxlength="40" required autocomplete="nickname"></label>
@@ -638,13 +609,19 @@
       $('setup').hidden = true;
       $('sync').disabled = false;
       $('finish').disabled = false;
+      $('add-to-gallery').disabled = false;
       setStatus('Live');
       resize();
       terminals.left.focus();
       startFilePolling();
     };
-    $('finish').onclick = async () => {
+    let finishing = false;
+    let publishAfterFinish = false;
+    const finishComparison = async () => {
+      if (finishing || lastReport || !started) return;
+      finishing = true;
       $('finish').disabled = true;
+      $('add-to-gallery').disabled = true;
       setStatus('Saving files…');
       clearInterval(fileTimer);
       await pollFiles().catch(() => {});
@@ -652,6 +629,7 @@
       send({ type: 'exit' });
       setStatus(hosted ? 'Finishing…' : 'Saving report…');
     };
+    $('finish').onclick = finishComparison;
 
     // Files the agents write, previewed in a separate tab
     const previewTabs = new Map();
@@ -931,8 +909,7 @@
     };
 
     // Environment: the pricing schedule both meters use, plus the provider and proxy the
-    // comparison represents. The section lives in the hosted form and moves into the local one.
-    if (!hosted) $('local-environment').replaceWith($('environment'));
+    // comparison represents. (The website's demo collects these on its own setup card.)
     const environment = () => ({ pricing: $('pricing').value, provider: $('provider').value,
       proxy: $('proxy').value });
     const describeEnvironment = () => {
@@ -986,13 +963,9 @@
       }
     }
     const sideOf = (role) => (paneRoles.left === role ? 'left' : 'right');
-    const publishBlocker = () => {
-      if (!gallery) return 'Publishing needs a native pane and a Penny pane on the same harness.';
-      if (!snapshot[sideOf('NATIVE')].length || !snapshot[sideOf('PENNY')].length) {
-        return 'Publishing needs an HTML page in each pane.';
-      }
-      return '';
-    };
+    // Pages are optional: a comparison can be shared with just its numbers and a screenshot.
+    const publishBlocker = () =>
+      gallery ? '' : 'Publishing needs a native pane and a Penny pane on the same harness.';
     const prepareGallery = (message) => {
       lastReport = message;
       gallery = message.gallery || null;
@@ -1003,6 +976,8 @@
       }
       $('results-publish').hidden = false;
       if (blocker) $('results-publish').textContent = blocker;
+      if (publishAfterFinish && !blocker) openPublish();
+      publishAfterFinish = false;
       if (hosted) window.parent.postMessage({ type: 'compare-demo-finished' }, config.parentOrigin);
     };
     const remembered = (key, value) => {
@@ -1015,7 +990,22 @@
     const pagePolicy = "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data: blob:; " +
       "font-src data:; connect-src 'none'; frame-src 'none'; object-src 'none'; base-uri 'none'; form-action 'none'";
     const sandboxed = (html) => `<meta http-equiv="Content-Security-Policy" content="${pagePolicy}"><meta name="referrer" content="no-referrer">${html}`;
-    const chosen = (role) => snapshot[sideOf(role)][Number($(role === 'NATIVE' ? 'publish-native' : 'publish-penny').value) || 0];
+    // The page chosen for a side, or undefined when "No page" is selected.
+    const chosen = (role) => {
+      const value = $(role === 'NATIVE' ? 'publish-native' : 'publish-penny').value;
+      return value === '' ? undefined : snapshot[sideOf(role)][Number(value)];
+    };
+    // The featured page must be one that is shared; fall back to the other page, then to none.
+    const syncFeatured = () => {
+      const available = { penny: Boolean(chosen('PENNY')), native: Boolean(chosen('NATIVE')) };
+      for (const radio of document.querySelectorAll('input[name="publish-cover"]')) {
+        radio.disabled = radio.value !== 'none' && !available[radio.value];
+      }
+      if (document.querySelector('input[name="publish-cover"]:checked').disabled) {
+        const next = available.penny ? 'penny' : available.native ? 'native' : 'none';
+        document.querySelector(`input[name="publish-cover"][value="${next}"]`).checked = true;
+      }
+    };
     const checkedValue = (name) => document.querySelector(`input[name="${name}"]:checked`).value;
     const savingsText = (savings) => {
       if (!savings) return '';
@@ -1059,8 +1049,11 @@
       $('preview-savings').classList.toggle('loss', Boolean(savings && savings.cost < 0));
       const model = (meterSnapshots[sideOf('PENNY')]?.model || '').split('/').pop();
       $('preview-meta').textContent = [model, $('publish-name').value.trim()].filter(Boolean).join(' · ');
-      const cover = chosen(checkedValue('publish-cover') === 'native' ? 'NATIVE' : 'PENNY');
-      const key = `${checkedValue('publish-cover')}:${cover?.path}`;
+      syncFeatured();
+      const featured = checkedValue('publish-cover');
+      const cover = featured === 'none' ? undefined : chosen(featured === 'native' ? 'NATIVE' : 'PENNY');
+      $('publish-preview').hidden = !cover;
+      const key = `${featured}:${cover?.path}`;
       if (cover && key !== previewedCover) {
         previewedCover = key;
         $('publish-preview').srcdoc = sandboxed(cover.content);
@@ -1070,7 +1063,9 @@
       for (const [role, id] of [['NATIVE', 'publish-native'], ['PENNY', 'publish-penny']]) {
         const select = $(id);
         if (!select.options.length) {
+          select.add(new Option('No page', ''));
           snapshot[sideOf(role)].forEach((file, index) => select.add(new Option(file.path, String(index))));
+          select.value = snapshot[sideOf(role)].length ? '0' : '';
         }
       }
       if (!$('publish-name').value) $('publish-name').value = remembered('penny-compare-display-name');
@@ -1079,7 +1074,11 @@
       $('publish').hidden = false;
       $('publish-title').focus();
     };
-    $('add-to-gallery').onclick = openPublish;
+    $('add-to-gallery').onclick = () => {
+      if (lastReport) return openPublish();
+      publishAfterFinish = true;
+      return finishComparison();
+    };
     $('results-publish').onclick = openPublish;
     $('publish-cancel').onclick = () => { $('publish').hidden = true; };
     $('publish-form').addEventListener('input', updatePreview);
@@ -1101,6 +1100,7 @@
       if (published) return;
       const native = chosen('NATIVE');
       const penny = chosen('PENNY');
+      const featured = checkedValue('publish-cover');
       const video = $('publish-video').files[0] || null;
       const videoType = video && (video.type || (/\.webm$/i.test(video.name) ? 'video/webm' : /\.mp4$/i.test(video.name) ? 'video/mp4' : ''));
       $('publish-error').textContent = '';
@@ -1114,7 +1114,8 @@
       }
       const meta = { title: $('publish-title').value.trim(), comment: $('publish-comment').value.trim(),
         tag: checkedValue('publish-tag'), display_name: $('publish-name').value.trim(),
-        native_file: native.path, penny_file: penny.path, cover: checkedValue('publish-cover'),
+        native_file: native?.path ?? null, penny_file: penny?.path ?? null,
+        cover: featured === 'none' ? null : featured,
         video_type: video ? videoType : null };
       const submit = $('publish-submit');
       submit.disabled = true;
@@ -1124,13 +1125,13 @@
       try {
         if (hosted) {
           result = await relayToParent({ report: gallery.report, signature: gallery.signature,
-            reportNonce: gallery.reportNonce, meta, native: native.content, penny: penny.content, video,
+            reportNonce: gallery.reportNonce, meta, native: native?.content ?? null, penny: penny?.content ?? null, video,
             cover: coverImage });
         } else {
           const form = new FormData();
           form.set('meta', JSON.stringify(meta));
-          form.set('native', new Blob([native.content], { type: 'text/html' }), 'native.html');
-          form.set('penny', new Blob([penny.content], { type: 'text/html' }), 'penny.html');
+          if (native) form.set('native', new Blob([native.content], { type: 'text/html' }), 'native.html');
+          if (penny) form.set('penny', new Blob([penny.content], { type: 'text/html' }), 'penny.html');
           if (video) form.set('video', video, video.name);
           if (coverImage) form.set('cover', coverImage, 'cover');
           const response = await fetch('/gallery/submit', { method: 'POST',
@@ -1173,89 +1174,30 @@
         showReport(message);
         prepareGallery(message);
       }
-      else if (message.type === 'report-error') showReportError(message.error);
+      else if (message.type === 'report-error') {
+        publishAfterFinish = false;
+        showReportError(message.error);
+      }
       else return false;
       return true;
     };
 
     if (hosted) {
-      // Hosted sandbox: the parent page supplies the session token, then the key form starts both panes.
-      $('setup').hidden = false;
-      $('hosted-setup').hidden = false;
+      // Hosted sandbox: the website shows the setup card. It supplies the session token, then the
+      // visitor's choices; this page reports progress back and shows the terminals once started.
       let tokenAccepted = false;
+      let authenticated = false;
       let launchError = '';
-      let progressTimer;
-      const clearProgress = () => {
-        clearInterval(progressTimer);
-        $('progress').replaceChildren();
-      };
-      const showProgress = (lead, steps = [], current = -1) => {
-        clearInterval(progressTimer);
-        const intro = document.createElement('p');
-        intro.textContent = lead;
-        const list = document.createElement('ol');
-        let elapsed;
-        steps.forEach((label, index) => {
-          const item = document.createElement('li');
-          item.className = index < current ? 'done' : index === current ? 'current' : '';
-          const text = document.createElement('span');
-          text.textContent = label;
-          item.append(text);
-          if (index === current) {
-            elapsed = document.createElement('span');
-            elapsed.className = 'elapsed';
-            elapsed.setAttribute('aria-hidden', 'true');
-            item.append(elapsed);
-          }
-          list.append(item);
-        });
-        $('progress').replaceChildren(intro, list);
-        if (!elapsed) return;
-        const since = Date.now();
-        // Only show a counter once a step is slow enough for the wait to be noticeable.
-        progressTimer = setInterval(() => {
-          const seconds = Math.floor((Date.now() - since) / 1000);
-          elapsed.textContent = seconds >= 2 ? `${seconds}s` : '';
-        }, 500);
-      };
-      // Mirrors the server's key check; the server closes the sandbox on a rejected start.
-      const plausibleKey = (key) => key.length > 3 && key.length <= 1024 && !/\s/.test(key) && key.startsWith('sk-');
-      $('hosted-setup').onsubmit = (event) => {
-        event.preventDefault();
-        const harness = $('harness');
-        const input = $('key');
-        const second = $('penny-key');
-        const start = $('hosted-start');
-        const nativeKey = input.value.trim();
-        const pennyKey = second.value.trim() || nativeKey;
-        const provider = harness.value === 'claude' ? 'Anthropic' : 'OpenAI';
-        if (!plausibleKey(nativeKey) || !plausibleKey(pennyKey)) {
-          $('hosted-error').textContent = `That doesn't look like an ${provider} API key. Keys start with "sk-".`;
+      const toParent = (message) => window.parent.postMessage(message, config.parentOrigin);
+      window.addEventListener('message', (event) => {
+        if (event.origin !== config.parentOrigin || event.source !== window.parent) return;
+        if (event.data?.type === 'compare-demo-start' && authenticated) {
+          const { harness, model, nativeKey, pennyKey, environment: chosen } = event.data;
+          send({ type: 'start', harness, model, nativeKey, pennyKey, environment: chosen });
+          setStatus('Starting terminals…');
           return;
         }
-        $('hosted-error').textContent = '';
-        send({ type: 'start', harness: harness.value, nativeKey, pennyKey, environment: environment() });
-        input.value = '';
-        second.value = '';
-        for (const field of [harness, input, second, $('pricing'), $('provider'), $('proxy')]) field.disabled = true;
-        refreshPickers();
-        input.placeholder = 'Key received';
-        start.disabled = true;
-        start.classList.add('busy');
-        start.textContent = 'Starting terminals…';
-        showProgress('Key received. Preparing your terminals…');
-        setStatus('Starting terminals…');
-      };
-      $('harness').onchange = (event) => {
-        limitProviders(event.target.value === 'codex');
-        const name = event.target.value === 'claude' ? 'Anthropic' : 'OpenAI';
-        const suffix = event.target.value === 'claude' ? '' : ' (for Codex)';
-        $('key-label').textContent = `${name} API key${suffix}`;
-        $('penny-key-label').textContent = `${name} API key${suffix} (second account)`;
-      };
-      window.addEventListener('message', (event) => {
-        if (event.origin !== config.parentOrigin || event.source !== window.parent ||
-            event.data?.type !== 'compare-demo-session' || tokenAccepted) return;
+        if (event.data?.type !== 'compare-demo-session' || tokenAccepted) return;
         tokenAccepted = true;
         sessionToken = event.data.token;
         socket = new WebSocket(`wss://${location.host}/terminal`);
@@ -1267,33 +1209,32 @@
           if (message.type === 'authenticated') {
             $('download-logs').hidden = !message.captureLogs;
             if (message.subscription) {
-              $('setup').hidden = true;
               setStatus('Starting subscription test · costs are API-equivalent estimates');
               send({ type: 'start', harness: message.subscriptionHarness || 'claude' });
               return;
             }
-            setStatus('Ready for your key');
-            $('hosted-start').disabled = false;
+            authenticated = true;
+            setStatus('Ready');
+            toParent({ type: 'compare-demo-authenticated' });
           } else if (message.type === 'progress') {
-            showProgress('Key received. Preparing your terminals…', message.steps, message.current);
+            setStatus(message.steps?.[message.current] || 'Starting terminals…');
+            toParent({ type: 'compare-demo-progress', steps: message.steps, current: message.current });
           } else if (message.type === 'started') {
-            clearProgress();
             markStarted();
+            toParent({ type: 'compare-demo-started' });
           } else if (message.type === 'error') {
             launchError = message.error;
-            $('hosted-start').classList.remove('busy');
-            clearProgress();
-            $('hosted-error').textContent = message.error;
             setStatus('Could not start');
+            toParent({ type: 'compare-demo-error', error: message.error });
           }
         });
         socket.addEventListener('close', () => {
           clearInterval(fileTimer);
-          $('hosted-start').disabled = true;
           $('finish').disabled = true;
+          if (!lastReport) $('add-to-gallery').disabled = true;
           if (!$('results').hidden) return;
           setStatus('Session ended');
-          window.parent.postMessage({ type: 'compare-demo-ended', error: launchError }, config.parentOrigin);
+          toParent({ type: 'compare-demo-ended', error: launchError });
         });
       });
       window.parent.postMessage({ type: 'compare-demo-ready' }, config.parentOrigin);
@@ -1329,6 +1270,50 @@
       $('right-variant').value = `penny-${config.defaultHarness}`;
       $('left-cwd').value = config.folders.left;
       $('right-cwd').value = config.folders.right;
+      // Options a pane supports beyond its harness, under its picker (see pane-options.mjs).
+      const optionControls = { left: [], right: [] };
+      for (const side of sides) {
+        const details = document.createElement('details');
+        details.hidden = true;
+        details.append(document.createElement('summary'));
+        for (const option of config.paneOptions || []) {
+          const group = document.createElement('div');
+          group.className = 'option';
+          const label = document.createElement('label');
+          label.append(document.createTextNode(option.label));
+          const select = document.createElement('select');
+          for (const choice of option.choices) select.add(new Option(choice.label, choice.value));
+          select.value = option.default;
+          label.append(select);
+          const hint = document.createElement('p');
+          hint.className = 'hint';
+          hint.textContent = option.hint;
+          group.append(label, hint);
+          details.append(group);
+          optionControls[side].push({ option, select, group });
+        }
+        $(`${side}-options`).append(details);
+      }
+      const supportedControls = (side, variant) =>
+        optionControls[side].filter(({ option }) => option.variants.includes(variant));
+      const optionSummary = (side, variant) => supportedControls(side, variant).map(({ option, select }) =>
+        option.choices.find((choice) => choice.value === select.value)?.summary).filter(Boolean).join(' · ');
+      const refreshOptions = () => {
+        for (const side of sides) {
+          const variant = $(`${side}-variant`).value;
+          const details = $(`${side}-options`).firstElementChild;
+          const supported = supportedControls(side, variant);
+          details.hidden = !supported.length;
+          for (const control of optionControls[side]) control.group.hidden = !supported.includes(control);
+          const summary = details.firstElementChild;
+          summary.replaceChildren(`${side === 'left' ? 'Left' : 'Right'} options `);
+          const choice = document.createElement('span');
+          choice.className = 'choice';
+          choice.textContent = `· ${optionSummary(side, variant)}`;
+          summary.append(choice);
+        }
+      };
+      for (const side of sides) for (const { select } of optionControls[side]) select.addEventListener('change', refreshOptions);
       let modelFamily = 'claude';
       const refreshVariants = () => {
         const left = $('left-variant').value;
@@ -1346,6 +1331,7 @@
         modelSuggestions = family ? [{ value: '', label: 'Harness default' },
           ...modelChoices[family].map(([value, label]) => ({ value, label }))] : [];
         model.placeholder = family ? 'Harness default' : 'Pick panes from the same harness to choose a model';
+        refreshOptions();
         refreshPickers();
       };
       $('left-variant').onchange = refreshVariants;
@@ -1371,8 +1357,14 @@
           model: comboValue($('model'), modelSuggestions),
         };
         for (const side of sides) {
-          $(`${side}-label`).textContent = settings[side].label || roleLabel(settings[side].variant);
-          paneRoles[side] = roleLabel(settings[side].variant);
+          const { variant } = settings[side];
+          settings[side].options = Object.fromEntries(supportedControls(side, variant)
+            .map(({ option, select }) => [option.id, select.value]));
+          $(`${side}-label`).textContent = settings[side].label || roleLabel(variant);
+          paneRoles[side] = roleLabel(variant);
+          const chip = $(`${side}-chip`);
+          chip.textContent = optionSummary(side, variant);
+          chip.hidden = !chip.textContent;
         }
         pending = true;
         $('local-start').disabled = true;
@@ -1415,6 +1407,7 @@
         clearInterval(fileTimer);
         $('sync').disabled = true;
         $('local-start').disabled = true;
+        if (!lastReport) $('add-to-gallery').disabled = true;
         if (!$('finish').disabled) {
           $('finish').disabled = true;
           setStatus('Disconnected · reload to reconnect');

package/standalone/web-demo/gallery-submit.mjs

@@ -25,7 +25,7 @@ export async function savedPennyKey() {
   }
 }
 
-/** Sends the report, the chosen pages, and an optional video; returns the new entry's id. A
+/** Sends the report, the chosen pages (each optional), and an optional video; returns the new entry's id. A
  * report signed by its demo sandbox (the subscription launcher) carries that signature. */
 export async function publishToGallery(report, form, { signature = '', reportNonce = '' } = {}) {
   const key = await savedPennyKey();
@@ -37,8 +37,7 @@ export async function publishToGallery(report, form, { signature = '', reportNon
   outgoing.set('meta', String(form.get('meta') ?? ''));
   for (const side of ['native', 'penny']) {
     const page = form.get(side);
-    if (!(page instanceof Blob)) throw new Error('Choose a native page and a Penny page.');
-    outgoing.set(side, page, `${side}.html`);
+    if (page instanceof Blob) outgoing.set(side, page, `${side}.html`);
   }
   const cover = form.get('cover');
   if (cover instanceof Blob && cover.size) outgoing.set('cover', cover, 'cover');

package/standalone/web-demo/pane-options.mjs

@@ -0,0 +1,58 @@
+// Options a pane can carry beyond its harness, shown under its picker in the local setup card.
+// Each option names the pane variants it applies to, the choices it offers, and how a choice
+// reaches the harness. The setup page renders its controls from describePaneOptions().
+
+const cacheTtl = {
+  id: 'cacheTtl',
+  label: 'Cache TTL',
+  variants: ['penny-claude'],
+  default: '5m',
+  choices: [
+    { value: '5m', label: '5 minutes (default)', summary: '5-minute cache' },
+    { value: '1h', label: '1 hour', summary: '1-hour cache' },
+  ],
+  hint: 'How long the conversation cache lives. The shared prefix is always 1 hour, and a session’s ' +
+    'cold first write stays at 5 minutes.',
+  // Claude Code chooses the lifetime of its own cache breakpoints; PennyRouter passes a client's
+  // 1-hour request through once the session's cache is warm.
+  apply(env, value) {
+    delete env.ENABLE_PROMPT_CACHING_1H;
+    delete env.FORCE_PROMPT_CACHING_5M;
+    env[value === '1h' ? 'ENABLE_PROMPT_CACHING_1H' : 'FORCE_PROMPT_CACHING_5M'] = '1';
+  },
+};
+
+export const paneOptions = [cacheTtl];
+
+const supportedBy = (variant) => paneOptions.filter((option) => option.variants.includes(variant));
+
+/** A pane's options validated for its variant, with defaults filled in. */
+export function normalizePaneOptions(variant, raw) {
+  const given = raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : {};
+  const supported = supportedBy(variant);
+  for (const id of Object.keys(given)) {
+    if (!supported.some((option) => option.id === id)) {
+      throw new Error('Invalid compare settings. That option does not apply to this pane.');
+    }
+  }
+  const options = {};
+  for (const option of supported) {
+    const value = given[option.id] ?? option.default;
+    if (!option.choices.some((choice) => choice.value === value)) {
+      throw new Error(`Invalid compare settings. Choose a listed ${option.label}.`);
+    }
+    options[option.id] = value;
+  }
+  return options;
+}
+
+/** Sets the environment a pane's harness reads for its chosen options. */
+export function applyPaneOptions(env, variant, options) {
+  for (const option of supportedBy(variant)) option.apply(env, options?.[option.id] ?? option.default);
+}
+
+/** The JSON-safe description the setup page renders its controls from. */
+export function describePaneOptions() {
+  return paneOptions.map(({ id, label, variants, default: initial, choices, hint }) =>
+    ({ id, label, variants, default: initial, choices, hint }));
+}

package/standalone/web-demo/server.mjs

@@ -10,6 +10,7 @@ import { WebSocketServer } from 'ws';
 import pty from 'node-pty';
 import { ClaudeMeter, CodexMeter, galleryReport, pricingProfiles, saveReport } from './claude-meter.mjs';
 import { publishToGallery } from './gallery-submit.mjs';
+import { applyPaneOptions, describePaneOptions, normalizePaneOptions } from './pane-options.mjs';
 import { listArtifacts, readArtifact } from './artifacts.mjs';
 import { readTelemetry, telemetryEnv, telemetryRoute } from './telemetry.mjs';
 import { Readable } from 'node:stream';
@@ -96,7 +97,7 @@ const server = createServer(async (request, response) => {
   try {
   let body = await readFile(join(here, file[0]));
   if (request.url === '/') {
-    const config = { mode: 'local', compare, defaultHarness: startupHarness,
+    const config = { mode: 'local', compare, defaultHarness: startupHarness, paneOptions: describePaneOptions(),
       folders: { left: join(launchDirectory, 'native'), right: join(launchDirectory, 'penny') },
       versions: await harnessVersions };
     body = body.toString('utf8')
@@ -186,7 +187,7 @@ async function validateConfig(config) {
   if (!existing && !(await stat(dirname(cwd)).catch(() => null))?.isDirectory()) {
     throw new Error(`Folder does not exist: ${dirname(cwd)}`);
   }
-  return { ...config, cwd, create: !existing };
+  return { ...config, cwd, create: !existing, options: normalizePaneOptions(config.variant, config.options) };
 }
 
 // Each pane needs its own folder: agents running side by side in one folder would edit the
@@ -337,7 +338,8 @@ wss.on('connection', (ws) => {
           const Meter = config.variant.includes('codex') ? CodexMeter : ClaudeMeter;
           const role = config.variant.startsWith('penny-') ? 'PENNY' : 'NATIVE';
           meter = new Meter({ sessionId, cwd: config.cwd, side: message.side, role,
-            label: config.label, variant: config.variant, pricingProfile: environment.pricing });
+            label: config.label, variant: config.variant, pricingProfile: environment.pricing,
+            options: config.options });
         }
         // Claude panes report background model calls to this server; see telemetry.mjs.
         const route = meter instanceof CodexMeter || !meter ? null : telemetryRoute();
@@ -352,6 +354,7 @@ wss.on('connection', (ws) => {
             delete env[key];
           }
         }
+        applyPaneOptions(env, config.variant, config.options);
         const session = pty.spawn(command, commandArgs, {
           name: 'xterm-256color', cols: message.cols, rows: message.rows,
           cwd: config.cwd, env,