reference pwa staleness

The problem this solves

The PWA used to rebuild once at 11pm nightly. If anything changed during the day — new draft, deal stage moved, new transcript, action item captured — the PWA stayed stale until midnight. User opens PWA on their phone → sees yesterday's state → makes a decision on stale data. Dangerous.

Three layers of freshness

Layer 1 — Instant rebuild on state change (best case)

launchd agent: com.skyrun.pwa-autorebuild (plist at ~/Library/LaunchAgents/).

Uses native macOS WatchPaths — fires the rebuild script within seconds of any watched file being modified.

Watches:

/Users/josephbowens/Desktop/SkyRun/morning_brief.md
All pending_*.jsonl in ~/Library/Application Support/SkyRun/pwa/data/
/Users/josephbowens/Desktop/SkyRun/knowledge_graph.json
/Users/josephbowens/.claude/projects/.../memory/MEMORY.md
/Users/josephbowens/Desktop/SkyRun/Consolidation Reports/ (directory)

Script: ~/Library/Application Support/SkyRun/pwa_auto_rebuild.sh

Debounced: skips if last rebuild was <30s ago (prevents thrashing)
launchd also enforces ThrottleInterval: 15s as backup
Runs build_pwa.py + deploy_pwa.sh
Logs to ~/Library/Logs/skyrun-pwa-autorebuild.log

⚠️ Requires Full Disk Access for /bin/bash + /usr/bin/python3:
Without FDA, launchd-spawned bash can't read Desktop/SkyRun. Add both binaries via:
System Settings → Privacy & Security → Full Disk Access → + → select /bin/bash and /usr/bin/python3.

If FDA isn't granted, Layer 1 silently logs "Operation not permitted" and Layer 2 catches the staleness within 20 min.

Layer 2 — Live-ea 20-min ceiling (always-on safety net)

live-ea scheduled task already runs every 20 min during business hours (weekdays 9am–7pm MDT). Added Step 7b (Apr 24): if this run processed any drafts / captures / drive-sort files, rebuild + deploy PWA.

Gives a 20-min maximum staleness guarantee during business hours, regardless of FDA. Automatic, no config needed.

Layer 3 — Nightly baseline (catches the overnight window)

nightly-consolidation at 11pm already rebuilds + deploys. Keeps the PWA current through the morning even if live-ea and the fswatch agent both miss something.

Per-section freshness badges

Every PWA section header shows a color-coded freshness badge:

Color	Meaning	Thresholds (by section)
🟢 fresh	Current	brief <6h, graph <24h, approvals <1h, health <2h
🟡 aging	Getting old	brief <24h, graph <72h, approvals <6h, health <6h
🔴 stale	Needs a rebuild	above the aging threshold

Badges appear in:

Section summaries (Approvals, Morning Brief, Relationships, System Health)
Top sync banner (overall freshness indicator)

Top sync banner

New at the top of every PWA view:


🔄 Last synced 10:15 AM · brief 🟢 12m ago · graph 🟢 2h ago · approvals 🟢 45m ago · health 🟢 10m ago   [↻ Reload]

Absolute time of last page render
Per-source freshness badges
↻ Reload button — forces a fresh page load (useful if you suspect something newer is on Cloudflare)

What this guarantees

During business hours (weekdays 9am-7pm): ≤20 min stale in worst case
With FDA granted: ≤30s stale when any state file changes
Outside business hours: rebuild happens on any live-ea skip run + automatic at 11pm
If you distrust any section's freshness: the badge will tell you immediately

Manual refresh options

↻ Reload button — forces browser to re-fetch index.html (picks up latest Cloudflare deploy)
Terminal: python3 /Users/josephbowens/Library/Application Support/SkyRun/build_pwa.py && bash "/Users/josephbowens/Library/Application Support/SkyRun/deploy_pwa.sh"
Touch any watched file (in Terminal, FDA granted): touch /Users/josephbowens/Desktop/SkyRun/morning_brief.md → triggers Layer 1 rebuild

Files

Purpose	Path
fswatch script	`~/Library/Application Support/SkyRun/pwa_auto_rebuild.sh`
launchd agent	`~/Library/LaunchAgents/com.skyrun.pwa-autorebuild.plist`
Log	`~/Library/Logs/skyrun-pwa-autorebuild.log`
PWA build script	`/Users/josephbowens/Library/Application Support/SkyRun/build_pwa.py`
PWA deploy script	`~/Library/Application Support/SkyRun/deploy_pwa.sh`
Deploy log	`~/Library/Logs/skyrun-pwa-deploy.log`

reference_pane_of_glass_pwa.md — the PWA itself
reference_approval_queue_v2.md — the approval queue that feeds the Approvals section
reference_scheduled_tasks.md — live-ea + nightly-consolidation context