stack/agents/dewey/work/queue-173/BUILD.md

Row 173 (#1671): a Seen click that waited out a Board read keeps the meaning it was clicked with

Brief: docs/plans/2026-10-19_seen-click-intent.md (blob 225ac823b). Branch dewey/row173 off aca16404c. Queue reviewer: Darkwing. Gate (queue row): Darkwing approves on #1671 naming the candidate manifest; webui and every scripts/test-*.sh green on Sage's gate rerun.

Design

• Intent. seenButton draws data-intent="seen" on a Seen button and data-intent="unsee" on an Unsee button, from the same r.seen that picks the label. The click handler reads it into mark before writing = true and before the wait, so the fresh row can't change it. I chose a data- value over reading the label text so a later relabel can't change what a click posts.
• The fresh row already holds the intent (r.seen === mark). This happens when another viewer marked or unmarked the row while the read was in flight. Nothing is posted, the button is re-enabled, and the page announces <agent> already seen or <agent> already waiting.
  • Why post nothing. The route takes a repeat without harm: markSeen with seen:true rewrites the same mark, and seen:false deletes a key that is already gone (control-board/src/scan.mjs:255-256). So posting the same value would also be correct. It would cost a write and a rescan, though, and the read that just finished has already drawn the row. The brief allows either.
  • An unseen row can still hold an old mark for an earlier lastActivity. Posting nothing on Unsee leaves that mark, which is harmless because scanAgent only counts a mark equal to the row's lastActivity (scan.mjs:340).
• Otherwise the click posts seen: mark and announces from mark, not from the fresh row.
• Unchanged: the row 172 wait, the single-click guard (writing), the no-row branch, and the /api/seen route (out of scope).
• seen.disabled = false in the new branch matches the no-row branch. After the read, accept redraws the inspector and the cards, so seen is usually a detached button and the line has no visible effect. No test can tell it apart; see M5.

Test

packages/webui/tests/board-held.test.mjs gains one test: "a Seen or Unsee click that waited out a Board read keeps its meaning: another viewer's mark in that read posts nothing". setup returns boardURL: f.boardURL so the test can post to the board as the other viewer.

• Steps, for each of Seen and Unsee:
  • it holds /api/board with window.__hold and clicks Refresh;
  • while the read is held, it posts the other viewer's mark straight to the board;
  • it clicks the inspector's button and releases the read.
• Checks: the announcement (agent1 already seen, then agent1 already waiting), #seen-count (1, then 0), and that the page sent no /api/seen at all.
• The held fetch hasn't reached the board when the other viewer posts (the stub awaits the hold before calling the real fetch), so the released answer carries the other viewer's mark.

Hash pins and readers checked (git grep, with a positive control for 64-hex): nothing pins app.js. shell.test counts existing app.js strings only. browser.test, sso-browser.test and the other board-held tests click [data-seen] buttons the page draws, so they get data-intent with them.

Mutants (run on CLEAR only; each one edit to app.js, then board-held.test.mjs whole)

id	edit	expected kill
M1	post seen: !r.seen and drop the r.seen === mark branch (the old toggle)	new test (a post, and "returned to waiting")
M2	drop the r.seen === mark branch only (post the repeat)	new test (a post, and "marked seen")
M3	seenButton swaps the intent (r.seen ? 'seen' : 'unsee')	row 172 test (#seen-count never 1) and the new test
M4	the new branch returns without announce	new test (announcement wait times out)
M5	drop seen.disabled = false in the new branch	equivalent: the button is redrawn by accept; named, not run

Each run: timeout -k 10 180 node --test --test-force-exit packages/webui/tests/board-held.test.mjs; a kill counts only as an assertion or a named wait failing in the named test.

Runs

None yet. Gander holds the gate slot (row 253 run 5) from 16:32Z. The claim, the push and every run wait for Sage's CLEAR.

Round 2: rebase onto 78b69e1e6 (sage-4361)

• Branch dewey/row173-r2 off refactor 78b69e1e6. The round 1 commit 25ff7cd3f (on aca16404c, 555 commits behind) was cherry-picked as a new commit; dewey/row173 is untouched. No force-push.
• The pick merged on its own. git range-diff aca16404c..25ff7cd3f 78b69e1e6..<pick> reports the commit equal.
• Overlap with refactor: one app.js line, the /api/config handler at the end of the file (federation render). It is far from both row 173 hunks and changes no assertion or reviewed line. board-held.test.mjs and the brief (blob 225ac823b) are unchanged on refactor.
• No test pins app.js by hash (grepped tests for app.js plus 64-hex).

Run list

app.js is a page script, loaded by index.html, not imported by any module. Its test readers:

• by name: board-held, browser, granted-user, serve, shell, sso-browser, user-option-swap;
• by page load: every webui test that opens the Console through tests/browser.mjs (31 test files). No test outside packages/webui reads or serves app.js (git grep over packages/*/tests and scripts: none).

Order, each run with TMPDIR from mktemp -d /mnt/storage/scratch/tmp/d173XXXXXX and absolute paths:

1. M1-M4 below, each with board-held.test.mjs whole.
2. board-held.test.mjs whole on the restored tree.
3. packages/webui whole (all 70 test files), which covers both reader groups. case1-accept.test.mjs is not in the list (mos-1612). Runs need Sage's CLEAR.

Mutant procedure

The M1-M5 table above stands. M5 stays equivalent: the new branch is reached only after the waited-out Board read's accept (refresh, app.js:372) has redrawn the row, so seen is the detached old button. Each mutant is one edit to app.js. Before the next mutant, the restored app.js must match the candidate's sha256. Each run is in its own process group so a timeout kill takes its browser with it. Afterwards I sweep for orphaned node/chromium processes in my run directory.