@deepseek-insight/dsi 0.8.5 → 0.9.0

package/.agents/skills/{dsi-gb-verifier → glass-dsi}/SKILL.md

@@ -1,13 +1,24 @@
 ---
-name: dsi-gb-verifier
-description: Use when asked to test/verify work "live", "on the glass", "headed", or on the real DSI surface — drive the operator's own Glass Browser over its MCP tools (mcp__glass-browser__browser_*), opening a glass panel if none exists or adding a focused tab when one does. Reserved keyword /dsi-gb-verifier.
+name: glass-dsi
+description: Use when asked to test/verify work "live", "on the glass", "headed", or on the real DSI surface — drive the operator's own Glass Browser over its MCP tools (mcp__glass-browser__browser_*), opening a glass panel if none exists or adding a focused tab when one does. Reserved keyword /glass-dsi (legacy alias /dsi-glass still matches).
 ---
 
-# dsi-gb-verifier — verify work on the operator's own Glass Browser
+# glass-dsi — verify work on the operator's own Glass Browser
+
+**Dispatch rule (2026-10-30, the Tab-Juggling RCA):** before any glass work,
+ask — is the surface I must drive the DSI workspace, or some other URL?
+DSI workspace → this skill (the driver hard-requires the DSI tab on :5175).
+Any other URL → the `glass-url` skill; it opens a NEW tab and NEVER touches
+the DSI tab. Do NOT navigate the DSI tab to an external URL and do NOT
+re-run `open` to "recover" — that dance produced a useless DSI tab, a
+strike from the driver, and three tabs where one was needed.
 
 Companion KB: `dev/feature-contract-scenario/glass-browser-verification.md`
 (the why and the wire: CDP, the :9515 in-process brain, the three doors).
-This skill is the DO-path. The one rule above all:
+This skill is the DO-path.
+Reference (raw-CDP DO-path when the MCP tools cannot reach the glass —
+orphaned glasses, stack-trace instrumentation, no-nesting rule):
+`references/cdp-verification.md` in this skill folder. The one rule above all:
 
 **The hands are the browser.** `mcp__glass-browser__browser_*` tools drive
 the SAME headed Chromium the operator's floor panel mirrors (CDP via the
@@ -140,4 +151,45 @@ re-litigate them):**
 Numbers before/after, the gesture that produced them, and the gates that
 passed. Label anything you seeded as seeded. If a step could not run,
 say so — a partial verification is a claim about what RAN, not about
-the feature.
+the feature.
+## Tab-ID grammar (2026-10-28 — glass-tab-ids wave)
+
+Glass prompts and the panel omnibox share ONE parser: src/lib/browser/tab-grammar.ts (`parseTabCommand`, discriminated union) — the both-doors rule; they can never disagree about what a command means. Grammar:
+
+| Input | Meaning |
+|---|---|
+| `glass <url>` | open a new tab to url |
+| `glass <text>` | open a new tab to a web search of text |
+| `reuse tab:N [url]` | focus tab N, optionally navigate |
+| `change [to] tab:N` / `tab:N` | focus tab N |
+| `close tab:N` / `close active` | close that tab / the active tab |
+| `active` | report the focused tab (id + URL) |
+| anything else | chrome fallback — navigate or web search on the active tab |
+
+`Alt+N` on the panel (not a grammar input) focuses the Nth tab by STRIP POSITION before the CDP relay — Alt+0 is the last tab; empty slot is a no-op and the combo never reaches the glass page.
+
+`tab:N` is the registry-owned ordinal rendered on the strip badge (data-testid=browser-tab-ordinal) — the badge IS the prompt ID. Focus polish 2026-10-28: the badge now READS `t{index}:{id}` (the 1-based strip position, the same index Alt+N dispatches on), while PROMPTS still use the `tab:{id}` grammar — the registry is unchanged. Ordinals are never reused after close: a retired/unknown tab:N is an explicit error (404 NO_TARGET), never a silent nearest-match. When verifying live, read the number off the badge and address the tab by it.
+
+
+## Fast path — the driver script (2026-10-29)
+
+The whole discovery dance above is codified in ONE script. Run it FIRST;
+fall back to the manual steps only when it fails:
+
+```sh
+# from the DSI repo root (playwright-core resolves there)
+node .agents/skills/dsi-glass/scripts/glass.mjs open          # resolve port, connect, reuse-or-create the DSI tab
+node .agents/skills/dsi-glass/scripts/glass.mjs type '?adr'   # real keystrokes into the composer
+node .agents/skills/dsi-glass/scripts/glass.mjs strip         # rows / activeIdx / ariaSel / tipCount verdict
+node .agents/skills/dsi-glass/scripts/glass.mjs shot tmp/glass.png
+node .agents/skills/dsi-glass/scripts/glass.mjs eval '1+1'    # arbitrary page.evaluate
+node .agents/skills/dsi-glass/scripts/glass.mjs pages
+```
+
+It caches NOTHING: every run re-resolves the session from
+`GET /api/browser` (rule 3 — a hardcoded port verifies a ghost). On
+failure it prints the manual fallback (operator clicks the Browser chip).
+Complex gestures (mouse drags, multi-step keyboards, instrumentation
+shims) still go through playwright-core by hand per §2–§4 — the script
+covers the connect + common verbs, not every probe.
+

package/.agents/skills/glass-dsi/references/cdp-verification.md

@@ -0,0 +1,132 @@
+# Reference — Driving a Glass Over Raw CDP (the orphaned-glass DO-path)
+
+Companion to SKILL.md. Read when the `mcp__glass-browser__browser_*`
+tools cannot reach the glass you need (brain re-homed, preset entry
+stale) or when you need evidence the MCP tools cannot produce (stack
+traces, per-frame scroll curves, wire-call counts). The KB companion
+(`dev/feature-contract-scenario/glass-browser-verification.md`,
+"2026-10-28 additions II") carries the WHY; this file is the HOW, every
+pattern battle-tested 2026-10-28 on the operator's own glass (port 9400,
+three session ids, one investigation — the floor-steal RCA).
+
+## 0. The rules that outrank every pattern
+
+1. **NO NESTING.** Never open the host DSI inside a glass tab to "drive
+   the GUI". The host GUI's gestures belong to the OPERATOR; you verify
+   effects through the glass CDP and ask the operator to click. (Operator
+   correction 2026-10-28: "do not nest DSI".)
+2. **A re-homed glass is not dead.** `mcpHealth: "down", mcpError:
+   "brain re-homed to a newer glass"` means the MCP tools left — the
+   chromium and its CDP port are still fully alive and still may be the
+   browser the operator's panel mirrors.
+3. **Re-resolve the port every session.** `GET /api/browser` rows carry
+   `port`; the registry cycles whenever the operator re-chips. A
+   hardcoded port verifies a ghost.
+4. **Instrument BEFORE the gesture.** A counter armed after the click
+   proves nothing.
+
+## 1. Resolve the target
+
+```sh
+curl -s http://127.0.0.1:5175/api/browser
+# → {"sessions":[{"id":"…","port":9400,"mcpHealth":"…"}]}
+curl -s http://127.0.0.1:<port>/json/list
+```
+
+Pick the DSI-under-test page: `type === "page"`, URL contains
+`127.0.0.1:5175`. Its `title` is the FOCUSED SESSION's name — DSI sets
+`document.title` to it, so the title flipping IS a focus probe. Ignore
+`browser_ui` rows (Omnibox Popup) and the `data:text/html` placeholder.
+
+## 2. Connect (playwright-core over CDP — real input, real pages)
+
+```js
+import { chromium } from 'playwright-core';
+const browser = await chromium.connectOverCDP('http://127.0.0.1:' + port);
+const page = browser.contexts()[0].pages().find(p => p.url().includes('5175'));
+```
+
+This gives real `locator.click()` gestures (pointerdown included — the
+activation verb) and `page.evaluate` into the live page. Raw-CDP
+alternatives for the same doors: `Runtime.evaluate` (+`userGesture:
+true`), `Input.dispatchMouseEvent/KeyEvent`, `Page.captureScreenshot`.
+
+## 3. Arm the instrumentation (one `page.evaluate`, before acting)
+
+```js
+await page.evaluate(() => {
+  window.__ev = []; window.__sl = [];
+  const vp = document.querySelector('[data-testid=panels-viewport]');
+  // (a) rAF scroll sampler — CDP round-trips miss the smooth-scroll curve
+  let last = vp.scrollLeft;
+  const sample = () => { const s = vp.scrollLeft;
+    if (s !== last) { last = s; window.__sl.push({ t: Math.round(performance.now()), sl: Math.round(s * 10) / 10 }); }
+    requestAnimationFrame(sample); };
+  requestAnimationFrame(sample);
+  const proto = Element.prototype;
+  // (b) scroll watches with STACKS — the stack frame names the guilty component
+  if (!proto.__watched) { proto.__watched = true;
+    const siv = proto.scrollIntoView, sto = proto.scrollTo;
+    proto.scrollIntoView = function (...a) {
+      if (this.closest('[data-testid=panels-viewport]'))
+        window.__ev.push({ t: Math.round(performance.now()), kind: 'scrollIntoView',
+          d: (this.getAttribute?.('data-testid') ?? this.tagName),
+          stack: new Error().stack.split('\n')[2]?.trim() });
+      return siv.apply(this, a); };
+    proto.scrollTo = function (...a) {
+      if (this.matches?.('[data-testid=panels-viewport]'))
+        window.__ev.push({ t: Math.round(performance.now()), kind: 'floor.scrollTo', d: JSON.stringify(a[0]) });
+      return sto.apply(this, a); }; }
+  // (c) fetch shim — negative evidence (zero POSTs) kills hypotheses
+  if (!window.__fw) { window.__fw = true; const of_ = window.fetch;
+    window.fetch = function (...a) {
+      const u = String(a[0]);
+      if (u.includes('/viewport') || u.includes('/activate') || u.includes('/tabs'))
+        window.__ev.push({ t: Math.round(performance.now()), kind: 'fetch', d: u.split('/').pop() });
+      return of_.apply(this, a); }; }
+  // (d) selection timestamps
+  new MutationObserver(() => window.__ev.push({ t: Math.round(performance.now()), kind: 'selection' }))
+    .observe(document.querySelector('[data-testid=panels-row]'), { attributes: true, attributeFilter: ['class'], subtree: true });
+});
+```
+
+Notes: arm once (the `__watched`/`__fw` guards) — HMR reloads wipe
+everything and the guards re-arm cleanly; the stack slice `[2]` is the
+first APP frame (skip the wrapper).
+
+## 4. Gesture, then read the verdict
+
+Perform the REAL gesture (`locator.click()` on the panel header), wait
+OUT past at least one poll cadence (the tabs poll is 2000 ms — a 2s wait
+verifies nothing), then:
+
+```js
+const out = await page.evaluate(() => ({
+  sl: document.querySelector('[data-testid=panels-viewport]').scrollLeft,
+  sel: document.querySelector('.panels-row [data-testid=panel-column].selected')
+        ?.getBoundingClientRect().toJSON(),
+  vp:  document.querySelector('[data-testid=panels-viewport]').getBoundingClientRect().toJSON(),
+  ev: window.__ev, samples: window.__sl }));
+```
+
+Verdict = NUMBERS: selected rect fully inside viewport rect? scroll trace
+monotonic (reveal settles) or snapped back (a steal)? which stack frames
+appear? Report before/after pairs and the gates passed; adjectives are not
+verification.
+
+## 5. Geometry facts that bite
+
+- The floor viewport's left edge is NOT page x=0 (the sidebar rail sits
+  left of it) — compare column rects against `panels-viewport`'s OWN
+  rect, never against the page.
+- `getBoundingClientRect` is transform-true (zoom included); `clientWidth`
+  is layout px. At floor zoom ≠ 1 the two disagree — use the rect.
+- A 12px glass resize you did not cause is usually the mirror's
+  viewport-sync, not your gesture — check the fetch shim before claiming it.
+
+## 6. Worked example
+
+The full live trace that convicted the tab-strip floor steal (instrument
+→ gesture → stack frame → fix → re-trace) is in
+`dev/kb/rca/2026-10-28 - RCA — The Tab Chip That Rearranged the Room
+(A Strip's Scroll Walked Into the Floor).md`.

package/.agents/skills/glass-dsi/scripts/_connect.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+/**
+ * _connect.mjs — shared glass connection for the glass-url / glass-dsi drivers.
+ *
+ * EXPORTS (do not guess — this header is the contract, keep it in sync):
+ *   die(msg)                 — print a JSON error and exit 1.
+ *   identityFrom(argv)       — caller identity, first-wins: --owner-session
+ *                              flag > GLASS_OWNER_SESSION > DSH_SESSION_ID
+ *                              (the harness built-in is CONDITIONAL —
+ *                              dsh-shell-env index.js:89 injects it only
+ *                              when the execution carries an agent binding,
+ *                              RCA 2026-10-30 "the session id is gone" —
+ *                              so explicit beats inherited).
+ *   pickSession(sessions, envId)
+ *                            — PURE D7 resolver (unit-tested): match the
+ *                              caller's identity to ownerSessionId. NEVER
+ *                              registry index (ADR-0045 amendment 3).
+ *                              Returns { session } | { session:null, error }.
+ *   connect()                — GET /api/browser (the ONLY source of truth,
+ *                              ADR-0030) → pickSession → CDP connect →
+ *                              { session, browser, ctx }. Dies LOUDLY on
+ *                              ambiguity; degraded single-session runs print
+ *                              a warning on stderr and proceed.
+ *   pick(ctx, substr)        — page whose URL contains substr; NEVER
+ *                              positional "newest" among foreign tabs (D2).
+ */
+import { chromium } from 'playwright-core';
+
+const DSI = 'http://127.0.0.1:5175';
+
+export function die(msg) {
+  console.error(JSON.stringify({ error: msg, fallback: 'SKILL.md Step 1 — ask the OPERATOR to click the Browser chip IN THE RIGHT CONVERSATION, then catch the session via GET /api/browser. If DSH_SESSION_ID is absent from env, pass --owner-session <id> (the session id you already know from context).' }));
+  process.exit(1);
+}
+
+export function identityFrom(argv) {
+  const flag = argv.indexOf('--owner-session');
+  if (flag !== -1 && argv[flag + 1]) return argv[flag + 1];
+  if (process.env.GLASS_OWNER_SESSION) return process.env.GLASS_OWNER_SESSION;
+  if (process.env.DSH_SESSION_ID) return process.env.DSH_SESSION_ID;
+  return undefined;
+}
+
+export function pickSession(sessions, envId) {
+  const list = sessions ?? [];
+  if (envId) {
+    const mine = list.filter((s) => (s.ownerSessionId ?? null) === envId);
+    if (mine.length === 1) return { session: mine[0], degraded: false };
+    if (mine.length > 1) {
+      const newest = [...mine].sort((a, b) => String(a.createdAt ?? '').localeCompare(String(b.createdAt ?? ''))).at(-1);
+      return { session: newest, degraded: false, note: 'multiple glasses owned by ' + envId + ' — newest wins' };
+    }
+    if (list.length === 1 && (list[0].ownerSessionId ?? null) === null) {
+      return { session: list[0], degraded: true, note: 'legacy session without ownerSessionId — degraded match' };
+    }
+    return { session: null, error: 'no glass owned by ' + envId + ' — your glass is dead or never summoned (click the Browser chip in THIS conversation); live glasses belong to other conversations and are untouchable (D7)' };
+  }
+  if (list.length === 1) {
+    return { session: list[0], degraded: true, note: 'no explicit identity in env — degraded single-session resolution' };
+  }
+  return { session: null, error: 'multiple live glasses and no explicit identity — pass --owner-session <id> (or GLASS_OWNER_SESSION) from the session id you already know; refusing to guess (D7)' };
+}
+
+export async function connect() {
+  let reg;
+  try {
+    reg = await (await fetch(DSI + '/api/browser')).json();
+  } catch {
+    die('DSI dev server not reachable on 5175 — floor not up (dsi dsh --sync --dev --playwright-mcp)');
+  }
+  const { session, degraded, note, error } = pickSession(reg.sessions, identityFrom(process.argv));
+  if (!session) die(error ?? 'no glass session resolved — operator must click the Browser chip');
+  if (degraded || note) console.error(JSON.stringify({ warn: note ?? 'degraded', sessionId: session.id }));
+  const browser = await chromium.connectOverCDP('http://127.0.0.1:' + session.port).catch(() => null);
+  if (!browser) die('CDP connect failed on port ' + session.port);
+  return { session, browser, ctx: browser.contexts()[0] };
+}
+
+export function pick(ctx, substr) {
+  return ctx.pages().find((p) => p.url().includes(substr));
+}

package/.agents/skills/glass-dsi/scripts/glass-url.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+/**
+ * glass-url.mjs — the dsi-glass URL path (2026-10-29).
+ *
+ * For driving NON-DSI surfaces (YouTube, docs, anything) on the operator's
+ * glass. Never touches the DSI tab: open <url> adds a NEW tab last and
+ * focuses it (tab-grammar: glass <url>); the other verbs run against the
+ * NEWEST tab, whatever it is. The DSI server is still needed — it owns the
+ * session registry (see _connect.mjs).
+ *
+ * Usage (run from the DSI repo root so playwright-core resolves):
+ *   node .agents/skills/dsi-glass/scripts/glass-url.mjs open <url>
+ *   node …/glass-url.mjs pages
+ *   node …/glass-url.mjs eval '<js>'     # async page.evaluate on newest tab
+ *   node …/glass-url.mjs shot <file.png> # screenshot of newest tab
+ */
+import { connect, die } from './_connect.mjs';
+
+const [cmd, ...args] = process.argv.slice(2);
+const { session, browser, ctx } = await connect();
+
+// newest real tab = last http(s) page; CDP page order is not insertion order
+// and the glass placeholder (data:text/html,<title>Glass Browser…) can sit last
+const newest = () => {
+  const pages = ctx.pages().filter((p) => p.url().startsWith('http'));
+  return pages[pages.length - 1];
+};
+
+if (cmd === 'open') {
+  const url = args[0];
+  if (!url) die('open needs a url');
+  const page = await ctx.newPage();
+  await page.goto(url, { waitUntil: 'domcontentloaded' }).catch((e) => die('goto failed: ' + e.message));
+  await page.waitForTimeout(1500); // let the SPA settle
+  console.log(JSON.stringify({ ok: true, sessionId: session.id, url: page.url(), title: await page.title() }));
+} else if (cmd === 'pages') {
+  console.log(JSON.stringify(await Promise.all(ctx.pages().map(async (p) => ({ url: p.url(), title: await p.title() }))), null, 1));
+} else if (cmd === 'eval') {
+  if (!args[0]) die('eval needs a js expression');
+  console.log(JSON.stringify(await newest().evaluate(async (src) => await eval(src), args[0]), null, 1));
+} else if (cmd === 'shot') {
+  const file = args[0] ?? 'tmp/glass-url-shot.png';
+  await newest().screenshot({ path: file });
+  console.log(JSON.stringify({ ok: true, file }));
+} else {
+  die('unknown command: ' + cmd);
+}
+await browser.close();

package/.agents/skills/glass-dsi/scripts/glass.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/**
+ * glass.mjs — the dsi-glass fast path (2026-10-29).
+ *
+ * ONE command replaces the discovery dance: port resolve (:5175 health →
+ * GET /api/browser → session port → /json/list → playwright-core
+ * connectOverCDP → reuse-or-create the DSI tab). The browser-session
+ * registry stays the ONLY source of truth — this script caches nothing
+ * (skill rule 3: a hardcoded port verifies a ghost).
+ *
+ * Usage (run from the DSI repo root so playwright-core resolves):
+ *   node .agents/skills/dsi-glass/scripts/glass.mjs open [url]
+ *   node …/glass.mjs eval '<js>'          # async page.evaluate, JSON out
+ *   node …/glass.mjs type '<text>'        # real keystrokes into the composer
+ *   node …/glass.mjs shot <file.png>      # viewport screenshot
+ *   node …/glass.mjs strip                # suggest-strip verdict (rows,
+ *                                         #   activeIdx, ariaSel, tipCount)
+ *   node …/glass.mjs pages                # list glass pages (url + title)
+ *
+ * On any failure it prints the manual fallback hint (SKILL.md Step 1 —
+ * the operator clicks the Browser chip; agents never open sessions).
+ */
+import { connect, die } from './_connect.mjs';
+
+const DSI = 'http://127.0.0.1:5175';
+const [cmd, ...args] = process.argv.slice(2);
+
+const { session, browser, ctx } = await connect();
+
+let page = ctx.pages().find((p) => p.url().includes('5175'));
+if (cmd === 'open') {
+  if (!page) {
+    page = await ctx.newPage();
+    await page.goto(args[0] ?? DSI, { waitUntil: 'domcontentloaded' }).catch(() => {});
+  } else if (args[0] && args[0] !== page.url()) {
+    await page.goto(args[0], { waitUntil: 'domcontentloaded' }).catch(() => {});
+  }
+  await page.waitForSelector('body', { timeout: 15000 });
+} else if (!page) {
+  die('no DSI tab in the glass — run: glass.mjs open');
+}
+
+if (cmd === 'open') {
+  await page.waitForTimeout(1500); // let the SPA settle
+  console.log(JSON.stringify({ ok: true, sessionId: session.id, port: session.port, url: page.url(), title: await page.title() }));
+} else if (cmd === 'pages') {
+  console.log(JSON.stringify(await Promise.all(ctx.pages().map(async (p) => ({ url: p.url(), title: await p.title() }))), null, 1));
+} else if (cmd === 'eval') {
+  if (!args[0]) die('eval needs a js expression');
+  console.log(JSON.stringify(await page.evaluate(async (src) => await eval(src), args[0]), null, 1));
+} else if (cmd === 'type') {
+  if (!args[0]) die('type needs text');
+  const ta = page.locator('textarea').first();
+  await ta.click();
+  await page.keyboard.press('Meta+a');
+  await page.keyboard.press('Backspace');
+  await page.keyboard.type(args[0], { delay: 60 });
+  await page.waitForTimeout(1000); // debounce (120 ms) + fetch
+  console.log(JSON.stringify({ ok: true, typed: args[0] }));
+} else if (cmd === 'shot') {
+  const file = args[0] ?? 'tmp/glass-shot.png';
+  await page.screenshot({ path: file });
+  console.log(JSON.stringify({ ok: true, file }));
+} else if (cmd === 'strip') {
+  console.log(JSON.stringify(await page.evaluate(() => {
+    const strip = document.querySelector('[data-testid=suggest-strip]');
+    if (!strip) return { strip: false };
+    const chips = [...strip.querySelectorAll(':scope > .strip-chip')];
+    const tips = [...document.body.querySelectorAll(':scope > .strip-tip')];
+    return {
+      strip: true,
+      rows: chips.length,
+      labels: chips.map((c) => c.querySelector('.strip-label')?.textContent?.trim()),
+      activeIdx: chips.findIndex((c) => c.classList.contains('active')),
+      ariaSel: chips.map((c) => c.querySelector('.strip-pick')?.getAttribute('aria-selected')),
+      tipCount: tips.length,
+      tipText: tips[0]?.querySelector('pre')?.textContent?.slice(0, 80) ?? null,
+      taValue: document.querySelector('textarea')?.value
+    };
+  }), null, 1));
+} else {
+  die('unknown command: ' + cmd);
+}
+await browser.close();

package/.agents/skills/glass-url/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: glass-url
+description: Open and drive an ARBITRARY URL (YouTube, docs, any web page) in a NEW tab on the operator's glass browser via CDP — search, click, screenshot, read the page. NOT for verifying DSI work; that is glass-dsi. Reserved keyword /glass-url.
+---
+
+# glass-url — drive an arbitrary URL on the operator's glass
+
+Companion skill: `glass-dsi` (verify DSI work on the glass — the DSI tab,
+the floor mirror, the SSE probe). This skill is the OTHER scenario: the
+target is some web page, and the DSI tab is none of your business.
+
+**The dispatch rule (Tab-Juggling RCA, ADR-0045):** before any glass work
+ask ONE question — is the surface I must drive the DSI workspace, or some
+other URL? DSI workspace → `glass-dsi`. Any other URL → THIS skill.
+Never navigate the DSI tab, never re-run `open` to "recover".
+
+## Environment contract (read before the first command — RCA 2026-10-30)
+
+- **Node lives off the default PATH here** (`~/.local/bin/node` observed
+  2026-10-30). If `node` is not found, resolve it first:
+  `bash -lc "which node"` or check `~/.local/bin`, `/opt/homebrew/bin`.
+- **Run from the DSI repo root** (`~/agentic-ai/deepseek-insight`) so
+  `playwright-core` resolves.
+- **Never hand unquoted JS through a shell** — a stripped quote fails
+  after the round-trip was already spent. Use `eval --b64 <base64>`.
+- **Every ad-hoc driver snippet must `process.exit()`** — a driver that
+  played media once hung its caller for a full 120s timeout.
+- **Script headers are contracts** — `_connect.mjs` exports
+  `die`, `connect`, `pick(ctx, substr)`; do not guess names, read the
+  header; re-read the header in the same edit that changes the code.
+
+## The fast path — glass-url.mjs (one command per intent)
+
+```sh
+# from the DSI repo root (playwright-core resolves there)
+node .agents/skills/glass-url/scripts/glass-url.mjs yt "Dimas Senopati" --play "What's Up" --shot tmp/proof.png
+#   → search + normalized match + open watch tab + unmute/play + double
+#     gate + shot, ONE JSON with every stage, then exits. --play consumes
+#     EVERY term (artist AND title) — put both in it (ADR-0045 D9).
+
+node .agents/skills/glass-url/scripts/glass-url.mjs open <url>    # NEW tab, focused
+node .agents/skills/glass-url/scripts/glass-url.mjs pages         # list tabs
+node .agents/skills/glass-url/scripts/glass-url.mjs eval '<js>'           # newest non-DSI tab
+node .agents/skills/glass-url/scripts/glass-url.mjs eval watch?v= '<js>'  # inline: LAST arg is the js
+node .agents/skills/glass-url/scripts/glass-url.mjs eval --b64 <b64-js> <url-substring>
+    # quote-proof eval; anything left after the payload IS the url-substring
+    # (ADR-0045 D10 — parsed by shape, never positional fallback)
+node .agents/skills/glass-url/scripts/glass-url.mjs shot f.png [url-substring]
+```
+
+"Newest tab" = last http(s) page that is neither the glass placeholder nor
+the DSI tab (:5175). When SEVERAL foreign tabs exist, position lies —
+pass the URL-substring argument (the `yt` verb does this for you).
+Every run re-resolves the session from `GET /api/browser`.
+
+## Recipes
+
+- **Search + play a video:** the `yt` verb IS the recipe (match
+  normalization included: apostrophes/case folded). Only drop to
+  `open` → `eval` when the flow is not search-and-play.
+- **Read a page:** `open` → `eval` extract DOM text/links.
+
+## Rules
+
+1. Always `open` a NEW tab for your target — never reuse a tab you did
+   not create, never close operator tabs.
+2. Never navigate the DSI workspace tab; it belongs to glass-dsi.
+3. Multi-step state (click, type, drag) beyond eval/shot: drop to
+   playwright-core by hand over CDP (import `connect`/`pick` from
+   `.agents/skills/glass-url/scripts/_connect.mjs` — exports listed in
+   its header), same as glass-dsi §2–4.
+4. If `GET /api/browser` has no session: the operator must click the
+   Browser chip first (the one gesture you cannot simulate). Say so and wait.
+5. Verify with gates, not adjectives: a playback gate is `paused:false`
+   plus rising `currentTime`; a navigation gate is the URL/title you
+   expected; finish by asking the operator to confirm they SEE it.
+
+## Identity (2026-10-30, RCA "the session id is gone")
+
+The driver claims YOUR glass by identity, first-wins:
+1. `--owner-session <id>` flag — pass the session id you already know from
+   your context when `DSH_SESSION_ID` is absent (the harness injects it
+   only when the execution carries an agent binding — dsh-shell-env
+   index.js:89 — so its absence is possible and NOT an error).
+2. `GLASS_OWNER_SESSION` env.
+3. `DSH_SESSION_ID` env.
+No identity + several live glasses = loud refusal, never a guess (D7).
+
+## The Stop-Loss Law (2026-10-30, ADR-0045 D11 — a refusal is an answer)
+
+- **NO_MATCH is an answer.** When the yt verb exits `stage:"match"` with a
+  candidate list, REPORT that list and STOP — do not open ad-hoc search
+  tabs, do not re-search with different words, do not drop to open/eval to
+  hand-roll what the verb just refused. The operator decides the next move.
+- **Grammar dies are answers.** A `die` ("no tab matching …", "no
+  non-DSI tab …") ends the investigation, not triggers a workaround hunt.
+  Run `pages` once to re-orient if you must, then report.
+- **Already playing is DONE.** If the media is live on the operator's glass
+  (they say so, or a prior gate passed), the goal is met — report and stop.
+  No follow-up verification, no "one more tab". Verification serves the
+  operator's goal; when the goal is met, the correct next action is WORDS.
+- Every extra tab and round-trip after a refusal is a token burn the
+  operator pays for. (RCA: "The Answer That Bought Another Round".)
+
+## Failure branches (2026-10-30)
+
+- `eval` on a cross-origin page still loading can return empty — wait and
+  re-run; do not conclude "no results".
+- String matching needs normalization (case, apostrophes) or exact titles
+  will NO_MATCH — `yt` normalizes for you.
+- A vite restart empties the registry and kills the Chrome — re-run from
+  the operator's chip click, same as glass-dsi.
+- "Newest non-DSI tab" is positional and CAN pick a sibling foreign tab —
+  select by URL substring (the optional eval/shot argument), not position.
+- Node/git missing from PATH, quoting mangling, guessed flags, and
+  non-exiting drivers each cost a full round-trip: see the environment
+  contract above; they are pre-paid now.

package/.agents/skills/glass-url/scripts/_args.mjs

@@ -0,0 +1,49 @@
+/**
+ * _args.mjs — pure helpers for glass-url.mjs (ADR-0045 Amendment 5, D9 + D10).
+ *
+ * Lives beside _connect.mjs so vitest can pin them without touching CDP
+ * (the driver connects at import; these never do). Exports are a contract:
+ * change them in the same edit that changes glass-url.mjs.
+ */
+
+/**
+ * Title normalization: fold apostrophes, case, and punctuation runs.
+ * @param {string | undefined | null} s
+ * @returns {string}
+ */
+export const norm = (s) => (s || '').toLowerCase().replace(/[\u2019']/g, '').replace(/[^a-z0-9]+/g, ' ').trim();
+
+/**
+ * D10 — the eval grammar is parsed, not positional.
+ * Inline mode:  [substr?] src           — the LAST arg is always the JS source.
+ * b64 mode:     [b64payload, substr?]   — the payload is consumed by the caller
+ *               (it already stripped --b64), so anything LEFT is the substring.
+ * Returns an object with src and substr, undefined where absent.
+ * @param {string[]} rest
+ * @param {{ b64?: boolean } | undefined} [opts]
+ * @returns {{ src: string | undefined, substr: string | undefined }}
+ */
+export function parseEvalArgs(rest, opts) {
+  const b64 = !!(opts && opts.b64);
+  if (b64) {
+    return { src: rest[0], substr: rest.length > 1 ? rest[1] : undefined };
+  }
+  if (rest.length > 1) return { substr: rest[0], src: rest[1] };
+  return { src: rest[0], substr: undefined };
+}
+
+/**
+ * D9 — the play match consumes EVERY play term.
+ * True only when every whitespace-split term of play appears in the
+ * normalized title. An empty or absent play value means no filter (true) —
+ * the yt verb then takes the first result, unchanged behavior.
+ * @param {string} title
+ * @param {string | undefined | null} play
+ * @returns {boolean}
+ */
+export function matchAllTerms(title, play) {
+  const terms = (play || '').split(/\s+/).filter(Boolean);
+  if (!terms.length) return true;
+  const t = norm(title);
+  return terms.every((term) => t.includes(norm(term)));
+}