kaloko 0.21.0 → 0.21.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaloko",
-  "version": "0.21.0",
+  "version": "0.21.2",
   "description": "Your AI agents build; Kaloko walks every screen, puts it on one canvas and records who approved what.",
   "keywords": [
     "qa",

package/skills/kaloko/reference/integrations.md

@@ -102,9 +102,12 @@ kaloko schedule hook <id>       # URL + secret that start the run after a deploy
 - Findings: `GET …/scenarios/<id>/findings` (MCP `list_findings`) groups a
   scenario's open results by check, site, locale and step, with a status
   people set (acknowledged, ignored with a reason) and fixed when no page
-  fails. A scenario may open one Jira / Linear issue per new finding
-  (`PUT …/findings/sync { tracker, min_severity }`, Developer / Tester): at
-  most 20 per run, a comment on big changes, closed when fixed. Switching it
+  fails. A scenario may open one issue per new finding in Jira, Linear,
+  GitHub Issues or Plane (`PUT …/findings/sync { tracker, min_severity,
+  github?, plane?, routes? }`, Developer / Tester; routes send checks or
+  packs to another tracker): at most 20 per run, a comment on big changes,
+  closed when fixed. With `traffic:`, findings and issues carry clicks,
+  impressions and impact. Switching it
   on or ignoring findings is the team's call, not an agent's.
 - Does not work for: native apps, local or private addresses (localhost, IPs,
   `.local`), header credentials, stacks listed by crawl, script or file.

package/src/cli.mjs

@@ -12,7 +12,7 @@ import { startRefs, normalizePurpose, RUN_PURPOSES } from './lib/run-refs.mjs'
 import { gitMeta, projectAndIssue, appVersion } from './lib/git.mjs'
 import { startBrowser, stopBrowser, connectBrowser, currentPage, launchEphemeral, launchWithRetry, consoleLog, allStates, resetSession, acquireWalkLock } from './lib/browser.mjs'
 import { captureStep, captureCrop, captureOptions, acceptDialogs } from './lib/capture.mjs'
-import { observeConsole } from './lib/console.mjs'
+import { observeConsole, pageTarget } from './lib/console.mjs'
 import { mailClient, waitForMessage, recipient, readMessageFile } from './lib/mail.mjs'
 import { newContext, accountFor, gateHeaders, gateOrigins, originMatcher, gateForRequests } from './lib/access.mjs'
 import { configureGate, disposeShared } from './lib/linkcheck.mjs'
@@ -810,7 +810,7 @@ async function exportScenario ({ args, config, root, client }) {
  * Walks a stack step: resolves its pages, then opens and captures each one with the step's criteria and index
  * fields (HTTP status of the main document included). A step script, when given, runs per page with `item`.
  */
-async function walkStack ({ node, locale, page, env, run, scenario, scenarioDir, config, consoleFile, args, keys = null, tag = '', cache = null, gate = null }) {
+async function walkStack ({ node, locale, page, env, run, scenario, scenarioDir, config, consoleFile, consoleBound = null, args, keys = null, tag = '', cache = null, gate = null }) {
   // a rotating sample (items.rotate) remembers between runs how many runs walked it and when each page was checked
   const statePath = (l) => join(run.dir, '..', '.cache', 'stack', scenario.id, `${node.id}.${l}.json`)
   const state = node.items?.rotate ? await rotationState(statePath(locale), run.meta.id) : null
@@ -854,13 +854,17 @@ async function walkStack ({ node, locale, page, env, run, scenario, scenarioDir,
   const streak = failureStreak(5)
   const failed = []; let ok = 0; const checkedNow = []
   const started = Date.now(); let told = started
+  let from = consoleBound?.since(page) || new Date().toISOString()
   try {
     for (const [i, item] of chosen.entries()) {
       if (streak.stopped('stack')) { failed.push(`${item.id}: not walked after repeated failures`); continue }
       status = null
-      const since = Date.now()
+      // the console counts from the previous page's last capture on this tab (an ISO time: a number never matched an
+      // entry's time, so stack pages never reported a console error)
+      const since = from
       let captured = false
-      const capture = (opts = {}) => { captured = true; return captureStep({ page, node, locale, viewports: opts.viewports ? scopeKeys(run.meta.scope, passKeys, opts.viewports) : viewports, run, consoleFile, since, item, fields, maxChars: config.evaluators?.jev?.max_state_chars, options: captureOptions(scenario, node), extra: { http_status: status } }) }
+      let lastCapture = null
+      const capture = (opts = {}) => { captured = true; lastCapture = new Date().toISOString(); return captureStep({ page, node, locale, viewports: opts.viewports ? scopeKeys(run.meta.scope, passKeys, opts.viewports) : viewports, run, consoleFile, since, item, fields, maxChars: config.evaluators?.jev?.max_state_chars, options: captureOptions(scenario, node), extra: { http_status: status } }) }
       try {
         if (script) await script.default({ page, item, url: () => item.url, locale, env, run: run.meta, capture, acceptDialogs: () => acceptDialogs(page) })
         else await page.goto(item.url, { waitUntil: 'domcontentloaded', timeout: 30000 })
@@ -870,10 +874,11 @@ async function walkStack ({ node, locale, page, env, run, scenario, scenarioDir,
         failed.push(`${item.id} (${item.path}): ${error.message.split('\n')[0]}`)
         if (streak.record('stack', error.message)) say(`  stopping ${node.id} (${locale}${tag}): the last 5 pages failed with the same error`)
       }
+      from = lastCapture || new Date().toISOString()
       // long stacks: progress every 25 pages (or 30 s) with the time left, estimated from the pages so far
       if (i + 1 < chosen.length && ((i + 1) % 25 === 0 || Date.now() - told > 30000)) { told = Date.now(); const left = timeLeft(i + 1, chosen.length, told - started); say(`  ${node.id} ${locale}: ${i + 1}/${chosen.length}${left ? ` · ${left}` : ''}`) }
     }
-  } finally { page.off('response', onResponse) }
+  } finally { page.off('response', onResponse); consoleBound?.done(page, from) }
   // the rotation of this locale goes into the run (the stack index shows it) and the pages checked into the state
   if (state && rotation) {
     const checked = await state.save(checkedNow, all)
@@ -1531,7 +1536,11 @@ const commands = {
         say(`Attached ${entry.file} to ${node.id}`)
         return
       }
-      const since = (await readCaptures(run.dir)).filter((c) => c.node === node.id).map((c) => c.at).pop()
+      // the console counts from the run's start, or from the run's last capture on this tab (#197): what the shared
+      // browser logged before belongs to another run or to the step captured then. A capture that names no tab (an
+      // own browser, an older version) bounds every tab; one on another tab does not (its errors are not ours)
+      const tab = conn ? await pageTarget(page) : null
+      const since = (await readCaptures(run.dir)).filter((c) => c.type !== 'attachment' && c.at && !c.carried_from && (!c.tab || !tab || c.tab === tab)).map((c) => c.at).reduce((a, b) => (b > a ? b : a), run.meta.started_at || '') || undefined
       const results = await captureStep({ page, node, locale, options: captureOptions(scenario, node), viewports: inState(run, node, manualKeys(run, list(args.viewports)), args.state), run, consoleFile: conn ? consoleLog(root, config.output, env.name) : null, maxChars: config.evaluators?.jev?.max_state_chars, since, htmlView: htmlViewAllowed(env, scenario) ? { scenarioId: scenario.id } : null, stability: Number(args.stability) || 0 })
       for (const r of results) {
         const failed = Object.entries(r.checks).filter(([, v]) => v.ok === false).map(([k]) => k)
@@ -1689,6 +1698,10 @@ const commands = {
           const page = await lctx.newPage()
           const shared = conn && !parallel && plain // the shared browser's own context logs its console to a file
           if (!shared) observeConsole(page)
+          // where each page's console counts from (#197): from the walk's start on it, then from the previous step's
+          // last capture on it, so what a page logs between two steps counts in the next one and nothing older does
+          const consoleFrom = new WeakMap([[page, new Date().toISOString()]])
+          const consoleBound = { since: (p) => consoleFrom.get(p) || run.meta.started_at, done: (p, at) => consoleFrom.set(p, at || new Date().toISOString()) }
           // one recorder per page (the walk's tab and each named session's), started on its first step;
           // recordings and traces need CDP: Chromium passes only
           const recorders = new Map()
@@ -1699,7 +1712,7 @@ const commands = {
           }
           try {
             // every locale starts as a new visitor on its first walk in the run (an own context is new already)
-            if (shared && !walked.some((c) => c.locale === locale)) { await resetSession(lctx, page, baseUrl(env, locale)); say(`session reset (new visitor, ${locale}${tag})`) }
+            if (shared && !walked.some((c) => c.locale === locale)) { await resetSession(lctx, page, baseUrl(env, locale)); consoleBound.done(page); say(`session reset (new visitor, ${locale}${tag})`) }
             for (const node of scenario.nodes) {
               if (node.kind === 'decision' || (pick && !pick.includes(node.id))) continue
               if (node.kind !== 'stack' && node.path && !urlFor(env, node, locale)) continue // step does not exist in this locale
@@ -1710,7 +1723,7 @@ const commands = {
               const consoleFile = shared && !sess ? consoleLog(root, config.output, env.name) : null
               if (node.kind === 'stack') {
                 try {
-                  const bad = await walkStack({ node, locale, page: sPage, env, run, scenario, scenarioDir, config, consoleFile, args, keys: pass.keys, tag, cache: stackCache, gate: stackGate })
+                  const bad = await walkStack({ node, locale, page: sPage, env, run, scenario, scenarioDir, config, consoleFile, consoleBound, args, keys: pass.keys, tag, cache: stackCache, gate: stackGate })
                   for (const b of bad) failed.push(`${node.id} (${locale}${tag}) ${b}`)
                 } catch (error) {
                   failed.push(`${node.id} (${locale}${tag}): ${error.message.split('\n')[0]}`)
@@ -1745,11 +1758,15 @@ const commands = {
                 const rec = state === 'default' ? rec0 : null
                 rec?.beforeStep(node)
                 const records = []
-                const capture = (opts = {}) => { captured = true; rec?.beforeCapture(node); return captureStep({ page: sPage, node, locale, options: captureOptions(scenario, node), viewports: scopeKeys(run.meta.scope, stateKeys(run.meta.scope, Object.keys(scopeKeys(run.meta.scope, pass.keys, opts.viewports || null)), state)), run, htmlView: htmlViewAllowed(env, scenario) ? { scenarioId: scenario.id } : null, consoleFile, maxChars: config.evaluators?.jev?.max_state_chars, extra: node.session ? { session: node.session } : {}, stability: Number(args.stability) || 0 }).then((r) => { prefetch?.add(r, run.dir); records.push(...r); return r }) }
+                // the console counts from the previous step's last capture on this page (#197), for every capture the
+                // step takes: a later capture of the same view replaces the earlier one and must still name what it logged
+                const since = consoleBound.since(sPage)
+                let lastCapture = null
+                const capture = (opts = {}) => { captured = true; rec?.beforeCapture(node); lastCapture = new Date().toISOString(); return captureStep({ page: sPage, node, locale, options: captureOptions(scenario, node), viewports: scopeKeys(run.meta.scope, stateKeys(run.meta.scope, Object.keys(scopeKeys(run.meta.scope, pass.keys, opts.viewports || null)), state)), run, htmlView: htmlViewAllowed(env, scenario) ? { scenarioId: scenario.id } : null, consoleFile, since, maxChars: config.evaluators?.jev?.max_state_chars, extra: node.session ? { session: node.session } : {}, stability: Number(args.stability) || 0 }).then((r) => { prefetch?.add(r, run.dir); records.push(...r); return r }) }
                 try {
                   await mod.default({ page: sPage, context: sCtx, locale, state, node: { id: node.id, title: localized(node.title, locale), kind: node.kind, ...(node.states ? { states: nodeStates(run.meta.scope, node) } : {}) }, session: sessionInfo(node.session), url: (id = node.id) => urlFor(env, stepOf(scenario, id), locale), env, run: run.meta, capture, crop: (selector, title, o = {}) => captureCrop({ page: sPage, node, locale, selector, title, run, padding: Number(o.padding) || 0, options: captureOptions(scenario, node) }), acceptDialogs: () => acceptDialogs(sPage) })
                   if (!captured) await capture()
-                } catch (error) { await rec?.afterStep(node, { error }); throw error }
+                } catch (error) { await rec?.afterStep(node, { error }); throw error } finally { consoleBound.done(sPage, lastCapture) }
                 await rec?.afterStep(node, { records })
               }
               try {

package/src/lib/access.mjs

@@ -91,7 +91,7 @@ export async function prepareContext (context, env, { log } = {}) {
     const request = route.request()
     const reason = policyViolation(env, { method: request.method(), url: request.url() })
     if (reason) {
-      log?.({ type: 'blocked', url: request.url(), text: reason })
+      log?.({ type: 'blocked', url: request.url(), text: reason }, request)
       return route.abort('blockedbyclient')
     }
     if (toGate(request.url())) {

package/src/lib/browser-daemon.mjs

@@ -3,9 +3,10 @@
 // policy and gate on every request and records console errors for captures.
 // Secrets are resolved here from the inherited environment, never passed in argv.
 import { chromium } from 'playwright'
-import { writeJson, appendJsonl } from './util.mjs'
+import { writeJson } from './util.mjs'
 import { prepareContext, clientCertificates } from './access.mjs'
 import { launchPersistentWithRetry } from './browser.mjs'
+import { consoleWriter, pageTarget } from './console.mjs'
 
 const opts = JSON.parse(process.argv[2])
 const certs = opts.env ? clientCertificates(opts.env, opts.root) : []
@@ -18,10 +19,29 @@ const context = await launchPersistentWithRetry(chromium, opts.profile, {
   args: [`--remote-debugging-port=${opts.port}`]
 })
 
-const log = (entry) => appendJsonl(opts.consoleFile, { ts: new Date().toISOString(), ...entry }).catch(() => {})
+// the console log starts empty with the browser (once it is up): what an earlier one logged belongs to no page of it
+const consoleLog = await consoleWriter(opts.consoleFile)
+
+// every entry names its tab (#197): a capture counts only the errors of the page it captures, not of other tabs
+const tabs = new WeakMap()
+const tabOf = (page) => {
+  if (!page) return Promise.resolve(null)
+  // a lookup that failed or timed out is tried again with the next entry
+  if (!tabs.has(page)) tabs.set(page, pageTarget(page).then((id) => { if (!id) tabs.delete(page); return id }))
+  return tabs.get(page)
+}
+const pageOf = (request) => { try { return request.frame().page() } catch { return null } }
+const log = (entry, request = null) => {
+  const ts = new Date().toISOString()
+  return consoleLog.append(tabOf(entry.page || pageOf(request)).then((tab) => {
+    const { page, ...rest } = entry
+    return { ts, ...rest, ...(tab ? { tab } : {}) }
+  }))
+}
 const watch = (page) => {
-  page.on('console', (m) => { if (m.type() === 'error') log({ type: 'console', url: page.url(), text: m.text(), src: m.location()?.url || null }) })
-  page.on('pageerror', (e) => log({ type: 'pageerror', url: page.url(), text: e.message }))
+  tabOf(page)
+  page.on('console', (m) => { if (m.type() === 'error') log({ page, type: 'console', url: page.url(), text: m.text(), src: m.location()?.url || null }) })
+  page.on('pageerror', (e) => log({ page, type: 'pageerror', url: page.url(), text: e.message }))
 }
 context.pages().forEach(watch)
 context.on('page', watch)

package/src/lib/capture.mjs

@@ -3,7 +3,7 @@ import { dirname, relative, join } from 'node:path'
 import { buildHtmlView } from './htmlview.mjs'
 import { probe } from './probe.mjs'
 import { pageSpecScript } from './devspec.mjs'
-import { writeJson, readJsonl } from './util.mjs'
+import { writeJson } from './util.mjs'
 import { addCapture, runPaths } from './run.mjs'
 import { maskSpec, maskList, inPage, maskInPage, rememberPii, knownPii, maskMailHeaders, maskHtml, scrubDeep, scrubText, updateMasks, loadKnownPii, saveKnownPii, RECORD_PLAIN_KEYS } from './pii.mjs'
 
@@ -98,7 +98,7 @@ export function captureOptions (scenario, node) {
 }
 
 import { criteriaHash } from './evaluate.mjs'
-import { consoleEntriesFor } from './console.mjs'
+import { consoleEntriesFor, readConsoleLog, pageTarget, entriesSince } from './console.mjs'
 import { redact, redactDeep } from './secrets.mjs'
 import { readFields } from './stack.mjs'
 import { checkLinks, checkHreflang, checkLlmsTxt, requester, walkCache, NETWORK_ASSERTS, isolatedRequest, anonymousRequest, cacheScope } from './linkcheck.mjs'
@@ -203,6 +203,10 @@ export async function captureStep ({ page, node, locale, viewports, run, console
   // batch E: the engine of this page, and per key its colour scheme, motion and display mode (run scope variants)
   const engine = engineOf(page)
   const scope = run.meta?.scope
+  // console entries (#197): only those since `since` (an ISO time; a number is a time in ms) and, in the shared
+  // browser, only those of this page's tab
+  if (typeof since === 'number') since = new Date(since).toISOString()
+  const tab = consoleFile ? await pageTarget(page) : null
   for (const [viewport, [width, height]] of Object.entries(viewports)) {
     const now = page.viewportSize()
     if (!now || now.width !== width || now.height !== height) await page.setViewportSize({ width, height })
@@ -230,8 +234,8 @@ export async function captureStep ({ page, node, locale, viewports, run, console
       Object.assign(result.checks, localeChecks(node.criteria, { locale, meta: result.meta, url: page.url(), state: result.state }))
       // the console is read before the mask: the page's own reaction to masked text never counts as its error
       const url = page.url()
-      const collected = consoleFile ? await readJsonl(consoleFile) : consoleEntriesFor(page)
-      const consoleEntries = (collected || []).filter((e) => !since || e.ts >= since)
+      const collected = consoleFile ? await readConsoleLog(consoleFile) : consoleEntriesFor(page)
+      const consoleEntries = entriesSince(collected, { since, tab })
       // requests blocked by the readonly policy surface as ERR_BLOCKED_BY_CLIENT; they are reported separately
       // an error page's own status ("Failed to load resource: … 404" for the document itself) is not a console error
       const ownStatus = (e) => result.http_status >= 400 && /^Failed to load resource: the server responded with a status of \d+/.test(e.text) && e.src && sameDocument(e.src, url)
@@ -386,7 +390,7 @@ export async function captureStep ({ page, node, locale, viewports, run, console
       if (mask.active) await saveKnownPii(run.dir)
       const file = paths.step(stepId, locale, viewport, 'capture.json')
       await writeJson(file, stored)
-      await addCapture(run.dir, { type: 'capture', node: node.id, ...(item ? { item: item.id } : {}), locale, viewport, file: relative(run.dir, file), at: record.captured_at })
+      await addCapture(run.dir, { type: 'capture', node: node.id, ...(item ? { item: item.id } : {}), locale, viewport, file: relative(run.dir, file), at: record.captured_at, ...(tab ? { tab } : {}) })
       results.push(stored)
     } finally {
       // the page gets its own text back, also when the capture failed half-way

package/src/lib/console.mjs

@@ -1,3 +1,6 @@
+import { appendFile, mkdir, readFile, rename, rm } from 'node:fs/promises'
+import { dirname } from 'node:path'
+
 // In-memory collection for browsers that are not managed by the daemon.
 const logs = new WeakMap()
 
@@ -11,3 +14,77 @@ export function observeConsole (page) {
 }
 
 export const consoleEntriesFor = (page) => logs.get(page) ?? null
+
+// The shared browser's console log (#197): one file per environment, written by the browser daemon only. It starts
+// empty with every browser start and keeps at most two parts of CONSOLE_LIMIT bytes (the current one and the one
+// before), so a browser that runs for days does not grow it without end and a capture reads a few MB at most.
+export const CONSOLE_LIMIT = 2 * 1024 * 1024
+const previousPart = (file) => file.replace(/(\.jsonl)?$/, '.old.jsonl')
+
+/** Appends entries in call order; starts the log afresh and moves it aside as the previous part past `limit` bytes. */
+export async function consoleWriter (file, { limit = CONSOLE_LIMIT } = {}) {
+  await mkdir(dirname(file), { recursive: true })
+  await rm(previousPart(file), { force: true })
+  await rm(file, { force: true })
+  let size = 0
+  let queue = Promise.resolve()
+  const write = async (entry) => {
+    const line = JSON.stringify(entry) + '\n'
+    const bytes = Buffer.byteLength(line)
+    if (size > 0 && size + bytes > limit) { await rename(file, previousPart(file)).catch(() => {}); size = 0 }
+    await appendFile(file, line)
+    size += bytes
+  }
+  // an entry may be a promise (its tab is looked up first): the file keeps the order of the calls
+  const append = (entry) => { queue = queue.then(async () => write(await entry)).catch(() => {}); return queue }
+  return { append, flushed: () => queue }
+}
+
+// one part of the log, line by line: a line cut short (the daemon was writing it) is skipped, never the whole part
+async function readPart (file) {
+  const text = await readFile(file, 'utf8').catch(() => '')
+  const lines = []
+  for (const line of text.split('\n')) {
+    if (!line) continue
+    try { lines.push({ line, entry: JSON.parse(line) }) } catch {}
+  }
+  return lines
+}
+
+/** Every entry the shared browser's console log still holds, the previous part first. */
+export async function readConsoleLog (file) {
+  // the current part first: when the daemon moves it aside between the two reads, its entries are in the previous
+  // part then and are read twice (and kept once), never lost
+  const current = await readPart(file)
+  const previous = await readPart(previousPart(file))
+  const moved = new Set(previous.map(({ line }) => line))
+  return [...previous, ...current.filter(({ line }) => !moved.has(line))].map(({ entry }) => entry)
+}
+
+/**
+ * The browser's own id of a page's tab (a CDP target id). The daemon and every process connected over CDP see the
+ * same id, so a capture keeps only the entries of the tab it captures. Null outside Chromium.
+ */
+export async function pageTarget (page, { timeout = 3000 } = {}) {
+  let session, timer
+  const lookup = (async () => {
+    session = await page.context().newCDPSession(page)
+    const { targetInfo } = await session.send('Target.getTargetInfo')
+    return targetInfo?.targetId || null
+  })()
+  try {
+    // a page that hangs (a modal dialog, a busy renderer) leaves its entries untagged rather than holding the log
+    return await Promise.race([lookup, new Promise((resolve) => { timer = setTimeout(() => resolve(null), timeout) })])
+  } catch { return null } finally {
+    clearTimeout(timer)
+    lookup.then(() => session?.detach(), () => {}).catch(() => {})
+  }
+}
+
+/**
+ * The entries a capture may count: written at or after `since` (an ISO time) and, when the tab is known, on that
+ * tab. Entries without a tab (a browser started by an older version) are kept: the time bound still holds for them.
+ */
+export function entriesSince (entries, { since = null, tab = null } = {}) {
+  return (entries || []).filter((e) => (!since || e.ts >= since) && (!tab || !e.tab || e.tab === tab))
+}

package/src/lib/doctor.mjs

@@ -175,6 +175,9 @@ export async function doctor ({ config, root, file = null, fetchImpl = fetch, la
         // sharing runs needs the Developer / Tester role (or admin) and, on tokens with scope sets, the upload scope
         const canShare = ['tester', 'admin'].includes(me.role) && (!Array.isArray(me.scopes) || me.scopes.includes('upload'))
         add('token', sameOrg, `${me.email} · ${me.role} · org ${me.org}${canShare ? '' : ' (this token cannot share runs)'}`, sameOrg ? '' : `The token belongs to organization "${me.org}" but the config says "${config.org}".`)
+        // doctor --json carries the scopes, so a script can tell before a long walk whether the token may also make
+        // a run public (full), not only share it (upload): scripts/demo-run.mjs (#62)
+        if (Array.isArray(me.scopes)) checks[checks.length - 1].scopes = me.scopes
         if (!canShare) add('token role', false, Array.isArray(me.scopes) ? `${me.role} · ${me.scopes.join(', ')}` : me.role, 'kaloko share needs a Developer / Tester token with the upload scope.')
       }
     } catch (e) { add('token', false, `${service} unreachable: ${e.cause?.code || e.message}`, 'Check your network or VPN; KALOKO_URL points the CLI to another service.') }

package/src/lib/evaluate.mjs

@@ -449,7 +449,7 @@ function triageContext ({ config, root, settings, report, fetchImpl, uncertain =
               const video = side?.files?.webm || side?.files?.mp4
               // a recording that cannot be read costs its frames only, never the screen's findings
               if (video) try {
-                const frames = await chooseFrames({ page: await page(), file: join(runDir, video), taps: (side.taps || []).map((t) => t.t ?? t), max: Math.min(settings.frames_per_step, framesLeft), maxW: settings.frame_width || 640 })
+                const frames = await chooseFrames({ page: await page(), file: join(runDir, video), taps: (side.taps || []).map((t) => t.t ?? t), max: Math.min(settings.frames_per_step, framesLeft), maxW: settings.frame_width || 640, cacheDir })
                 framesLeft -= frames.length; report.triage.frames += frames.length
                 for (const batch of frameBatches(frames)) {
                   const r = await ask(w, { kind: 'motion', context: { ...context, frames: batch.map((f) => ({ t_ms: f.t, why: f.why })) }, images: batch.map((f) => f.data) }, { frames: batch.map((f) => f.t) })

package/src/lib/health-findings.mjs

@@ -8,6 +8,7 @@
 // Pure: no Node APIs. The shapes are documented in help/reference/health-api.md.
 import { parseHealthKey } from './health-index.mjs'
 import { severityRank, SEVERITIES } from './health-core.mjs'
+import { impactOf } from './traffic-core.mjs'
 
 export const HEALTH_FINDINGS_SCHEMA = 'kaloko.health-findings.v1'
 /** What a person may set; fixed is never set, it is derived. */
@@ -45,10 +46,13 @@ export function findingId (fp) {
 /**
  * Findings of a flow from its open results. rows: health_open rows ({ key, severity, url, first_run, first_at, misses
  * }); checks: { HC…: { text, pack } } of the newest run's index; edit: "step|page" → edit_url; seen: { run, at } of
- * the newest run (last seen of what it checked). Returns findings, worst first: { id, fingerprint, check, text, pack,
- * site, locale, step, severity, count, unchecked, samples: [{ page, url, edit_url }], first_seen, last_seen }.
+ * the newest run (last seen of what it checked); traffic: "step|page" → the page's Search Console and GA4 numbers
+ * (#157). Returns findings, worst first: { id, fingerprint, check, text, pack, site, locale, step, severity, count,
+ * unchecked, samples: [{ page, url, edit_url, traffic? }], first_seen, last_seen, traffic?, impact? }. With traffic,
+ * a finding adds up clicks and impressions of its pages that have numbers (`traffic.pages` of them) and its impact
+ * (the sum of each page's impact, traffic-core.mjs impactOf); without, it has neither.
  */
-export function groupFindings (rows, { checks = {}, edit = {}, seen = null } = {}) {
+export function groupFindings (rows, { checks = {}, edit = {}, seen = null, traffic = null } = {}) {
   const out = new Map()
   for (const r of rows || []) {
     const k = parseHealthKey(r.key)
@@ -64,9 +68,15 @@ export function groupFindings (rows, { checks = {}, edit = {}, seen = null } = {
     if (r.misses > 0) f.unchecked++
     else if (seen) f.last_seen = seen
     if (r.first_at && (!f.first_seen || r.first_at < f.first_seen.at)) f.first_seen = { run: r.first_run, at: r.first_at }
+    const ek = `${k.step}|${k.page}`
+    const t = traffic && Object.hasOwn(traffic, ek) && traffic[ek] && typeof traffic[ek] === 'object' ? traffic[ek] : null
+    if (t) {
+      const sum = (f.traffic ||= { clicks: 0, impressions: 0, pages: 0 })
+      sum.clicks += Number(t.clicks) || 0; sum.impressions += Number(t.impressions) || 0; sum.pages++
+      f.impact = (f.impact || 0) + impactOf(t, r.severity)
+    }
     if (f.samples.length < SAMPLE_MAX) {
-      const ek = `${k.step}|${k.page}`
-      f.samples.push({ page: k.page || null, url: r.url || null, edit_url: (edit && Object.hasOwn(edit, ek) ? edit[ek] : null) || null })
+      f.samples.push({ page: k.page || null, url: r.url || null, edit_url: (edit && Object.hasOwn(edit, ek) ? edit[ek] : null) || null, ...(t ? { traffic: { clicks: Number(t.clicks) || 0, impressions: Number(t.impressions) || 0 } } : {}) })
     }
   }
   return [...out.values()].sort(worstFirst)
@@ -79,8 +89,8 @@ export const FINDINGS_SUMMARY_SCHEMA = 'kaloko.health-findings-summary.v1'
  * the flow keeps open, plus the findings whose every page the run fixed (`fixed`: the diff's fixed results as rows;
  * count 0, last seen `previous`). An open finding counts the pages the run fixed in `fixed` too.
  */
-export function summarizeFindings (rows, { checks = {}, edit = {}, seen = null, fixed = [], previous = null } = {}) {
-  const list = groupFindings(rows, { checks, edit, seen })
+export function summarizeFindings (rows, { checks = {}, edit = {}, seen = null, fixed = [], previous = null, traffic = null } = {}) {
+  const list = groupFindings(rows, { checks, edit, seen, traffic })
   const at = new Map(list.map((f) => [f.id, f]))
   for (const g of groupFindings(fixed, { checks, edit })) {
     const f = at.get(g.id)
@@ -114,3 +124,54 @@ export const atLeastSeverity = (severity, min) => SEVERITIES.includes(min) && se
  * the issue last said.
  */
 export const countChanged = (before, now) => before != null && Math.abs(now - before) >= Math.max(3, Math.ceil(before * 0.25))
+
+// ---------- where issues go (#191) ----------
+
+/** Trackers the findings sync can open issues in. */
+export const SYNC_TRACKERS = ['jira', 'linear', 'github', 'plane']
+/** Routes a scenario may have; checks and packs per route. */
+export const ROUTE_MAX = 20
+const ROUTE_LIST_MAX = 50
+const CHECK_PATTERN = /^[A-Z]{1,6}[0-9]{0,6}\*?$/
+const PACK = /^[a-z][a-z0-9_-]{0,30}$/
+
+/**
+ * Routes of a sync setting from the API: [{ tracker, checks?: ['HC127', 'HC1*'], packs?: ['aeo'] }], in order. A check
+ * ends with * to take every check that starts so (HC1* is HC100 to HC199 and HC1000…). Throws an Error that says
+ * what is wrong; [] for none.
+ */
+export function cleanRoutes (list) {
+  if (list == null) return []
+  if (!Array.isArray(list)) throw new Error('routes is a list of { tracker, checks, packs }.')
+  if (list.length > ROUTE_MAX) throw new Error(`At most ${ROUTE_MAX} routes.`)
+  return list.map((r, i) => {
+    if (!r || typeof r !== 'object') throw new Error(`Route ${i + 1} is not an object.`)
+    const tracker = String(r.tracker || '')
+    if (!SYNC_TRACKERS.includes(tracker)) throw new Error(`Route ${i + 1}: tracker is ${SYNC_TRACKERS.join(', ')}.`)
+    const words = (v, name) => {
+      if (v == null) return []
+      if (!Array.isArray(v) || v.length > ROUTE_LIST_MAX) throw new Error(`Route ${i + 1}: ${name} is a list of at most ${ROUTE_LIST_MAX}.`)
+      return [...new Set(v.map((x) => String(x ?? '').trim()))]
+    }
+    const checks = words(r.checks, 'checks').map((c) => c.toUpperCase())
+    const packs = words(r.packs, 'packs').map((p) => p.toLowerCase())
+    const badCheck = checks.find((c) => !CHECK_PATTERN.test(c) || c === '*')
+    if (badCheck !== undefined) throw new Error(`Route ${i + 1}: ${badCheck.slice(0, 20) || '(empty)'} is not a check id (HC127) or a prefix (HC1*).`)
+    const badPack = packs.find((p) => !PACK.test(p))
+    if (badPack !== undefined) throw new Error(`Route ${i + 1}: ${badPack.slice(0, 20) || '(empty)'} is not a pack name (seo, aeo).`)
+    if (!checks.length && !packs.length) throw new Error(`Route ${i + 1}: name checks or packs.`)
+    return { tracker, ...(checks.length ? { checks } : {}), ...(packs.length ? { packs } : {}) }
+  })
+}
+
+const checkMatches = (pattern, check) => pattern.endsWith('*') ? String(check).startsWith(pattern.slice(0, -1)) : pattern === check
+/**
+ * The tracker a finding's issue goes to: the first route that names its check (or a prefix of it) or its pack, else
+ * the scenario's tracker.
+ */
+export function routeOf (f, routes = [], fallback = null) {
+  for (const r of routes || []) {
+    if ((r.checks || []).some((c) => checkMatches(c, f.check)) || (f.pack && (r.packs || []).includes(String(f.pack).toLowerCase()))) return r.tracker
+  }
+  return fallback
+}

package/src/lib/health-index.mjs

@@ -8,6 +8,7 @@
 // (worker/src/health-index.js); the shapes are documented in help/reference/health-api.md.
 import { healthOfNode, levelOf, findingSeverity, severityRank } from './health-core.mjs'
 import { worst } from './manifest-core.mjs'
+import { trafficView } from './traffic-core.mjs'
 
 export const HEALTH_INDEX_SCHEMA = 'kaloko.health-index.v1'
 export const HEALTH_AGGREGATE_SCHEMA = 'kaloko.health-aggregate.v1'
@@ -42,14 +43,16 @@ const firstUrl = (vps) => { for (const c of Object.values(vps || {})) if (c?.url
  * [{ locale, step, check, counts, top: [{ page, path, url, verdict, evidence }] }], open: [[key, severity, url]],
  * open_total, truncated, passed, edit }. passed says which checks passed on which page: { "step|locale": { sigs:
  * ["HC103,HC112", …], pages: { <page>: <index into sigs> } } }; only a result that passed counts as fixed later
- * (passedIn). edit maps "step|page" to the edit_url of a stack page with open results (findings link it).
+ * (passedIn). edit maps "step|page" to the edit_url of a stack page with open results (findings link it); traffic
+ * maps "step|page" to the Search Console and GA4 numbers of such a page when its stack has `traffic:` (#157), for the
+ * same pages and bound (findings add them up, an issue shows them).
  */
 export function buildHealthIndex (manifest, stacks = {}) {
   const checks = Object.create(null); const groups = new Map(); const open = []; const pages = new Set(); const ok = new Map()
   // where a page with open results is edited (a stack item's edit_url): "step|page" → URL, kept below for the open list only
-  const edits = new Map()
+  const edits = new Map(); const visits = new Map()
   const totals = { results: 0, ...blank() }
-  const add = (step, locale, page, path, url, check, verdict, evidence, editUrl = null) => {
+  const add = (step, locale, page, path, url, check, verdict, evidence, editUrl = null, traffic = null) => {
     if (!VERDICTS.includes(verdict)) return
     pages.add(`${step}|${page}`)
     const gk = `${locale}\u0000${step}\u0000${check}`
@@ -63,6 +66,7 @@ export function buildHealthIndex (manifest, stacks = {}) {
     if (list.length < TOP_KEEP) list.push({ page, ...(path ? { path } : {}), url: url || null, verdict, ...(evidence ? { evidence: cut(evidence) } : {}) })
     open.push([healthKey(step, locale, check, page), severity, url || null])
     if (editUrl && typeof editUrl === 'string' && /^https?:\/\//i.test(editUrl)) edits.set(`${step}|${page}`, cut(editUrl, 500))
+    if (traffic && typeof traffic === 'object') { const t = trafficView(traffic); if (t && Object.keys(t).length) visits.set(`${step}|${page}`, t) }
   }
   for (const n of manifest?.nodes || []) {
     if (n.kind === 'decision') continue
@@ -85,7 +89,7 @@ export function buildHealthIndex (manifest, stacks = {}) {
             if (!was || worst([was.v, x[0]]) !== was.v) per.set(k, { locale, id, v: x[0], e: x[1] })
           }
         }
-        for (const { locale, id, v, e } of per.values()) add(n.id, locale, String(it.id), it.path || null, it.url || firstUrl(it.captures?.[locale]), id, v, e, it.edit_url)
+        for (const { locale, id, v, e } of per.values()) add(n.id, locale, String(it.id), it.path || null, it.url || firstUrl(it.captures?.[locale]), id, v, e, it.edit_url, it.traffic)
       }
       continue
     }
@@ -115,16 +119,18 @@ export function buildHealthIndex (manifest, stacks = {}) {
   // edit links of the pages in the kept open list only, at most EDIT_MAX of them (worst first, like the list)
   const kept = open.slice(0, OPEN_MAX)
   const edit = Object.create(null); let links = 0
+  const traffic = Object.create(null); let numbers = 0
   for (const [key] of kept) {
-    if (links >= EDIT_MAX) break
+    if (links >= EDIT_MAX && numbers >= EDIT_MAX) break
     const { step, page } = parseHealthKey(key)
     const k = `${step}|${page}`
-    if (edits.has(k) && !Object.hasOwn(edit, k)) { edit[k] = edits.get(k); links++ }
+    if (links < EDIT_MAX && edits.has(k) && !Object.hasOwn(edit, k)) { edit[k] = edits.get(k); links++ }
+    if (numbers < EDIT_MAX && visits.has(k) && !Object.hasOwn(traffic, k)) { traffic[k] = visits.get(k); numbers++ }
   }
   return {
     schema: HEALTH_INDEX_SCHEMA, checks, totals: { ...totals, pages: pages.size },
     groups: [...groups.values()].map(({ fails, unsure, ...g }) => ({ ...g, top: [...fails, ...unsure].slice(0, TOP_KEEP) })),
-    open: kept, open_total: open.length, truncated: open.length > OPEN_MAX, passed, edit
+    open: kept, open_total: open.length, truncated: open.length > OPEN_MAX, passed, edit, ...(numbers ? { traffic } : {})
   }
 }
 

package/src/lib/triage.mjs

@@ -4,6 +4,7 @@
 // CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID straight to Workers AI. Findings never change a verdict.
 import { join } from 'node:path'
 import { readFile } from 'node:fs/promises'
+import { createHash } from 'node:crypto'
 import { readJson, writeJson, sha256 } from './util.mjs'
 import { buildTriageRequest, parseTriage, mergeFindings, clefModelId, TRIAGE_PROMPT_VERSION, MAX_TRIAGE_IMAGES } from './triage-core.mjs'
 
@@ -77,15 +78,24 @@ export function hostedTriageSender (config, report) {
   return send
 }
 
+// bump when the choice of frames or their encoding changes, so cached frames are chosen again
+const FRAMES_VERSION = 1
+
 /**
  * Frames of a recording for the motion questions, chosen in a browser page: around each tap, where the picture changes
  * most between samples (a jump, a flash, a message), and the last frame. Returns [{ t, why, data }] in time order,
- * at most `max` frames, each a WebP data URL `maxW` wide.
+ * at most `max` frames, each a WebP data URL `maxW` wide. With `cacheDir` the frames are kept by the recording's
+ * content and the settings, so evaluating the same recording again sends the very same frames (and its triage answers
+ * from the cache) even when the browser decodes or encodes a frame differently the second time.
  */
-export async function chooseFrames ({ page, file, taps = [], max = 6, maxW = 1024 }) {
+export async function chooseFrames ({ page, file, taps = [], max = 6, maxW = 1024, cacheDir = null }) {
   if (!(max > 0)) return []
-  const src = `data:video/${file.endsWith('.mp4') ? 'mp4' : 'webm'};base64,${(await readFile(file)).toString('base64')}`
-  return page.evaluate(async ({ src, taps, max, maxW }) => {
+  const bytes = await readFile(file)
+  const cacheFile = cacheDir && join(cacheDir, `frames-${createHash('sha256').update(bytes).update(JSON.stringify({ taps, max, maxW, v: FRAMES_VERSION })).digest('hex')}.json`)
+  const kept = cacheFile && await readJson(cacheFile, null)
+  if (Array.isArray(kept)) return kept
+  const src = `data:video/${file.endsWith('.mp4') ? 'mp4' : 'webm'};base64,${bytes.toString('base64')}`
+  const frames = await page.evaluate(async ({ src, taps, max, maxW }) => {
     const v = document.createElement('video'); v.muted = true; v.preload = 'auto'; v.src = src
     // every wait has a limit: a stalled video must not hang the evaluation
     const within = (p, ms) => Promise.race([p, new Promise((ok, no) => setTimeout(() => no(new Error('the recording did not answer in time')), ms))])
@@ -96,13 +106,25 @@ export async function chooseFrames ({ page, file, taps = [], max = 6, maxW = 102
     const dur = Number.isFinite(v.duration) ? v.duration : 0
     if (!dur) return []
     const seek = (t) => within(new Promise((ok) => { v.onseeked = ok; v.currentTime = Math.min(Math.max(0, t), Math.max(0, dur - 0.01)) }), 5000)
+    // `seeked` (even at readyState 4) does not mean the frame can be painted yet: on a busy machine the first draw
+    // sometimes paints nothing, which read as a change from an empty picture and moved the chosen frames. A decoded
+    // frame is opaque, so the draw is repeated until its middle row holds one.
+    const draw = async (g, w, h) => {
+      const painted = () => { const row = g.getImageData(0, h >> 1, w, 1).data; for (let i = 3; i < row.length; i += 4) if (row[i]) return true; return false }
+      for (let tries = 0; ; tries++) {
+        g.clearRect(0, 0, w, h); g.drawImage(v, 0, 0, w, h)
+        if (painted()) return
+        if (tries >= 100) throw new Error('a frame of the recording could not be drawn')
+        await new Promise((ok) => setTimeout(ok, 20))
+      }
+    }
     const small = document.createElement('canvas'); small.width = 64; small.height = Math.max(1, Math.round(64 * v.videoHeight / v.videoWidth))
     const sg = small.getContext('2d', { willReadFrequently: true })
     // sampled differences: 4 samples a second, at most 240
     const step = Math.max(0.25, dur / 240)
     const diffs = []; let prev = null
     for (let t = 0; t <= dur; t += step) {
-      await seek(t); sg.drawImage(v, 0, 0, small.width, small.height)
+      await seek(t); await draw(sg, small.width, small.height)
       const px = sg.getImageData(0, 0, small.width, small.height).data
       if (prev) { let d = 0; for (let i = 0; i < px.length; i += 4) d += Math.abs(px[i] - prev[i]) + Math.abs(px[i + 1] - prev[i + 1]) + Math.abs(px[i + 2] - prev[i + 2]); diffs.push({ t, d: d / (px.length / 4) / 765 }) }
       prev = px
@@ -117,11 +139,13 @@ export async function chooseFrames ({ page, file, taps = [], max = 6, maxW = 102
     const list = chosen.length > max ? [...chosen.slice(0, max - 1), chosen.at(-1)] : chosen
     const big = document.createElement('canvas'); const s = Math.min(1, maxW / v.videoWidth)
     big.width = Math.round(v.videoWidth * s); big.height = Math.round(v.videoHeight * s)
-    const bg = big.getContext('2d')
+    const bg = big.getContext('2d', { willReadFrequently: true })
     const out = []
-    for (const f of list) { await seek(f.t); bg.drawImage(v, 0, 0, big.width, big.height); out.push({ t: Math.round(f.t * 1000), why: f.why, data: big.toDataURL('image/webp', 0.8) }) }
+    for (const f of list) { await seek(f.t); await draw(bg, big.width, big.height); out.push({ t: Math.round(f.t * 1000), why: f.why, data: big.toDataURL('image/webp', 0.8) }) }
     return out
   }, { src, taps, max, maxW })
+  if (cacheFile && frames.length) await writeJson(cacheFile, frames)
+  return frames
 }
 
 /** Frames in requests of MAX_TRIAGE_IMAGES, each overlapping the previous by one frame so a change at the seam is seen. */