From 0e2de953abb29f739afad717a029da86b648d876 Mon Sep 17 00:00:00 2001
From: Sanket Sudake <sanketsudake@gmail.com>
Date: Sun, 16 Aug 2026 22:54:53 +0530
Subject: [PATCH 1/2] fix: --by cell ranks candidates by grid, re-resolves
 replaced nodes, names the cover
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three findings from a live timesheet run where `fill --by cell "Tue, …"`
failed as `occluded` on one column in five, every week, while the other
four columns filled fine.

1. cellLocatorJS picked candidates in document order after a geometric
   "in this column" filter. Workday's global "Search Workday" input sits
   above its Enter Time dialog with its centre inside one day column's
   tolerance; it comes first in the DOM and is under the modal overlay,
   so that column resolved to an off-grid, covered input and timed out.
   Rank candidates instead of filtering: the header's own grid beats the
   rest of the page, an unoccluded centre beats a covered one, document
   order breaks ties. Off-grid candidates stay as the last resort because
   some grids split header and body tables.
   TestCellAddressingPrefersGridOverOffGridField reproduces the wrong pick
   (value lands in the search box) on the old locator.

2. settledNodePoint polled one resolved node until the deadline. A grid
   that re-renders its row after a commit (Workday's does; input ids
   change) detaches that node, which then measures 0x0 forever and reads
   as `occluded`. The geometry probe now reports `detached`, and the new
   settledPointFor / coordClickSelector re-resolve the selector on it;
   Type, Fill, Key, the pointer verbs and drag targets all go through it.
   Only if the replacement never settles does the caller see a timeout,
   now with `detached: true`.
   TestCellAddressingReResolvesReplacedNode models the commit-veil-then-
   rebuild shape and fails on the old code with the exact message seen live.

3. `occluded: true` said nothing about WHAT was on top, so each failure had
   to be reproduced under instrumentation. OccludedError now carries the
   element found at the centre and puts it in the message ("its centre is
   covered by DIV name=\"modalOverlay\"", or "it measured 0x0"); the
   evidence rides in the message because errors cross the daemon as
   strings and the envelope must read the same on both paths. IsOccluded
   still matches. TestOccludedErrorMessage pins the format.

Live-verified on the real grid with the rebuilt binary: a five-column
session batch fills clean where the released binary failed the Tue cell.
---
 docs/cli-reference.md            |   5 +-
 internal/chrome/cdp.go           |  45 +++++++---
 internal/chrome/cell_test.go     | 148 +++++++++++++++++++++++++++++++
 internal/chrome/geometry.go      |  19 +++-
 internal/chrome/key.go           |   6 +-
 internal/chrome/pointer.go       |  15 ++--
 internal/chrome/pointer_test.go  |  40 +++++++++
 internal/chrome/select.go        | 130 ++++++++++++++++++++-------
 internal/cli/commands.go         |   8 ++
 skills/drive-chrome-cdp/SKILL.md |   7 ++
 10 files changed, 360 insertions(+), 63 deletions(-)

diff --git a/docs/cli-reference.md b/docs/cli-reference.md
index 0d0b73a..8ae5364 100644
--- a/docs/cli-reference.md
+++ b/docs/cli-reference.md
@@ -92,7 +92,7 @@ On real apps, prefer `name` — it reads the accessibility tree, skips hidden/ut
 | `id` | an element id | |
 | `name` | an ARIA accessible name | prefer on real apps; pair with `--role` / `--nth` / `--match` |
 | `ref` | a `snap`-issued `e<id>` ref | act on the exact node `snap` reported, no re-resolve |
-| `cell` | a `[row\|]column` grid header | resolves the editable input in that grid cell |
+| `cell` | a `[row\|]column` grid header | resolves the editable input in that grid cell; a candidate in the header's own grid beats one elsewhere on the page, and an unoccluded one beats a covered one |
 | `label` | a form control's visible label | for controls whose label isn't wired (no `aria-label` / `<label for>`) |
 | `search` | DevTools text/XPath/CSS search | broad; first match wins |
 | `jspath` | a JS path | |
@@ -292,7 +292,8 @@ A never-settling promise is bounded by `--timeout` (exit 4), and the connection
 | `attr get\|list\|set\|rm <selector> [name] [value]` | read/write element attributes |
 
 `click`, `hover`, `dblclick`, `rclick` and `drag` are one driver method behind five names: they resolve the identical occlusion-verified centre and all take `--modifiers` (`ctrl`/`shift`/`alt`/`cmd`, joined with `+`) — `click --modifiers cmd` is the multi-select in a table.
-An element that resolves but never presents an unoccluded centre fails as `target_timeout` with `occluded: true`, so it's distinguishable from "not found".
+An element that resolves but never presents an unoccluded centre fails as `target_timeout` with `occluded: true`, so it's distinguishable from "not found"; the message names what sat on top (`its centre is covered by DIV name="modalOverlay"`) or says the element measured 0x0, so the next step — dismiss an overlay, wait out a tooltip, re-check the selector — is read from the envelope rather than reproduced under instrumentation.
+If the page replaces the element while a verb waits on it (a grid re-rendering its row after a commit), the verb re-resolves the selector and continues on the replacement; only when the replacement never settles either does it fail, as `target_timeout` with `detached: true` — the page is churning, so `wait --stable` before retrying.
 
 `key` takes a named key, a printable character, a chord, or a space-separated sequence of those, and works with no selector at all — which is what makes it usable when nothing is addressable:
 
diff --git a/internal/chrome/cdp.go b/internal/chrome/cdp.go
index 4915036..d6aad8f 100644
--- a/internal/chrome/cdp.go
+++ b/internal/chrome/cdp.go
@@ -928,6 +928,19 @@ func cellQuery(cellSel string) func(context.Context, *cdp.Node) ([]cdp.NodeID, e
 // when its field has no box lets the caller's pointer sequence land on the cell,
 // which is what mounts the input. Grids whose inputs are already visible still
 // resolve to the input, so nothing that worked before changes.
+//
+// Candidates are RANKED, not just filtered, because "in this column" is a
+// geometric test and the page has fields outside the grid that happen to share
+// an x-range with a column. Workday's global "Search Workday" box sits above
+// its Enter Time dialog with its centre inside one day column's tolerance;
+// document-order-first picked it (it comes before the grid), it was under the
+// modal overlay, and `fill --by cell "Tue, …"` failed as `occluded` on that one
+// column and no other. So a candidate inside the header's own grid ranks ahead
+// of one outside it, and one whose centre hit-tests to itself ranks ahead of
+// one that is covered; document order breaks ties. Off-grid candidates are kept
+// as the last resort rather than dropped, because some grids split header and
+// body into separate tables and the header's `closest` container then holds no
+// inputs at all.
 const cellLocatorJS = `(() => {
   const col = %[1]s, row = %[2]s;
   const norm = s => (s || "").replace(/\s+/g, " ").trim();
@@ -947,15 +960,27 @@ const cellLocatorJS = `(() => {
     const tr = el.closest("[role=row],tr");
     return tr && has(tr.textContent, row);
   };
+  // Rank: the header's own grid beats the rest of the page; a centre that
+  // hit-tests to the element beats one under an overlay; then document order
+  // (Array.prototype.sort is stable).
+  const grid = hdr.closest("table,[role=grid],[role=treegrid],[role=table]");
+  const inGrid = el => !grid || grid.contains(el);
+  const hitSelf = el => {
+    const r = el.getBoundingClientRect();
+    const at = document.elementFromPoint(r.left + r.width / 2, r.top + r.height / 2);
+    return !!at && (at === el || el.contains(at));
+  };
+  const rank = el => (inGrid(el) ? 0 : 2) + (hitSelf(el) ? 0 : 1);
+  const byRank = list => list.map((el, i) => ({ el, i, r: rank(el) })).sort((a, b) => a.r - b.r || a.i - b.i).map(x => x.el);
   const fields = "input,textarea,select,[contenteditable=true],[role=textbox],[role=spinbutton]";
   // A field with its own box: the original path, and still the preferred one.
-  const direct = [...document.querySelectorAll(fields)]
-    .filter(el => vis(el) && inCol(el) && inRow(el));
+  const direct = byRank([...document.querySelectorAll(fields)]
+    .filter(el => vis(el) && inCol(el) && inRow(el)));
   if (direct.length) return direct[0];
   // Otherwise find the cell by ITS box and hand back whichever of the field or
   // the cell can actually be pointed at.
-  const cells = [...document.querySelectorAll("[role=gridcell],[role=cell],td")]
-    .filter(el => vis(el) && inCol(el) && inRow(el));
+  const cells = byRank([...document.querySelectorAll("[role=gridcell],[role=cell],td")]
+    .filter(el => vis(el) && inCol(el) && inRow(el)));
   for (const cell of cells) {
     const f = cell.querySelector(fields);
     if (f) return vis(f) ? f : cell;
@@ -1324,11 +1349,7 @@ func withDialogResult(res map[string]any, sink *dialogSink) map[string]any {
 // then sends the text as real keystrokes to the focused element.
 func (c *CDP) Type(ctx context.Context, id, selector, text string, q QueryOpts) (map[string]any, error) {
 	core := chromedp.ActionFunc(func(actx context.Context) error {
-		nid, err := resolveNodeReady(actx, selector, q)
-		if err != nil {
-			return err
-		}
-		if err := coordClickNode(actx, nid); err != nil {
+		if err := coordClickSelector(actx, selector, q, 1); err != nil {
 			return err
 		}
 		return chromedp.KeyEvent(text).Do(actx)
@@ -1346,12 +1367,8 @@ func (c *CDP) Type(ctx context.Context, id, selector, text string, q QueryOpts)
 // a timesheet "0" hour cell) to a new value in one call.
 func (c *CDP) Fill(ctx context.Context, id, selector, value string, q QueryOpts) (map[string]any, error) {
 	core := chromedp.ActionFunc(func(actx context.Context) error {
-		nid, err := resolveNodeReady(actx, selector, q)
-		if err != nil {
-			return err
-		}
 		// Triple-click selects all text in the field; typing then replaces it.
-		if err := coordClickNodeN(actx, nid, 3); err != nil {
+		if err := coordClickSelector(actx, selector, q, 3); err != nil {
 			return err
 		}
 		return chromedp.KeyEvent(value).Do(actx)
diff --git a/internal/chrome/cell_test.go b/internal/chrome/cell_test.go
index 46a2662..8498520 100644
--- a/internal/chrome/cell_test.go
+++ b/internal/chrome/cell_test.go
@@ -131,3 +131,151 @@ func TestCellAddressingZeroSizeInput(t *testing.T) {
 		}
 	}
 }
+
+// TestCellAddressingPrefersGridOverOffGridField covers the second shape --by
+// cell met in the wild: a field OUTSIDE the grid whose centre-x happens to fall
+// inside one column's tolerance. Workday's global "Search Workday" box sits
+// above its Enter Time dialog, its centre inside the Tue column's band; being
+// earlier in document order it was picked first, it was under the modal
+// overlay, and `fill --by cell "Tue, …"` failed as `occluded` on that column and
+// no other, in every week.
+//
+// The fixture makes the off-grid input hit-testable (not covered), which turns
+// the old behaviour into the WORSE failure — the value lands in the search box
+// and the grid cell stays 0 — so the assertion is deterministic either way:
+// ranking the header's own grid first is what makes the grid cell win.
+func TestCellAddressingPrefersGridOverOffGridField(t *testing.T) {
+	if testing.Short() {
+		t.Skip("skipping live-Chrome integration in -short mode")
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
+	defer cancel()
+
+	b, err := launch(true, tmpProfile(t), 0)
+	if err != nil {
+		t.Skipf("cannot launch a managed headless Chrome here: %v", err)
+	}
+	defer b.Close()
+
+	// #search is centred over the Tue column (x 310..390 → centre 350) and comes
+	// before the table in document order.
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		fmt.Fprint(w, `<!doctype html><title>OffGrid</title>
+<style>
+  body{margin:0}
+  #search{position:absolute;left:310px;top:8px;width:80px;height:28px}
+  table{position:absolute;left:0;top:80px;border-collapse:collapse}
+  th,td{width:100px;height:32px;padding:0;text-align:center}
+  td input{width:80px;box-sizing:border-box}
+</style>
+<body>
+<input id="search" placeholder="Search">
+<table>
+<thead><tr><th>Task</th><th>Sun, 7/12</th><th>Mon, 7/13</th><th>Tue, 7/14</th></tr></thead>
+<tbody>
+<tr><th>Regular</th><td><input id="r_sun" value="0"></td><td><input id="r_mon" value="0"></td><td><input id="r_tue" value="0"></td></tr>
+</tbody></table></body>`)
+	}))
+	defer srv.Close()
+
+	id := firstTab(ctx, t, b)
+	if _, err := b.Navigate(ctx, id, srv.URL); err != nil {
+		t.Fatalf("Navigate: %v", err)
+	}
+
+	if _, err := b.Fill(ctx, id, "Tue, 7/14", "8", QueryOpts{By: "cell"}); err != nil {
+		t.Fatalf("Fill cell Tue, 7/14: %v", err)
+	}
+	for cellID, want := range map[string]string{"r_tue": "8", "r_sun": "0", "r_mon": "0", "search": ""} {
+		got := evalString(ctx, t, b, id, fmt.Sprintf("document.getElementById('%s').value", cellID))
+		if got != want {
+			t.Errorf("%s = %q, want %q", cellID, got, want)
+		}
+	}
+}
+
+// TestCellAddressingReResolvesReplacedNode covers the third shape --by cell met
+// in the wild: a grid that RE-RENDERS its row after a cell commits. Workday's
+// time grid does this after every hour entry, so the input the next fill
+// resolved a moment earlier is gone by the time it is measured. Polling that
+// node measured 0x0 until the deadline and surfaced as `occluded` — one column
+// in five, every row, with no overlay anywhere to dismiss.
+//
+// The fixture commits on `input`: it covers the row with a "saving" overlay for
+// a beat (so the next fill's first measurement is genuinely occluded and it has
+// to poll), then rebuilds every input in the row and lifts the overlay. The
+// second fill therefore resolves the OLD Tue input, watches it get detached, and
+// must re-resolve to the replacement to succeed.
+func TestCellAddressingReResolvesReplacedNode(t *testing.T) {
+	if testing.Short() {
+		t.Skip("skipping live-Chrome integration in -short mode")
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
+	defer cancel()
+
+	b, err := launch(true, tmpProfile(t), 0)
+	if err != nil {
+		t.Skipf("cannot launch a managed headless Chrome here: %v", err)
+	}
+	defer b.Close()
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		fmt.Fprint(w, `<!doctype html><title>Rerender</title>
+<style>
+  body{margin:0}
+  table{position:absolute;left:0;top:40px;border-collapse:collapse}
+  th,td{width:100px;height:32px;padding:0;text-align:center}
+  td input{width:80px;box-sizing:border-box}
+  #veil{position:absolute;left:0;top:0;width:100vw;height:100vh;background:rgba(0,0,0,.05);display:none}
+</style>
+<body>
+<table>
+<thead><tr><th>Task</th><th>Sun, 7/12</th><th>Mon, 7/13</th><th>Tue, 7/14</th></tr></thead>
+<tbody>
+<tr id="row"><th>Regular</th><td><input id="r_sun" value="0"></td><td><input id="r_mon" value="0"></td><td><input id="r_tue" value="0"></td></tr>
+</tbody></table>
+<div id="veil"></div>
+<script>
+  // Commit = veil the grid, then rebuild the row's inputs (new elements, same
+  // ids and values) and lift the veil — the grid under test's shape.
+  const arm = () => document.querySelectorAll("#row input").forEach(i => i.addEventListener("input", commit, {once: true}));
+  const commit = () => {
+    document.getElementById("veil").style.display = "block";
+    setTimeout(() => {
+      document.querySelectorAll("#row input").forEach(old => {
+        const fresh = document.createElement("input");
+        fresh.id = old.id; fresh.value = old.value;
+        old.replaceWith(fresh);
+      });
+      arm();
+      document.getElementById("veil").style.display = "none";
+    }, 400);
+  };
+  arm();
+</script></body>`)
+	}))
+	defer srv.Close()
+
+	id := firstTab(ctx, t, b)
+	if _, err := b.Navigate(ctx, id, srv.URL); err != nil {
+		t.Fatalf("Navigate: %v", err)
+	}
+
+	if _, err := b.Fill(ctx, id, "Mon, 7/13", "8", QueryOpts{By: "cell"}); err != nil {
+		t.Fatalf("Fill Mon, 7/13: %v", err)
+	}
+	// Straight into the next cell while the row is mid-commit. Bounded so the
+	// failure mode (polling a detached node until the deadline) fails the test
+	// in seconds, not the suite's minute.
+	fctx, fcancel := context.WithTimeout(ctx, 8*time.Second)
+	defer fcancel()
+	if _, err := b.Fill(fctx, id, "Tue, 7/14", "8", QueryOpts{By: "cell"}); err != nil {
+		t.Fatalf("Fill Tue, 7/14 across the row re-render: %v", err)
+	}
+	for cellID, want := range map[string]string{"r_mon": "8", "r_tue": "8", "r_sun": "0"} {
+		got := evalString(ctx, t, b, id, fmt.Sprintf("document.getElementById('%s').value", cellID))
+		if got != want {
+			t.Errorf("%s = %q, want %q", cellID, got, want)
+		}
+	}
+}
diff --git a/internal/chrome/geometry.go b/internal/chrome/geometry.go
index 6bda07c..f7d5cac 100644
--- a/internal/chrome/geometry.go
+++ b/internal/chrome/geometry.go
@@ -45,12 +45,24 @@ type nodeBox struct {
 	// Occluded means the aim point resolved to something else (an overlay, a
 	// covering panel). Reported rather than fatal for reads.
 	Occluded bool `json:"occluded"`
+	// Detached means the element is no longer in the document: the page swapped
+	// it out (a grid re-rendering its row after a commit) between resolution and
+	// this measurement. A detached node has no geometry and never will again, so
+	// waiting on it is pointless — the caller must re-resolve.
+	Detached bool `json:"detached"`
+	// At describes what elementFromPoint found at the aim point when it was NOT
+	// this element — the evidence behind Occluded. Nil when it was this element,
+	// or when there was no box to test.
+	At map[string]any `json:"at,omitempty"`
 }
 
 // axBoxCoreJS measures `this` and hit-tests its centre. It is a statement list
 // spliced into a function body, so both variants below share every line of the
 // measurement and differ only in what happens before it.
 const axBoxCoreJS = `
+  if (!this.isConnected) {
+    return { ok: false, x: 0, y: 0, cx: 0, cy: 0, w: 0, h: 0, occluded: false, detached: true };
+  }
   const r = this.getBoundingClientRect();
   if (r.width < 1 || r.height < 1) {
     return { ok: false, x: 0, y: 0, cx: 0, cy: 0, w: r.width, h: r.height, occluded: false };
@@ -60,7 +72,12 @@ const axBoxCoreJS = `
   const cy = Math.max(0, Math.min(Math.round(ty), window.innerHeight - 1));
   const at = document.elementFromPoint(cx, cy);
   const hit = !!at && (at === this || this.contains(at));
-  return { ok: hit, x: cx, y: cy, cx: tx, cy: ty, w: r.width, h: r.height, occluded: !hit };
+  const desc = (!hit && at) ? {
+    tag: at.tagName, id: at.id || undefined,
+    role: at.getAttribute("role") || undefined,
+    name: (at.getAttribute("aria-label") || at.getAttribute("data-automation-id") || "").trim() || undefined,
+  } : undefined;
+  return { ok: hit, x: cx, y: cy, cx: tx, cy: ty, w: r.width, h: r.height, occluded: !hit, at: desc };
 `
 
 // nodeCoordJS scrolls the element into view, then measures — the pointer path.
diff --git a/internal/chrome/key.go b/internal/chrome/key.go
index 3fb19f9..1785ee5 100644
--- a/internal/chrome/key.go
+++ b/internal/chrome/key.go
@@ -40,11 +40,7 @@ func (c *CDP) Key(ctx context.Context, id, selector string, keys []KeyStroke, op
 
 	core := chromedp.ActionFunc(func(actx context.Context) error {
 		if selector != "" {
-			nid, err := resolveNodeReady(actx, selector, opts.Query)
-			if err != nil {
-				return err
-			}
-			if err := coordClickNode(actx, nid); err != nil {
+			if err := coordClickSelector(actx, selector, opts.Query, 1); err != nil {
 				return err
 			}
 		}
diff --git a/internal/chrome/pointer.go b/internal/chrome/pointer.go
index 4db9173..8b7212b 100644
--- a/internal/chrome/pointer.go
+++ b/internal/chrome/pointer.go
@@ -37,6 +37,9 @@ func errIs(err, target error) bool {
 // IsOccluded reports whether err is ErrOccluded.
 func IsOccluded(err error) bool { return errIs(err, ErrOccluded) }
 
+// IsDetached reports whether err is ErrDetached.
+func IsDetached(err error) bool { return errIs(err, ErrDetached) }
+
 // Pointer dispatches one pointer gesture — click, hover, double-click,
 // right-click, or drag — at an element's live, occlusion-verified centre.
 //
@@ -149,11 +152,7 @@ func dragDestination(ctx context.Context, x, y float64, opts PointerOpts, gate *
 	if opts.To == "" {
 		return x + opts.Dx, y + opts.Dy, nil
 	}
-	nid, err := resolveNodeReady(ctx, opts.To, opts.ToQuery)
-	if err != nil {
-		return 0, 0, err
-	}
-	return settledNodePoint(ctx, nid)
+	return settledPointFor(ctx, opts.To, opts.ToQuery)
 }
 
 // dragResult builds the drag envelope payload: both endpoints, the step count
@@ -287,11 +286,7 @@ func pointerOrigin(ctx context.Context, selector string, opts PointerOpts, gate
 		}
 		return opts.At.X, opts.At.Y, hit, nil
 	}
-	nid, err := resolveNodeReady(ctx, selector, opts.Query)
-	if err != nil {
-		return 0, 0, nil, err
-	}
-	x, y, err = settledNodePoint(ctx, nid)
+	x, y, err = settledPointFor(ctx, selector, opts.Query)
 	return x, y, nil, err
 }
 
diff --git a/internal/chrome/pointer_test.go b/internal/chrome/pointer_test.go
index 2241794..ee7c969 100644
--- a/internal/chrome/pointer_test.go
+++ b/internal/chrome/pointer_test.go
@@ -8,6 +8,7 @@ package chrome
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"net/http"
 	"net/http/httptest"
@@ -536,3 +537,42 @@ func TestOccludedSurvivesDeadlineDuringGeometryRead(t *testing.T) {
 		}
 	}
 }
+
+// The occluded error carries its evidence in the MESSAGE (errors cross the daemon
+// as strings), while still matching IsOccluded — so both the human and the agent
+// learn what sat on top without re-running under instrumentation.
+func TestOccludedErrorMessage(t *testing.T) {
+	t.Parallel()
+	cases := map[string]struct {
+		err  error
+		want string
+	}{
+		"no box": {
+			err:  &OccludedError{},
+			want: "element has no settled, unoccluded clickable centre; it measured 0x0 (no box to click)",
+		},
+		"covered by an overlay": {
+			err:  &OccludedError{CoveredBy: map[string]any{"tag": "DIV", "id": "", "name": "modalOverlay"}},
+			want: `element has no settled, unoccluded clickable centre; its centre is covered by DIV name="modalOverlay"`,
+		},
+		"covered by an identified element": {
+			err:  &OccludedError{CoveredBy: map[string]any{"tag": "INPUT", "id": "q", "role": "textbox"}},
+			want: `element has no settled, unoccluded clickable centre; its centre is covered by INPUT#q role="textbox"`,
+		},
+	}
+	for name, tc := range cases {
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+			if got := tc.err.Error(); got != tc.want {
+				t.Errorf("Error() = %q, want %q", got, tc.want)
+			}
+			if !IsOccluded(tc.err) {
+				t.Errorf("IsOccluded(%v) = false, want true", tc.err)
+			}
+			// And after a trip through the daemon, where only the string survives.
+			if !IsOccluded(errors.New(tc.err.Error())) {
+				t.Errorf("IsOccluded(string-only copy) = false, want true")
+			}
+		})
+	}
+}
diff --git a/internal/chrome/select.go b/internal/chrome/select.go
index 65f35ab..32c7a7a 100644
--- a/internal/chrome/select.go
+++ b/internal/chrome/select.go
@@ -5,6 +5,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"strconv"
 	"strings"
 	"time"
 
@@ -238,30 +239,18 @@ func resolveNodeReady(ctx context.Context, selector string, q QueryOpts) (cdp.No
 	return nodes[0].NodeID, nil
 }
 
-// coordClickNode clicks a resolved node at its live, occlusion-verified centre via
-// a coordinate pointer sequence. Unlike chromedp's node-click it computes geometry
-// in JS (getBoundingClientRect / elementFromPoint work even when the tab is
-// hidden) and dispatches Input events — so it lands on a background/inactive tab
-// (after bringToFront) where a box-model node-click would poll until it times out.
-// It waits for the centre to settle on the target (or a descendant) — an occluding
-// overlay or a mid-animation element is waited out rather than mis-clicked.
-func coordClickNode(ctx context.Context, nid cdp.NodeID) error {
-	return coordClickNodeN(ctx, nid, 1)
-}
-
-// coordClickNodeN is coordClickNode with a click count (3 = triple-click to
-// select all text in an input).
-func coordClickNodeN(ctx context.Context, nid cdp.NodeID, count int64) error {
-	x, y, err := settledNodePoint(ctx, nid)
-	if err != nil {
-		return err
-	}
-	return coordClickN(ctx, x, y, count)
-}
+// coordClickSelector (below) is the click primitive every verb uses: it owns
+// resolution so it can re-resolve when the page swaps the node out mid-wait. It
+// computes geometry in JS (getBoundingClientRect / elementFromPoint work even
+// when the tab is hidden) and dispatches Input events — so it lands on a
+// background/inactive tab (after bringToFront) where a box-model node-click
+// would poll until it times out. It waits for the centre to settle on the target
+// (or a descendant) — an occluding overlay or a mid-animation element is waited
+// out rather than mis-clicked.
 
 // settledNodePoint waits for a node's centre to settle on the node itself (or a
 // descendant) and returns that viewport point. It is the geometry half of
-// coordClickNode, factored out so every pointer verb — click, hover, dblclick,
+// coordClickSelector, factored out so every pointer verb — click, hover, dblclick,
 // right-click, and both ends of a drag — targets the identical, occlusion-
 // verified point rather than each recomputing its own.
 //
@@ -287,20 +276,26 @@ func settledNodePoint(ctx context.Context, nid cdp.NodeID) (float64, float64, er
 	// the classification stable under load rather than only on an idle machine.
 	var sawOccluded bool
 	var lastErr error
+	var coveredBy map[string]any
 	for {
-		x, y, ok, err := nodeCoord(ctx, obj.ObjectID)
+		b, err := measureNode(ctx, obj.ObjectID, nodeCoordJS)
 		switch {
-		case err == nil && ok:
-			return x, y, nil
+		case err == nil && b.Detached:
+			// The node left the document; no amount of waiting brings it back.
+			// Hand the decision up: a caller holding the selector re-resolves.
+			return 0, 0, ErrDetached
+		case err == nil && b.OK:
+			return b.X, b.Y, nil
 		case err == nil:
 			sawOccluded = true
+			coveredBy = b.At
 		default:
 			lastErr = err
 		}
 		select {
 		case <-ctx.Done():
 			if sawOccluded || lastErr == nil {
-				return 0, 0, ErrOccluded
+				return 0, 0, &OccludedError{CoveredBy: coveredBy}
 			}
 			return 0, 0, lastErr
 		case <-t.C:
@@ -308,6 +303,39 @@ func settledNodePoint(ctx context.Context, nid cdp.NodeID) (float64, float64, er
 	}
 }
 
+// OccludedError is ErrOccluded carrying the evidence: what elementFromPoint
+// found at the element's centre on the last clean measurement. A caller that
+// sees `occluded: true` next needs to know WHAT is on top — an app overlay to
+// dismiss, a tooltip anchored on the cell it just edited, or nothing at all
+// (the element measured 0x0) — and without this it has to reproduce the failure
+// under instrumentation to find out. The evidence rides in the MESSAGE, not a
+// structured field, because errors cross the daemon RPC as strings and the
+// envelope must read the same on both paths; the message still starts with
+// ErrOccluded's text, so IsOccluded keeps matching.
+type OccludedError struct {
+	// CoveredBy describes the element under the centre (tag, id, role, name as
+	// available). Nil when the element had no box to test.
+	CoveredBy map[string]any
+}
+
+func (e *OccludedError) Error() string {
+	if e.CoveredBy == nil {
+		return ErrOccluded.Error() + "; it measured 0x0 (no box to click)"
+	}
+	desc := fmt.Sprint(e.CoveredBy["tag"])
+	if id, _ := e.CoveredBy["id"].(string); id != "" {
+		desc += "#" + id
+	}
+	for _, k := range []string{"role", "name"} {
+		if v, _ := e.CoveredBy[k].(string); v != "" {
+			desc += " " + k + "=" + strconv.Quote(v)
+		}
+	}
+	return ErrOccluded.Error() + "; its centre is covered by " + desc
+}
+
+func (e *OccludedError) Unwrap() error { return ErrOccluded }
+
 // ErrOccluded reports that an element resolved but never presented an unoccluded
 // centre — it is covered by an overlay, or it never stopped animating. Pointer
 // verbs surface it as `occluded: true` in the error details, so a caller can tell
@@ -315,14 +343,54 @@ func settledNodePoint(ctx context.Context, nid cdp.NodeID) (float64, float64, er
 // errors.Is at call sites.
 var ErrOccluded = errors.New("element has no settled, unoccluded clickable centre")
 
-// nodeCoord returns the element's clamped centre and whether that point is
-// hit-testable on the element (or a descendant) — i.e. not occluded.
-func nodeCoord(ctx context.Context, objID runtime.RemoteObjectID) (float64, float64, bool, error) {
-	b, err := measureNode(ctx, objID, nodeCoordJS)
+// ErrDetached reports that the element a selector resolved to was removed from
+// the document before its centre settled — the page re-rendered it (a grid
+// swapping out its row's inputs after a neighbouring cell commits). Verbs that
+// hold the selector re-resolve on this; it only reaches a caller when the
+// replacement never settled either, and then it is a timeout with `detached:
+// true`, so the caller knows the page churned rather than covered the element.
+var ErrDetached = errors.New("element was replaced by the page before its centre settled (timeout waiting for the replacement)")
+
+// settledPointFor is resolveNodeReady + settledNodePoint with one addition: when
+// the resolved node is detached mid-wait, it re-resolves the selector and waits
+// on the replacement, until the context expires.
+//
+// This is what a grid that re-renders after a commit needs. Workday's time grid
+// rebuilds the row's inputs when a cell's edit commits (their ids change), so a
+// node the NEXT fill resolved a moment earlier can be gone by the time it is
+// measured. Polling a detached node measured 0x0 until the deadline and
+// surfaced as `occluded`, sending callers after an overlay that did not exist —
+// with the wait bounded by the caller's timeout and no way to tell it apart from
+// a real cover. Re-resolving costs one extra query and only runs on detachment.
+func settledPointFor(ctx context.Context, selector string, q QueryOpts) (float64, float64, error) {
+	t := time.NewTicker(100 * time.Millisecond)
+	defer t.Stop()
+	for {
+		nid, err := resolveNodeReady(ctx, selector, q)
+		if err != nil {
+			return 0, 0, err
+		}
+		x, y, err := settledNodePoint(ctx, nid)
+		if !errors.Is(err, ErrDetached) {
+			return x, y, err
+		}
+		select {
+		case <-ctx.Done():
+			return 0, 0, ErrDetached
+		case <-t.C:
+		}
+	}
+}
+
+// coordClickSelector resolves selector to a settled, unoccluded centre — re-
+// resolving if the page swaps the node out while it waits — and clicks there
+// count times.
+func coordClickSelector(ctx context.Context, selector string, q QueryOpts, count int64) error {
+	x, y, err := settledPointFor(ctx, selector, q)
 	if err != nil {
-		return 0, 0, false, err
+		return err
 	}
-	return b.X, b.Y, b.OK, nil
+	return coordClickN(ctx, x, y, count)
 }
 
 // locateResult is the coordinate + occlusion verdict returned by the JS option
diff --git a/internal/cli/commands.go b/internal/cli/commands.go
index daf214e..7ea2d91 100644
--- a/internal/cli/commands.go
+++ b/internal/cli/commands.go
@@ -107,6 +107,14 @@ func (a *App) classifyWithTabHint(b chrome.Browser, id string, err error) (strin
 	if chrome.IsOccluded(err) {
 		return result.CodeTargetTimeout, err.Error(), map[string]any{"occluded": true}
 	}
+	// The page replaced the element while we waited on it and the replacement
+	// never settled before the deadline. Also a timeout, but the fix is
+	// different again: the page is churning (a grid re-rendering after a
+	// commit), so wait for it to settle (`wait --stable`) rather than dismiss
+	// an overlay or change a selector.
+	if chrome.IsDetached(err) {
+		return result.CodeTargetTimeout, err.Error(), map[string]any{"detached": true}
+	}
 	// A coordinate outside the viewport is its own failure: the caller named a
 	// PLACE that does not exist on this page, which is a different fix from a
 	// selector that did not resolve. The viewport goes in the details so an
diff --git a/skills/drive-chrome-cdp/SKILL.md b/skills/drive-chrome-cdp/SKILL.md
index 44443a6..c28d452 100644
--- a/skills/drive-chrome-cdp/SKILL.md
+++ b/skills/drive-chrome-cdp/SKILL.md
@@ -39,6 +39,8 @@ Because it drives the real profile, live logins are reused: **type no credential
    If it runs out you get exit 3 with `error.code: consent_pending`; the recovery is to click Allow and retry, not to restart Chrome.
    Do not retry in a loop while a prompt is pending: a retry started within a few seconds of a `consent_pending` inherits that answer rather than asking again, and one started later raises a second dialog at a browser that is already holding one.
    Launching Chrome with `--remote-debugging-port=9222` skips the prompt entirely — prefer recommending that.
+4. **A daemon that lost Chrome fails every command instantly** with `connection_failed: context canceled` while `chrome-cdp doctor` still says `ready` and `daemon status` shows `connected: false`.
+   That is a stale daemon, not a Chrome problem: `chrome-cdp daemon stop && chrome-cdp daemon start`, then retry — the fresh attach may raise the consent prompt once on the `chrome://inspect` path.
 
 ## The loop
 
@@ -112,6 +114,7 @@ The action verbs, beyond `click`/`type`/`fill`/`select`:
   Calling `type "" "text"` fails with a raw `cdp_error: DOM Error while querying (-32000)` rather than a usage error, so there is no way to type literal text into just the focused element.
   When only focus is available, drive it with `key` (digits and letters are valid key names) or address the element once it becomes focusable.
   A sequence runs left to right: `key "End shift+Home Backspace"` empties the focused field.
+  Inside a dirty dialog `Escape` is not free: apps like Workday answer it with an in-page "Discard Changes?" (`Continue` keeps the data, `Discard` throws it away), so read `snap.alerts` after an Escape rather than assuming a transient popover closed.
   `--repeat N` (1–100) and `--delay` for apps that debounce.
   An unknown key name is a usage error, never typed out letter by letter — use `type` for literal text.
 - **`hover <selector>`** — reveal a row's action buttons, a nav flyout, or a tooltip that only renders on `mouseover`.
@@ -133,6 +136,8 @@ Selector syntax is chosen with `--by`:
 - **`--by ref "e<id>"`** — act on the exact element a prior `snap` reported, without re-resolving by name (the ref is stable for the document's lifetime).
 - **`--by cell "[row|]column header"`** — resolve the editable input in a grid cell by its column header (and optional row header): `fill --by cell "Mon, 7/13" "8"`.
   Kills mapping grid inputs by coordinate; use `"Regular|Mon, 7/13"` to disambiguate a row in a multi-row grid.
+  Candidates are ranked, not just filtered: an input inside the header's own grid beats one elsewhere on the page that merely shares the column's x-range (an app's global search box above a dialog), and one whose centre hit-tests to itself beats one under an overlay — so a whole-row fill no longer fails `occluded` on the one column a stray off-grid field overlaps.
+  If a cell still resists, read the input's DOM id with `eval` and `fill '[id="…"]'` it — the read-back (`value --all`) is what proves the row, either way.
 - **`--by label "<visible label text>"`** — resolve a **form control** (input/select/textarea) by the label text shown next to it, for forms whose labels aren't wired to the control (no `aria-label`, no `<label for>` — e.g. a native `<select>` with a sibling `<span>` label).
   `select --by label "Activity Category" "…"`, `fill --by label "Notes" "…"`.
   Resolves via `querySelector`, so it isn't a11y-throttled on a hidden tab.
@@ -168,6 +173,8 @@ Two consequences worth knowing:
 `--by name` also falls back to a DOM accessible-name match on a hidden tab, so it often still works — but **`--by css` is the reliable choice when driving a background tab you can't foreground.**
 
 An element that resolves but is covered by an overlay now fails as `target_timeout` with **`occluded: true`**, distinct from "no such element" — dismiss whatever is on top (often `chrome-cdp key Escape`) rather than rewriting a selector that was already correct.
+The message names the cover (`its centre is covered by DIV name="modalOverlay"`) or says the element measured 0x0, so read it before choosing between "dismiss", "wait", and "re-address".
+A page that swaps the element out mid-wait (a grid re-rendering its row after a commit) is re-resolved automatically; a `detached: true` timeout means even the replacement never settled — `wait --stable`, then retry.
 
 ### `select` — prompt / combobox / cascade widgets
 

From 67f30bd54eb2a0286daf3a35f060d6a8e38fef0e Mon Sep 17 00:00:00 2001
From: Sanket Sudake <sanketsudake@gmail.com>
Date: Sun, 16 Aug 2026 22:55:18 +0530
Subject: [PATCH 2/2] feat: key reports focused_id, the DOM id of what has
 focus after the press
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`focused` names the focused element by role and accessible name, which is
`textbox ""` for every input in a grid — so a stroke that followed a
coordinate click into the wrong cell was invisible in the envelope and
only showed up in a later value read-back (it did, on a live timesheet:
an `8` typed into Sunday instead of Tuesday).

Add `focused_id`: `document.activeElement.id` when the element has one,
read best-effort like `focused` and omitted otherwise. Additive field, no
change to existing shape.
---
 docs/cli-reference.md            |  1 +
 internal/chrome/key.go           | 22 ++++++++++++++++++++++
 internal/chrome/keys_test.go     |  5 +++++
 skills/drive-chrome-cdp/SKILL.md |  1 +
 4 files changed, 29 insertions(+)

diff --git a/docs/cli-reference.md b/docs/cli-reference.md
index 8ae5364..56b11c4 100644
--- a/docs/cli-reference.md
+++ b/docs/cli-reference.md
@@ -310,6 +310,7 @@ If the page replaces the element while a verb waits on it (a grid re-rendering i
 | `--delay <dur>` | pause between repeats, for apps that debounce |
 
 `cmd` maps to Meta on every platform — the *page* decides which modifier it listens for, so the CLI never rewrites `cmd` to `ctrl` for you.
+The result reports `focused` (role and accessible name of what has focus after the press) and, when that element has one, `focused_id` (its DOM id) — the disambiguator for grids whose inputs all read as `textbox ""`, so a stroke that landed in the wrong cell shows in the envelope rather than only in a later value read-back.
 `shift+<character>` presses the character that key actually produces, so `shift+a` is the same press as `A` (and `shift+1` is `!`) rather than a lowercase `a` with a Shift bit set.
 An unknown key name is a `usage` error rather than being typed as literal characters.
 
diff --git a/internal/chrome/key.go b/internal/chrome/key.go
index 1785ee5..81a5d19 100644
--- a/internal/chrome/key.go
+++ b/internal/chrome/key.go
@@ -70,6 +70,9 @@ func (c *CDP) Key(ctx context.Context, id, selector string, keys []KeyStroke, op
 	if f := c.focusedDesc(ctx, id); f != "" {
 		res["focused"] = f
 	}
+	if fid := c.focusedID(ctx, id); fid != "" {
+		res["focused_id"] = fid
+	}
 	return withDialogResult(res, sink), nil
 }
 
@@ -170,6 +173,25 @@ func unmodifiedText(k KeyStroke) string {
 // the FIRST node carrying the focused state, and the document root carries it
 // whenever the window has focus — which bringToFront has just arranged. The
 // useful answer is the element inside the document, which appears later.
+// focusedID is the DOM id of the element that has focus after the press, when
+// it has one — the disambiguator `focused` lacks. Grid cells and other unlabelled
+// inputs all read as `textbox ""` in the accessibility tree, so a stroke that
+// landed in the wrong cell of a row is invisible in `focused` and only shows up
+// in the value read-back; a page that gives its inputs ids (Workday's time grid
+// does) makes the target checkable straight from the envelope. Best-effort like
+// `focused`: any failure, or an element with no id, omits the field.
+func (c *CDP) focusedID(ctx context.Context, id string) string {
+	fctx, cancel := context.WithTimeout(ctx, focusedReadTimeout)
+	defer cancel()
+	var fid string
+	err := c.run(fctx, id, chromedp.Evaluate(
+		`(() => { const a = document.activeElement; return a && a !== document.body ? (a.id || "") : ""; })()`, &fid))
+	if err != nil {
+		return ""
+	}
+	return fid
+}
+
 func (c *CDP) focusedDesc(ctx context.Context, id string) string {
 	fctx, cancel := context.WithTimeout(ctx, focusedReadTimeout)
 	defer cancel()
diff --git a/internal/chrome/keys_test.go b/internal/chrome/keys_test.go
index a090692..39484a6 100644
--- a/internal/chrome/keys_test.go
+++ b/internal/chrome/keys_test.go
@@ -457,6 +457,11 @@ func TestKeyLive(t *testing.T) {
 		} else if !strings.Contains(f, "textbox") || !strings.Contains(f, "Field") {
 			t.Errorf("focused = %q, want it to describe the focused textbox", f)
 		}
+		// focused_id names the element by DOM id — the disambiguator for grids
+		// whose inputs all read as `textbox ""`.
+		if fid, _ := res["focused_id"].(string); fid != "q" {
+			t.Errorf("focused_id = %q, want %q", fid, "q")
+		}
 		if log := readLog(t); len(log) != 1 || log[0].Key != "a" || log[0].Code != "KeyA" {
 			t.Errorf("keydown log = %+v, want one {key:a, code:KeyA} — a page reading event.code must still see the press", log)
 		}
diff --git a/skills/drive-chrome-cdp/SKILL.md b/skills/drive-chrome-cdp/SKILL.md
index c28d452..857672b 100644
--- a/skills/drive-chrome-cdp/SKILL.md
+++ b/skills/drive-chrome-cdp/SKILL.md
@@ -114,6 +114,7 @@ The action verbs, beyond `click`/`type`/`fill`/`select`:
   Calling `type "" "text"` fails with a raw `cdp_error: DOM Error while querying (-32000)` rather than a usage error, so there is no way to type literal text into just the focused element.
   When only focus is available, drive it with `key` (digits and letters are valid key names) or address the element once it becomes focusable.
   A sequence runs left to right: `key "End shift+Home Backspace"` empties the focused field.
+  The result's `focused` (role + name) and `focused_id` (DOM id, when the element has one) say where the stroke landed — check them after a `key` that follows a coordinate click, since a grid's inputs all read as `textbox ""` and a wrong cell is otherwise invisible until the value read-back.
   Inside a dirty dialog `Escape` is not free: apps like Workday answer it with an in-page "Discard Changes?" (`Continue` keeps the data, `Discard` throws it away), so read `snap.alerts` after an Escape rather than assuming a transient popover closed.
   `--repeat N` (1–100) and `--delay` for apps that debounce.
   An unknown key name is a usage error, never typed out letter by letter — use `type` for literal text.