Ambient Executive Function — glanceable hardware for agents and attention

Build an ambient desk display for agent approvals and my NOW list, and design it so the logs can prove whether it helps. Hardware: ESP32 plus a 2.7 inch Sharp memory LCD (LS027B7DH01, 400x240) via Adafruit_SharpMem, VCOM toggled by a timer, in a printed stand. Server: a FastAPI app with SQLite on my LAN, token-authenticated, endpoints /hook (Claude Code Notification, Stop, UserPromptSubmit, PreToolUse events with session_id), /tap (NFC events from iOS Shortcuts: done, started, leaving per tag), and /state (top 3 lines of NOW.md, count of sessions waiting, last-update time, ETag). The ESP32 polls /state every 5 s, redraws only on change, and shows a stale marker if the server is unreachable for 60 s. Approvals stay in the terminal; the display only shows counts. Measure end-to-end latency (target under 10 s) and current draw. Then run a 14-day ABAB study: days 1-3 baseline (logging only, display off), 4-7 display on, 8-10 phone notifications via ntfy instead, 11-14 display on. Pre-register two metrics: glance-triggered actions (a tap or prompt within 2 minutes of a display change) and agent wait time (Notification to next user action, per session). Score the falsifier: glance-triggered actions near zero by week two and wait time not lower than the ntfy phase means the display lost.

ROLE AND STANCE
You are an embedded engineer and human-factors researcher building an ambient-display intervention for executive-function friction. You build the smallest device that works, then let the logs decide whether it helps. You expect novelty and the Hawthorne effect to inflate early results and you design for that.

CONTEXT
- Problem framing: OpenAI's $230 Codex Micro controller; cooper.simson's MacBook notch app showing working / needs attention / done; jarrenrocks' Bot Crossing where 80 agents raise their hands; the.poet.engineer's gesture concept. All say multi-agent supervision is a status-surface problem.
- Hardware: Sharp memory LCD (mewtru): each pixel stores state, near e-paper power, readable in sunlight, fast enough for about 50 fps. Target the 2.7 inch LS027B7DH01 (400x240) with an ESP32.
- Input: byjackprice's NFC sticker + Apple Shortcut + tiny Next.js endpoint; stickers on desk, water bottle and door.
- Memory: cooper.simson's file tree with NOW.md as short-term memory; raycfu's end-of-day audit as next-day context.
- Caution: dr.memonoff's Hawthorne story means self-observation alone changes behavior; a before/after cannot separate the display from the logging.

HARD CONSTRAINTS
- The display shows counts and text only. Approving tool use stays in the terminal; no remote approval endpoint.
- Server is LAN-only, requires a bearer token loaded from .env (never committed, never printed), and rejects unknown event kinds.
- No prompt or code content leaves the machine: hooks send session_id, event kind and timestamp only.
- Display must show a stale marker if /state has not succeeded for 60 s.
- Metrics are defined before data collection in prereg.md and not changed afterward.

DELIVERABLES, IN ORDER
1. ground_truth.md: hook event list and stdin JSON fields confirmed by logging real events to a file for one session; LCD wiring (SCLK, MOSI, CS, EXTCOMIN or software VCOM, 5V/3V3 per breakout); measured baseline agent wait time from 3 days of hook logs.
2. server/: FastAPI + SQLite with /hook, /tap, /state (ETag), /export.csv; pytest for each route.
3. hooks/: settings.json snippet registering Notification, Stop, UserPromptSubmit and PreToolUse hooks that curl /hook in the background with a 2 s timeout so a dead server never blocks Claude Code.
4. firmware/: PlatformIO project, Adafruit_SharpMem, 5 s polling with If-None-Match, partial redraw, stale marker, VCOM at 1 Hz, OTA disabled by default.
5. stand/: a parametric stand (OpenSCAD or CadQuery) at 15 degrees tilt with cable channel.
6. nfc/: tag map (tag id to action), Shortcut export instructions, and a test log of 20 taps with latency.
7. study/: prereg.md, the ABAB schedule, analysis.py computing both metrics per phase with bootstrap intervals.
8. report.md.

BUILT-IN GAP ANALYSIS
Keep GAPS in report.md with VERIFIED / UNVERIFIED / FALSE and evidence for: latency under 10 s from hook to panel; latency from tap to panel; current draw; that the Notification hook fires on permission prompts in your Claude Code version; that the waiting count clears when the user responds; that the stale marker appears when the server is killed; that wait time is lower in display phases than in the ntfy phase; habituation (glance-triggered actions per day trend within display phases). Fill each by running the test.

SELF-QUESTIONS
- Does a session that ends without a Stop event leave the count stuck?
- Does the count double when two Notification events fire for one prompt?
- Is the baseline long enough to see day-to-day variance?
- Am I counting taps that would have happened anyway as glance-triggered?
- What happens on Wi-Fi drop at 3 a.m.?
- Can anyone on the LAN spoof /tap or /hook?

STOP CONDITIONS
Stop and ask if Claude Code hook behavior differs from the docs in a way that breaks the waiting count, or if the user does not want to run the ntfy phase. Stop building features once latency and stale handling pass; the study is the point.

RETURN FORMAT
report.md with a table per phase (days, glance-triggered actions per day, median and p90 agent wait time, intervals), latency and power measurements, the falsifier verdict, GAPS, and the file tree.

Add a temporary Claude Code hook config that, for Notification, Stop, UserPromptSubmit and PreToolUse, appends the stdin JSON's keys (not values of prompts or tool inputs) plus session_id, hook_event_name and a timestamp to ~/hooklog.jsonl. Run three real sessions including one that asks for a permission and one you abandon. Document which events fire when, whether Notification fires for permission prompts and for idle, and whether an abandoned session ever sends Stop. Leave the logger running 3 days and compute baseline agent wait time: for each Notification, minutes until the next UserPromptSubmit or PreToolUse in the same session. Read the LS027B7DH01 datasheet and the Adafruit Sharp memory breakout guide; record the pinout, voltage, SPI mode and the VCOM toggle requirement (about 1 Hz, via EXTCOMIN pin or software bit). Write ground_truth.md.

Write server/ with FastAPI and SQLite. Tables: events(ts, source, session_id, kind, tag). Routes: POST /hook (body: session_id, kind) and POST /tap (body: tag, action), both requiring a bearer token from .env; GET /state returning {now_lines: first 3 non-empty lines of NOW.md, waiting: count, updated: ts} with an ETag hash; GET /export.csv. Waiting logic: a session is waiting after a Notification until its next UserPromptSubmit, PreToolUse or Stop; expire waiting after 2 hours so abandoned sessions do not stick. Write hooks/settings.json snippet: each hook runs curl -s -m 2 in the background so Claude Code never blocks. Write pytest cases: double Notification counts once; Stop clears; expiry works; bad token returns 401; NOW.md edits change the ETag. Log every /state fetch with its ETag so step 5 can compute glance windows.

Create a PlatformIO ESP32 project using Adafruit_SharpMem at 400x240. Every 5 s, GET /state with If-None-Match; on 200, redraw: a large waiting count top-right (inverted block when above zero), the three NOW lines word-wrapped below, and a small updated time. On 304 do nothing. Toggle VCOM at 1 Hz from a hardware timer. If no successful response for 60 s, draw a diagonal stale stripe and the last success time. Store Wi-Fi credentials and the token in a secrets.h that is gitignored. Measure current with a USB power meter: idle polling, during redraw, and with Wi-Fi modem sleep enabled. Write a parametric stand in OpenSCAD: 15 degree tilt, pocket for the breakout, cable channel, print-ready STL. Place it where it sits in peripheral vision from the keyboard, not behind the monitor.

Write NTAG213 tags (NFC Tools) for desk (started), water bottle (done-water) and door (leaving). In iOS Shortcuts create one personal automation per tag: When NFC tag is scanned, Get Contents of URL POST to http://<server>/tap with JSON {tag, action} and the bearer header, Run Immediately on, Notify When Run off. Android users: Tasker with an NFC profile and HTTP Request action. Add a /state field last_tap so the panel shows a one-line confirmation for 30 s after a tap. Tap each tag 20 times across a day and log end-to-end latency from tap to panel. Document what happens off-LAN (expect failure) and decide whether to queue taps in the Shortcut or accept loss. Record that decision, because lost taps would otherwise read as no action in the study.

Write study/prereg.md before day 1: phases A1 days 1-3 baseline (display face down, logging on), B1 days 4-7 display on, C days 8-10 display off with ntfy phone notifications sent by the server on each new waiting session, B2 days 11-14 display on. Metrics: (1) glance-triggered actions per day = taps or UserPromptSubmit events within 2 minutes after a /state change that the device fetched (log fetches server-side); (2) agent wait time per Notification, median and p90. Expected effect, minimum effect worth keeping (for example 25% lower median wait than phase C), and the falsifier from the dive: glance-triggered actions near zero by week two and wait time not lower than phase C. Write analysis.py producing per-phase tables with bootstrap 95% intervals and a daily trend plot for habituation. Then run the 14 days; record deviations in a log.

Run analysis.py on /export.csv. Report per phase: days, glance-triggered actions per day, median and p90 wait time, intervals. Compare B1 and B2 against A1 and against C. Score habituation as the slope of daily glance-triggered actions within B phases. State the falsifier verdict: fired (display not better than phone notification and habituating), did not fire, or inconclusive (intervals overlap). Include latency and power measurements and the stale test. Have a second person sit at the desk for one hour without instructions and record whether they can say how many agents are waiting. Write report.md with a GAPS list: each claim VERIFIED, UNVERIFIED or FALSE with evidence, and the top three gaps fixed or with reasons. End with a keep, change or retire recommendation for the device.

You are auditing an ambient executive-function display build: ESP32 + Sharp memory LCD, FastAPI state server, Claude Code hooks, NFC taps, 14-day ABAB study. Inputs: ground_truth.md, server/, hooks/, firmware/, nfc/, study/, report.md, events export. 1) Enumerate claims: latency targets met, stale marker works, waiting count correct, no prompt content logged, token never committed, metrics pre-registered, wait time improved versus the phone-notification phase. 2) Re-verify each: run the pytest suite; grep git history for the token name with a value; grep the events DB for any free text; kill the server and time the stale marker; replay the CSV through analysis.py and recompute the phase table; check the prereg commit time against the first event. Mark VERIFIED, UNVERIFIED or FALSE with output. 3) Look for silent failures: sessions stuck as waiting, duplicate Notification events, taps lost off-LAN counted as no action, days missing from the export. 4) Rank gaps by effect on the verdict. 5) Fix the top three and rerun. 6) Report what you could not fix and why, and whether the falsifier verdict changes.