TK-11793: README — scale design note (async pane watcher, stale-while-revalidate)

b5244e5a1713a43ae31ac96f06ca29c6e7bbc589 · 2026-09-16 08:48:40 -0700 · Steve Abrams

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Files touched

M README.md

Diff

commit b5244e5a1713a43ae31ac96f06ca29c6e7bbc589
Author: Steve Abrams <steve@designerwallcoverings.com>
Date:   Wed Sep 16 08:48:40 2026 -0700

    TK-11793: README — scale design note (async pane watcher, stale-while-revalidate)
    
    Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 README.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/README.md b/README.md
index e9005f5..823f4d9 100644
--- a/README.md
+++ b/README.md
@@ -36,6 +36,13 @@ Optional launchd: `com.steve.answer-cockpit.plist` (install is a Steve paste; ne
 - Every write-back **and every refusal** is audited to `data/audit.jsonl`. Unmeasured is never
   green: an unavailable terminal API → `stale:true`, POSTs 503, heartbeat WARN; iTerm down → FAIL.
 
+## Scale (51 live sessions, 45 panes — 2026-09-16)
+The expensive reads never run on the request path: a **background async pane watcher** refreshes
+the batched `contents of session` read every 12s (request paths read the cache; the POST guard
+does ONE blocking fresh read right before typing), and `build()` is **stale-while-revalidate** —
+one build at a time, concurrent polls get the last result instantly with `building:true`.
+Measured: health 0.14s *during* a build (was starved past 60s), concurrent queue 0.025s.
+
 ## Detail sources (where the card text comes from)
 1. `~/.claude/answer-cockpit/map/<tty>.json` (a future hook can make everything `exact`).
 2. `~/.claude/sessions/<pid>.json` → sessionId → transcript (`exact`).

← 3dfd1b3 chore: v0.2.1 — scale fix (async pane watcher, stale-while-r · back to Answer Cockpit · TK-11793: pane watcher only while a viewer is polling, 60s i 191e46b →