kaloko 0.3.0

package/src/cli.mjs

@@ -0,0 +1,1344 @@
+import { writeFile, access, readFile, mkdir } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { gzipSync } from 'node:zlib'
+import { join, resolve, relative, dirname } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import yaml from 'js-yaml'
+import { loadConfig, environment, urlFor, baseUrl, CONFIG_FILE, LEGACY_CONFIG_FILE } from './lib/config.mjs'
+import { loadScenario, validateScenario } from './lib/scenario.mjs'
+import { createRun, resolveRun, readCaptures, listRuns } from './lib/run.mjs'
+import { gitMeta, projectAndIssue, appVersion } from './lib/git.mjs'
+import { startBrowser, stopBrowser, connectBrowser, currentPage, launchEphemeral, consoleLog, allStates, resetSession, acquireWalkLock } from './lib/browser.mjs'
+import { captureStep, captureCrop, captureOptions, acceptDialogs } from './lib/capture.mjs'
+import { observeConsole } from './lib/console.mjs'
+import { mailClient, waitForMessage, recipient, readMessageFile } from './lib/mail.mjs'
+import { newContext, accountFor, gateHeaders, gateOrigins, originMatcher } from './lib/access.mjs'
+import { rememberEnvironment } from './lib/secrets.mjs'
+import { evaluateRun, semanticPrefetch } from './lib/evaluate.mjs'
+import { buildManifest, writePreview } from './lib/build.mjs'
+import { localized, readJson, UserError, globToRegExp, failureStreak, expiryNote } from './lib/util.mjs'
+import { packageRoot } from './lib/schema.mjs'
+import { compareRuns, formatComparison } from './lib/compare.mjs'
+import { doctor, formatDoctor } from './lib/doctor.mjs'
+import { parsePlan, coverage, formatCoverage } from './lib/coverage.mjs'
+import { calibrate, formatCalibration, casesFromGolden, casesFromRun } from './lib/calibrate.mjs'
+import { pageFacts, draftScenario, scenarioYaml } from './lib/draft.mjs'
+import { recheckCaptures } from './lib/recheck.mjs'
+import { resolveItems, fieldsOf, DEFAULT_LIMIT } from './lib/stack.mjs'
+import { DEFAULTS as JEV_DEFAULTS } from './lib/jev.mjs'
+import { expandPacks } from './lib/packs.mjs'
+import { upsertPrComment } from './lib/pr.mjs'
+import { htmlViewAllowed } from './lib/htmlview.mjs'
+import { service } from './lib/service.mjs'
+import { walkDesign, syncDesign, publishVersion, historyCmd, referenceCmd, tokensCmd, exportLive, localRevisions, branchCmd, uploadBlobs } from './lib/design-cli.mjs'
+import { designDir, readBase, headKey } from './lib/design.mjs'
+import { driverFor, isApp, pngSize, ocr as ocrImage } from './lib/apps/drivers.mjs'
+import { captureApp } from './lib/apps/capture.mjs'
+import { readTree, flatten } from './lib/apps/tree.mjs'
+
+const fmtBytes = (n) => { n = Number(n) || 0; const u = ['B', 'kB', 'MB', 'GB']; let i = 0; while (n >= 1024 && i < u.length - 1) { n /= 1024; i++ } return `${n.toFixed(i ? 1 : 0)} ${u[i]}` }
+
+const HELP = `kaloko — walk, assess and approve what your agents built, on one flow canvas
+
+Usage: kaloko <command> [options]
+
+Project
+  draft <url> [url…] [--id SITE-X] [--title t] [--out qa/flows/site.yml] [--force]
+                                    First plan + read-only production scenario for public pages, drafted from the
+                                    pages (title, description, H1) with the seo, a11y, perf and console packs
+  init [--agent claude|codex|all] [--org <slug>]
+                                    Create ${CONFIG_FILE} and install the kaloko skill for your agent
+  doctor [--json] [--fix]           Check Node, Chrome, config, environments, browser ports, token, evaluator key
+                                    and app tools; --fix asks macOS for the desktop capture permissions
+  validate <scenario.yml>... [--coverage [--source ACCEPTANCE.md]]
+                                    Validate scenarios (schema + references); --coverage compares criteria with the plan
+                                    With a token it also warns about scenarios the service still lists whose file is gone (--offline skips it)
+  scenarios                         List scenarios matched by the config
+
+Run
+  start --scenario <file> --env <name> [--locales cs,en] [--viewports desktop,mobile] [--executor <name>]
+                                    [--app-version <v>] (default: the git tag on HEAD; documentation captures carry it)
+                                    Create a run directory and make it current
+  browser start|stop|status [--env e] [--headed]   One shared browser per environment (port = browser.port + index)
+                                    Shared Chromium with CDP (agents, scripts and people drive it)
+  open --step <id> [--locale l]     Navigate the current page to the step URL
+  session reset                     New visitor: clear cookies and storage in the shared browser
+  capture --step <id> [--locale l] [--url <url>] [--page <substring>] [--viewports a,b]
+                                    Capture the current page for a step in all viewports
+  capture --step <id> --crop <css> [--title <text>]
+                                    Attach an element screenshot to a step
+  capture --step <id> --image <shot.png> [--tree <dump.xml|json> | --ocr] [--platform android|ios|desktop]
+          [--device <name>] [--density 2.625 | --scale 3] [--viewport <name>]
+                                    An app screen taken by any tool (Maestro, Appium, XCUITest, a person) with its
+                                    UI dump (uiautomator/Appium XML, idb or Maestro JSON); app scenarios without
+                                    --image capture the current screen of the environment's app
+  mail --step <id> [--locale l] [--to <addr>] [--subject <text>] [--timeout 60]
+       [--since <ISO date> | --any-time] [--id <mailbox message id>]
+                                    Only messages received since the run started, unless --since/--any-time; --id takes one exact message
+                                    Capture an e-mail from the environment's mailbox (mail.provider) as an email step
+  mail --step <id> --file <message.eml|.html|.json|.txt> [--subject <text>]
+                                    Capture an e-mail you obtained yourself (any stack, any mailbox)
+  auth save --env <e> --account <key> [--url <url>]
+                                    A person signs in once (SSO, MFA) in a visible browser; the session is saved
+                                    for that account and walk reuses it (never uploaded)
+  auth list                         Saved sessions per environment and account, with their age
+  walk [--steps a,b] [--locales l] [--keep-going] [--ephemeral]
+                                    Run playwright steps (execution.script) and capture them; a session stops
+                                    after 3 steps in a row fail with the same error unless --keep-going
+                                    One walk at a time per shared browser; --ephemeral walks in an own browser
+                                    Semantic questions start as each step is captured; the walk ends with the
+                                    verdicts and what failed (--no-evaluate skips that; kaloko evaluate redoes it)
+       [--items a,b] [--limit N]    Stack steps (kind: stack, many pages of one template): only pages whose id or
+                                    path contains a, b; at most N pages (default items.limit, 500)
+  status                            Show what the current run has captured
+                                    Scenarios may declare "sessions" (people in the flow); walk keeps one browser context per session and locale
+
+Results
+  evaluate                          Deterministic checks + semantic evaluator (default JEV) for all captures
+  evaluate --recheck [--steps a,b]  After a scenario fix: re-run deterministic checks on the stored HTML (no walk);
+                                    console, overflow and performance keep their live result
+  build                             Write run.json and the local preview (index.html)
+  preview                           Build and print the preview path
+  share [--expires 30] [--pr]       Upload the run to kaloko.app (KALOKO_TOKEN, tester role);
+                                    --pr adds or updates one comment on the branch's pull request via gh
+  feedback [--run id] [--scenario id] [--json]
+                                    Open threads from reviewers (steps, the whole run, the whole flow) with ids and replies
+  comment [--step id | --flow] --note "…" [--status rejected|approved] [--run id] [--scenario id]
+  comment --reply|--resolve|--reopen|--edit|--delete <id> [--note "…"] [--flow]
+                                    Comment, answer and close feedback from the CLI (resolve with "Fixed in <commit>")
+  projects [--json]                 Projects of the organization (use the slug as project: in a scenario or config)
+  runs [--scenario id] [--all] [--json]
+                                    Shared runs: the newest per scenario (with "+ N older"); --all or --scenario lists every run
+  trash <run-id>... | restore <run-id>
+                                    Move runs to the trash (uploader or admin) and back; restorable until purge
+  prune [--scenario id] [--environment e] [--keep 3] [--older-than 14d] [--yes]
+                                    Keep the newest runs per scenario and environment plus kept, accepted, baseline,
+                                    referenced and commented runs; lists what would go to the trash unless --yes
+  keep <run-id> [--off]             A kept run never expires and is never pruned
+  archive <scenario-id> [--undo]    Hide a retired scenario from the scenario list (admin); its runs stay reachable
+  inbox [--all] [--read] [--json]   Your notifications on kaloko.app (mentions, returned runs, new runs, expiry); --read marks them read
+  calibrate [--golden labels.yml] [--scenario id [--limit 30]] [--target 0.95] [--json]
+                                    Semantic evaluator vs human labels: precision/recall per criterion at the
+                                    configured thresholds and suggested thresholds (labels from a golden file or
+                                    from reviewers' criterion verdicts in the service)
+  export [--run id] [--out file.zip]  Download a shared run (run.json + files) as a zip before it expires
+  export --scenario <id> [--accepted] [--out dir] [--locales l] [--viewports v]
+                                    Newest capture of every step as steps/<step>/<locale>/<viewport>.<ext> plus
+                                    index.json (documentation layer, Business plan); unchanged files are skipped
+  public [--run id] [--off]         Make a shared run readable without sign-in (admin; testers may refresh an already public scenario)
+  compare [--run id] [--baseline id | --design] [--json]
+                                    Text diff of two runs: step statuses, criterion verdicts, scores and evidence
+                                    (default: current run against the scenario baseline, else the previous run)
+
+Design (environments with kind: design; live HTML steps in a folder)
+  start --scenario <file> --env <design env>   A run of the design folder (same scenario as development and QA)
+  walk [--steps a,b] [--no-cache]   Render the steps; unchanged revisions reuse their captures
+  status                            Per step: synced, changed here, changed in the draft, conflict; step status
+  sync [--pull|--push] [--branch b] [--mine a,b|--theirs a,b]
+                                    Exchange revisions with the shared draft; only changed steps and missing files travel
+  share [--name <text>] [--branch b]  Publish the draft as a version of the flow (a run): "v4 · 3 changed, 17 unchanged"
+  history [--scenario id] [--step id] [--locale l] [--json]
+                                    Versions of the flow; revisions of a step with who (person or agent) and when
+  reference [--scenario id] (--design|--baseline) (--run id|--version n|--off) [--branch b]
+                                    Show or set the design reference (accepted version) and the baseline
+  tokens pull|push|check|validate [--project p] [--file tokens.json|tokens.resolver.json] [--mode m] [--json]
+                                    The project's token set (DTCG); check lists raw values outside it in the live folder
+  branch list | create <name> [--from vN] [--git <branch>] | merge <name> [--take-branch a,b] [--keep-main c]
+                                    Branches of the draft; a git-linked branch is what implementation runs of that git branch check against
+  export --live [--version n|--draft|--run id] [--out design/]
+                                    Live files of a version (default: the design reference) into a folder: the handoff
+  export --live --views --run <id> [--viewport desktop] [--out design/]
+                                    Fork into a draft: the HTML views of an app run become design steps (experimental)
+
+Common options: --run <id|dir> (or KALOKO_RUN)  --config <file>   KALOKO_AGENT=<name> labels writes by an agent
+`
+
+/** validate: scenarios the service still lists as active whose scenario file no longer exists here (#58). */
+async function warnRetired (args) {
+  if (args.offline) return
+  let config, client
+  try { ({ config } = await context(args)); client = service(config) } catch { return } // no project or no token: offline
+  if (!config?.org) return
+  let list
+  try { list = await client.request('GET', `/orgs/${config.org}/scenarios?runs=1`) } catch { return }
+  const gone = []
+  for (const s of list || []) {
+    if (s.archived || !s.file || (config.project && s.project && s.project !== config.project)) continue
+    try { await readFile(resolve(s.file)) } catch { gone.push(s) }
+  }
+  for (const s of gone) say(`! ${s.id}: the service lists it as active, but ${s.file} is gone here (split or renamed?). Archive it: kaloko archive ${s.id}`)
+}
+
+/** The end of a walk: evaluate (the semantic answers are mostly cached by now) and say what did not pass. */
+async function walkVerdicts ({ prefetch, run, scenario, config, root }) {
+  const t0 = Date.now()
+  await prefetch.done()
+  const report = await evaluateRun({ run, scenario, config, root })
+  const fails = report.findings.filter((f) => f.verdict === 'fail'); const unsure = report.findings.filter((f) => f.verdict === 'needs_review')
+  say(`\nEvaluated ${report.evaluated} capture(s) in ${Math.round((Date.now() - t0) / 100) / 10} s: ${fails.length ? `${fails.length} failing` : 'nothing failing'}${unsure.length ? `, ${unsure.length} for a person to look at` : ''}.`)
+  const line = (f) => `${f.node}${f.item ? `/${f.item}` : ''} ${f.locale}/${f.viewport} ${f.id}${f.why ? `: ${String(f.why).slice(0, 140)}` : ''}`
+  // pack criteria say how to fix them; a fix repeated across steps and locales is printed once
+  const hinted = new Set()
+  const withFix = (f) => { const l = line(f); if (!f.fix || hinted.has(f.id)) return l; hinted.add(f.id); return `${l}\n      fix: ${f.fix}` }
+  if (fails.length) say(`  ✕ ${fails.slice(0, 15).map(withFix).join('\n  ✕ ')}${fails.length > 15 ? `\n  … ${fails.length - 15} more (kaloko build lists them all)` : ''}`)
+  if (unsure.length) say(`  ? ${unsure.slice(0, 8).map(line).join('\n  ? ')}${unsure.length > 8 ? `\n  … ${unsure.length - 8} more` : ''}`)
+  if (report.skipped.length) say(`  Semantic criteria not evaluated: ${[...new Set(report.skipped.map((x) => x.split(': ').slice(1).join(': ')))].slice(0, 2).join('; ')}`)
+}
+
+function parse (argv) {
+  const args = { _: [] }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a.startsWith('--')) {
+      const [k, v] = a.slice(2).split('=')
+      if (v !== undefined) args[k] = v
+      else if (argv[i + 1] && !argv[i + 1].startsWith('--')) args[k] = argv[++i]
+      else args[k] = true
+    } else args._.push(a)
+  }
+  return args
+}
+const list = (v) => (typeof v === 'string' ? v.split(',').map((s) => s.trim()).filter(Boolean) : null)
+const say = (...m) => console.log(...m)
+
+async function context (args) {
+  const { config, root } = await loadConfig(process.cwd(), args.config)
+  return { config, root }
+}
+
+async function runContext (args) {
+  const ctx = await context(args)
+  const run = await resolveRun({ root: ctx.root, output: ctx.config.output, run: args.run })
+  const scenario = await loadScenario(resolve(ctx.root, run.meta.scenario_file))
+  const env = environment(ctx.config, run.meta.environment.name)
+  // a design is not checked against itself: the design reference checks apply to implementation runs only (#42)
+  if (env.kind === 'design') for (const n of scenario.nodes) if (n.criteria) n.criteria = n.criteria.filter((c) => !['design_pixels', 'design_structure'].includes(c.check.assert))
+  rememberEnvironment(env)
+  return { ...ctx, run, scenario, env }
+}
+
+function stepOf (scenario, id) {
+  if (!id) throw new UserError('--step <id> is required.')
+  const node = scenario.nodes.find((n) => n.id === id)
+  if (!node) throw new UserError(`Unknown step "${id}". Steps: ${scenario.nodes.filter((n) => n.kind !== 'decision').map((n) => n.id).join(', ')}`)
+  return node
+}
+
+/** Scenario of --scenario (id or file) or of the current run. */
+async function scenarioIdOf (args, config, root) {
+  if (typeof args.scenario === 'string') {
+    if (/\.ya?ml$/.test(args.scenario)) return (await loadScenario(resolve(args.scenario))).id
+    return args.scenario
+  }
+  try { return (await resolveRun({ root, output: config.output, run: args.run })).meta.scenario.id } catch {}
+  throw new UserError('--scenario <id|file> is required when there is no current run.')
+}
+
+function scopeViewports (run, pick) {
+  const all = run.meta.scope.viewports
+  const names = pick || Object.keys(all)
+  return Object.fromEntries(names.map((n) => { if (!all[n]) throw new UserError(`Unknown viewport "${n}".`); return [n, all[n]] }))
+}
+
+async function scenarioFiles (config, root) {
+  const { readdir } = await import('node:fs/promises')
+  const out = []
+  for (const pattern of config.scenarios || []) {
+    const parts = pattern.split('/')
+    const fixed = []
+    for (const p of parts) { if (/[*?]/.test(p)) break; fixed.push(p) }
+    const base = join(root, ...fixed)
+    const re = globToRegExp(pattern)
+    const walk = async (dir) => {
+      let entries = []
+      try { entries = await readdir(dir, { withFileTypes: true }) } catch { return }
+      for (const e of entries) {
+        const full = join(dir, e.name)
+        if (e.isDirectory()) { if (e.name !== 'node_modules' && !e.name.startsWith('.')) await walk(full) } else if (re.test(relative(root, full))) out.push(full)
+      }
+    }
+    await walk(base)
+  }
+  return [...new Set(out)].sort()
+}
+
+async function catalogFor (config, root) {
+  const runs = await listRuns(root, config.output)
+  const out = []
+  for (const file of await scenarioFiles(config, root)) {
+    try {
+      const s = yaml.load(await readFile(file, 'utf8'))
+      out.push({
+        id: s.id, title: s.title, kind: s.kind || 'task', file: relative(root, file),
+        runs: runs.filter((r) => r.scenario?.id === s.id).map((r) => ({ id: r.id, started_at: r.started_at, git: r.git, environment: r.environment, summary: r.summary })).sort((a, b) => b.started_at.localeCompare(a.started_at))
+      })
+    } catch {}
+  }
+  return out
+}
+
+// `{run}` in an address stands for the short run id (same as mail.address in the config).
+const expandRun = (value, short) => (value || '').replace('{run}', short)
+
+// Finds the e-mail (or takes the one given) and captures it as the node's screens.
+async function captureMail ({ config, root, run, env, node, locale, to, subject, timeoutMs = 60000, viewports, message = null, since, id = null }) {
+  if (!message) {
+    const client = mailClient(env.mail, root, env)
+    // only messages that arrived during this run unless told otherwise (#52): stale e-mails are not captured silently
+    message = await waitForMessage(client, { to, subject, since: since === undefined ? run.meta.started_at : since, id }, { timeoutMs })
+  }
+  const browser = await launchEphemeral(config)
+  try {
+    // The capture itself needs page JavaScript (webp encoding, settle), so the
+    // context keeps it on; the e-mail's own scripts are stripped and every
+    // non-image request is blocked instead. Images hosted behind the environment's
+    // gate get its headers, nobody else does.
+    const page = await (await browser.newContext()).newPage()
+    const gate = gateHeaders(env)
+    const toGate = Object.keys(gate).length ? originMatcher(gateOrigins(env)) : () => false
+    await page.route('**/*', (route) => {
+      const r = route.request()
+      if (r.url().startsWith('data:')) return route.continue()
+      if (r.resourceType() !== 'image') return route.abort()
+      return toGate(r.url()) ? route.continue({ headers: { ...r.headers(), ...gate } }) : route.continue()
+    })
+    const html = (message.html || `<pre>${(message.text || '').replace(/</g, '&lt;')}</pre>`).replace(/<script[\s\S]*?<\/script>/gi, '')
+    // Remote images are allowed for the screenshot but must not hold the capture hostage.
+    await page.setContent(html, { waitUntil: 'domcontentloaded', timeout: 20000 })
+    await page.waitForLoadState('load', { timeout: 15000 }).catch(() => {})
+    const mail = { id: message.id, subject: message.subject, from: message.from || '', to: (message.to || []).join(', '), date: message.date }
+    const results = await captureStep({ page, node, locale, viewports: scopeViewports(run, viewports), run, maxChars: config.evaluators?.jev?.max_state_chars, extra: { mail } })
+    return { subject: mail.subject, count: results.length }
+  } finally {
+    await browser.close()
+  }
+}
+
+/** Documentation layer: newest (accepted) capture of every step into a folder, skipping files whose run did not change. */
+async function exportScenario ({ args, config, root, client }) {
+  const { mkdir: mk, writeFile: wf, readFile: rf } = await import('node:fs/promises')
+  const id = args.scenario
+  const out = typeof args.out === 'string' ? resolve(args.out) : resolve(root, config.output, 'docs', id)
+  const q = args.accepted ? '?accepted=1' : ''
+  const index = await client.request('GET', `/orgs/${config.org}/scenarios/${encodeURIComponent(id)}/steps${q}`)
+  const want = (v, allowed) => !allowed || allowed.includes(v)
+  const locales = list(args.locales); const viewports = list(args.viewports)
+  let previous = null
+  try { previous = JSON.parse(await rf(join(out, 'index.json'), 'utf8')) } catch {}
+  const had = new Map((previous?.steps || []).flatMap((s) => (s.files || []).map((f) => [`${s.id}|${f.locale}|${f.viewport}`, f])))
+  const steps = []; let written = 0; let kept = 0
+  for (const s of index.steps) {
+    const files = []
+    for (const c of s.captures.filter((c) => want(c.locale, locales) && want(c.viewport, viewports))) {
+      const ext = c.image.format
+      const rel = `steps/${s.id}/${c.locale}/${c.viewport}`
+      const old = had.get(`${s.id}|${c.locale}|${c.viewport}`)
+      const entry = { locale: c.locale, viewport: c.viewport, image: `${rel}.${ext}`, html: `${rel}.html`, run: c.run.id, captured_at: c.captured_at, page_url: c.page_url, size: c.size, version: c.run.version }
+      if (old && old.run === c.run.id) { files.push(old); kept++; continue }
+      await mk(join(out, 'steps', s.id, c.locale), { recursive: true })
+      const img = await client.fetch(c.links.image.replace(/^https?:\/\/[^/]+\/api\/v1/, ''))
+      await wf(join(out, entry.image), Buffer.from(await img.arrayBuffer()))
+      const html = await client.fetch(c.links.html.replace(/^https?:\/\/[^/]+\/api\/v1/, ''))
+      await wf(join(out, entry.html), Buffer.from(await html.arrayBuffer()))
+      files.push(entry); written++
+    }
+    steps.push({ id: s.id, title: s.title, status: s.status, files })
+  }
+  await mk(out, { recursive: true })
+  await wf(join(out, 'index.json'), JSON.stringify({ schema: 'qawalk.docs-export.v1', scenario: index.scenario, run: index.run, accepted: !!args.accepted, exported_at: new Date().toISOString(), steps }, null, 2) + '\n')
+  say(`Exported ${index.steps.length} steps of ${id} from run ${index.run.id}${index.run.app_version ? ` (version ${index.run.app_version})` : ''} → ${relative(process.cwd(), out) || '.'}\n  ${written} files downloaded, ${kept} unchanged`)
+}
+
+/**
+ * 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 }) {
+  const { items, total, truncated } = await resolveItems({ node, base: baseUrl(env, locale), page, scenarioDir, env, locale, limit: Number(args.limit) || undefined })
+  const only = list(args.items)
+  const chosen = only ? items.filter((it) => only.some((q) => it.id === q || it.path.includes(q))) : items
+  const scope = run.meta.scope.viewports
+  const vpNames = (node.items.viewports || []).filter((v) => scope[v])
+  const viewports = Object.fromEntries((vpNames.length ? vpNames : [Object.keys(scope)[0]]).map((v) => [v, scope[v]]))
+  say(`▦ ${node.id} ${locale}: ${chosen.length} page(s)${truncated ? ` — limit ${Number(args.limit) || node.items.limit || DEFAULT_LIMIT} reached (${total}+ found; raise items.limit or pass --limit)` : ''}`)
+  const fields = fieldsOf(node)
+  const script = node.execution?.script ? await import(pathToFileURL(resolve(scenarioDir, node.execution.script)).href) : null
+  let status = null
+  const onResponse = (r) => { if (r.request().isNavigationRequest() && r.frame() === page.mainFrame()) status = r.status() }
+  page.on('response', onResponse)
+  const streak = failureStreak(5)
+  const failed = []; let ok = 0
+  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()
+      let captured = false
+      const capture = (opts = {}) => { captured = true; return captureStep({ page, node, locale, viewports: opts.viewports ? Object.fromEntries(opts.viewports.map((v) => [v, scope[v]])) : 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 })
+        if (!captured) await capture()
+        ok++; streak.ok('stack')
+      } catch (error) {
+        failed.push(`${item.id} (${item.path}): ${error.message.split('\n')[0]}`)
+        if (streak.record('stack', error.message)) say(`  stopping ${node.id} (${locale}): the last 5 pages failed with the same error`)
+      }
+      if ((i + 1) % 25 === 0 && i + 1 < chosen.length) say(`  ${node.id} ${locale}: ${i + 1}/${chosen.length}`)
+    }
+  } finally { page.off('response', onResponse) }
+  say(`${failed.length ? '✗' : '✓'} ${node.id} ${locale}: ${ok}/${chosen.length} page(s) captured`)
+  return failed
+}
+
+/** Deep link of an app step: a URL scheme as written, a path under the environment's base URL (universal links). */
+function linkFor (env, node, locale) {
+  const raw = typeof node.path === 'string' ? node.path : (node.path?.[locale] ?? node.path?.default)
+  if (!raw) return null
+  const p = raw.replaceAll('{random}', () => Math.random().toString(36).slice(2, 10))
+  if (/^[a-z][a-z0-9+.-]*:/i.test(p)) return p
+  return env.base_url ? urlFor(env, { path: p }, locale) : null
+}
+const appViewport = (run) => Object.keys(run.meta.scope.viewports || {})[0] || null
+
+/**
+ * Walks an app scenario (platform android, ios, electron, desktop) with the environment's driver: per locale the
+ * app starts fresh, each step runs its script (with `app`, the driver) or opens its deep link, then is captured.
+ */
+async function walkApp ({ config, root, run, scenario, env, args }) {
+  const platform = scenario.platform
+  const pick = list(args.steps)
+  const locales = list(args.locales) || run.meta.scope.locales
+  const scenarioDir = resolve(root, run.meta.scenario_file, '..')
+  const pending = []; const failed = []; const skipped = []
+  // WebP and thumbnails are encoded in a headless Chrome page (no native image dependency); PNG without Chrome
+  const enc = await launchEphemeral(config).catch(() => null)
+  const encoder = enc ? await enc.newPage().catch(() => null) : null
+  const streak = failureStreak(args['keep-going'] ? 0 : 3)
+  const maxChars = config.evaluators?.jev?.max_state_chars
+  try {
+    for (const locale of locales) {
+      const driver = driverFor(platform, env, { root, scenarioDir, locale })
+      try {
+        await driver.open({ locale, reset: true })
+        if (driver.web) observeConsole(driver.page)
+        say(`${platform} ${locale}: ${driver.web ? 'Electron window' : 'app'} ready`)
+      } catch (error) { failed.push(`${platform} (${locale}): ${error.message.split('\n')[0]}`); say(`✗ ${platform} ${locale}: ${error.message.split('\n')[0]}`); await driver.close().catch(() => {}); if (error instanceof UserError) break; continue }
+      try {
+        for (const node of scenario.nodes) {
+          if (node.kind === 'decision' || (pick && !pick.includes(node.id))) continue
+          if (node.kind === 'stack') { pending.push(`${node.id} (${locale}): stack steps list web pages; not walked on ${platform}`); continue }
+          if (node.kind === 'email' && node.mail?.to) {
+            try { const r = await captureMail({ config, root, run, env, node, locale, to: expandRun(node.mail.to, run.meta.short), subject: localized(node.mail?.subject, locale), timeoutMs: 45000 }); say(`✓ ${node.id} ${locale}: "${r.subject}"`) } catch (error) { failed.push(`${node.id} (${locale}): ${error.message.split('\n')[0]}`); say(`✗ ${node.id} ${locale}: ${error.message.split('\n')[0]}`) }
+            continue
+          }
+          const scripted = ['playwright', 'script'].includes(node.execution?.strategy) && node.execution?.script
+          const link = linkFor(env, node, locale)
+          if (!scripted && !(link && ['playwright', 'script'].includes(node.execution?.strategy))) { pending.push(`${node.id} (${locale}): ${node.execution?.strategy || 'agent'} — ${(node.execution?.instructions || '').split('\n')[0]}`); continue }
+          if (streak.stopped(locale)) { skipped.push(`${node.id} (${locale})`); continue }
+          try {
+            let captured = false
+            const capture = async (o = {}) => {
+              captured = true
+              if (driver.web) {
+                const [w, h] = await driver.page.evaluate(() => [innerWidth, innerHeight])
+                return captureStep({ page: driver.page, node, locale, options: captureOptions(scenario, node), viewports: { [o.viewport || appViewport(run) || 'window']: [w, h] }, run, consoleFile: null, maxChars, extra: { platform, device: 'Electron' } })
+              }
+              return captureApp({ snapshot: await driver.snapshot(), node, locale, viewport: o.viewport || appViewport(run), run, platform, encoder, maxChars, extra: { url: link } })
+            }
+            if (scripted) {
+              const mod = await import(pathToFileURL(resolve(scenarioDir, node.execution.script)).href)
+              await mod.default({ app: driver, page: driver.page || null, locale, node: { id: node.id, title: localized(node.title, locale), kind: node.kind }, env, run: run.meta, capture, link: (id = node.id) => linkFor(env, stepOf(scenario, id), locale), url: (id = node.id) => linkFor(env, stepOf(scenario, id), locale) })
+            } else await driver.link(link)
+            if (!captured) await capture()
+            say(`✓ ${node.id} ${locale}`)
+            streak.ok(locale)
+          } catch (error) {
+            failed.push(`${node.id} (${locale}): ${error.message.split('\n')[0]}`)
+            say(`✗ ${node.id} ${locale}: ${error.message.split('\n')[0]}`)
+            if (streak.record(locale, error.message)) say(`  stopping ${locale}: the last 3 steps failed with the same error`)
+          }
+        }
+      } finally { await driver.close().catch(() => {}) }
+    }
+  } finally { await enc?.close().catch(() => {}) }
+  if (pending.length) say(`\nSteps for an agent or a person (drive the app, then kaloko capture --step <id> --image shot.png [--tree dump.xml|json]):\n  - ${[...new Set(pending)].join('\n  - ')}`)
+  if (failed.length) { say(`\nSteps that failed (fix and rerun with --steps):\n  - ${failed.join('\n  - ')}`); process.exitCode = 1 }
+  if (skipped.length) { say(`\nSteps not walked after repeated failures:\n  - ${skipped.join('\n  - ')}`); process.exitCode = 1 }
+}
+
+/**
+ * `kaloko capture --image`: a screen someone else took (a person, an agent, Maestro, Appium, XCUITest, Detox),
+ * with its UI dump when there is one (uiautomator/Appium XML, idb or Maestro JSON), or OCR on macOS (--ocr).
+ */
+async function captureImage ({ config, run, scenario, node, locale, args }) {
+  const png = await readFile(resolve(String(args.image))).catch(() => { throw new UserError(`--image ${args.image} cannot be read.`) })
+  const px = pngSize(png)
+  if (!px) throw new UserError('--image must be a PNG screenshot.')
+  const platform = typeof args.platform === 'string' ? args.platform : (scenario.platform && scenario.platform !== 'web' ? scenario.platform : 'desktop')
+  let scale = Number(args.scale) || null
+  let tree = null
+  if (typeof args.tree === 'string') {
+    const raw = await readFile(resolve(args.tree), 'utf8').catch(() => { throw new UserError(`--tree ${args.tree} cannot be read.`) })
+    const density = Number(args.density) || 1
+    tree = readTree(raw, { density })
+    // without --scale: the tree's extent against the image width (Android dumps in pixels stay 1 unless --density)
+    if (!scale && Number(args.density)) scale = density
+    if (!scale) { const right = Math.max(0, ...flatten(tree.root).map((n) => n.bounds ? n.bounds.x + n.bounds.w : 0)); scale = right > 0 ? Math.max(1, Math.min(4, Math.round(px[0] / right))) : 1 }
+  } else if (args.ocr) {
+    scale ||= platform === 'ios' ? 3 : 1
+    const res = await ocrImage(png, locale ? [locale] : undefined)
+    tree = readTree({ ocr: res.ocr.map((l) => ({ text: l.text, x: Math.round(l.x / scale), y: Math.round(l.y / scale), w: Math.round(l.w / scale), h: Math.round(l.h / scale) })) })
+  }
+  scale ||= 1
+  const enc = await launchEphemeral(config).catch(() => null)
+  try {
+    const encoder = enc ? await enc.newPage().catch(() => null) : null
+    return await captureApp({ snapshot: { png, tree, size: [Math.round(px[0] / scale), Math.round(px[1] / scale)], scale, device: typeof args.device === 'string' ? args.device : null, crash: null, logErrors: null }, node, locale, viewport: typeof args.viewport === 'string' ? args.viewport : appViewport(run), run, platform, encoder, maxChars: config.evaluators?.jev?.max_state_chars, extra: { source: 'import', url: typeof args.url === 'string' ? args.url : null } })
+  } finally { await enc?.close().catch(() => {}) }
+}
+
+const commands = {
+  async init (args) {
+    const cwd = process.cwd()
+    const file = join(cwd, CONFIG_FILE)
+    let exists = false
+    try { await access(file); exists = true } catch {}
+    // a project from before the rename keeps its qawalk.config.yml (it is still read)
+    try { await access(join(cwd, LEGACY_CONFIG_FILE)); exists = true; say(`${LEGACY_CONFIG_FILE} found; kept (still read; rename it to ${CONFIG_FILE} when convenient).`) } catch {}
+    if (!exists) {
+      let tpl = await readFile(join(packageRoot, 'templates', 'kaloko.config.yml'), 'utf8')
+      if (typeof args.org === 'string') {
+        if (!/^[a-z0-9][a-z0-9-]{1,40}$/.test(args.org)) throw new UserError('--org must be the organization slug from kaloko.app (a-z, 0-9, -).')
+        tpl = tpl.replace(/^org: .*$/m, `org: ${args.org}`)
+      }
+      await writeFile(file, tpl)
+      say(`Created ${CONFIG_FILE}. Edit org and environments.`)
+    } else if (!existsSync(join(cwd, LEGACY_CONFIG_FILE))) say(`${CONFIG_FILE} already exists; kept.`)
+    const agent = typeof args.agent === 'string' ? args.agent : 'none'
+    if (!['claude', 'codex', 'all', 'none'].includes(agent)) throw new UserError('--agent must be claude, codex, all or none.')
+    const { cp, mkdir, appendFile, rm } = await import('node:fs/promises')
+    const skill = join(packageRoot, 'skills', 'kaloko')
+    const targets = { claude: ['.claude/skills/kaloko'], codex: ['skills/kaloko'], all: ['.claude/skills/kaloko', 'skills/kaloko'], none: [] }[agent]
+    for (const t of targets) {
+      await mkdir(join(cwd, t, '..'), { recursive: true })
+      await cp(skill, join(cwd, t), { recursive: true, force: true })
+      say(`Installed skill → ${t}`)
+      // the skill was called qawalk before the rename: two copies would compete for the same tasks
+      const legacy = join(cwd, t.replace(/kaloko$/, 'qawalk'))
+      if (existsSync(join(legacy, 'SKILL.md')) && /^name: qawalk$/m.test(await readFile(join(legacy, 'SKILL.md'), 'utf8'))) { await rm(legacy, { recursive: true, force: true }); say(`Removed the former skill ${t.replace(/kaloko$/, 'qawalk')}`) }
+    }
+    if (agent === 'codex' || agent === 'all') {
+      const agents = join(cwd, 'AGENTS.md')
+      let text = ''
+      try { text = await readFile(agents, 'utf8') } catch {}
+      if (text.includes('skills/qawalk/SKILL.md')) {
+        await writeFile(agents, text.replace(/## QAwalk\n/g, '## Kaloko\n').replace(/the QAwalk canvas/g, 'the Kaloko canvas').replaceAll('skills/qawalk/SKILL.md', 'skills/kaloko/SKILL.md'))
+        say('Updated the pointer in AGENTS.md to skills/kaloko')
+      } else if (!text.includes('skills/kaloko')) {
+        await appendFile(agents, `${text && !text.endsWith('\n') ? '\n' : ''}\n## Kaloko\n\nFor acceptance plans, scenario runs and the Kaloko canvas use \`skills/kaloko/SKILL.md\`.\n`)
+        say('Added a Kaloko pointer to AGENTS.md')
+      }
+    }
+    const consentStep = join(cwd, 'qa', 'flows', 'steps', 'consent.mjs')
+    try { await access(consentStep) } catch {
+      await mkdir(join(consentStep, '..'), { recursive: true })
+      await cp(join(packageRoot, 'templates', 'steps', 'consent.mjs'), consentStep)
+      say('Added qa/flows/steps/consent.mjs (accepts the consent dialog, if the site has one)')
+    }
+    say(`Next: create a tester token in the app (Settings → API tokens) and put KALOKO_TOKEN into .env.\nScenario template: ${join(packageRoot, 'templates', 'scenario.yml')}`)
+  },
+
+  async validate (args) {
+    if (!args._.length) throw new UserError('Usage: kaloko validate <scenario.yml>...')
+    let failed = 0
+    for (const file of args._) {
+      const scenario = yaml.load(await readFile(file, 'utf8'))
+      const problems = validateScenario(scenario)
+      if (!problems.length) expandPacks(scenario)
+      if (problems.length) { failed++; say(`✕ ${file}\n  - ${problems.join('\n  - ')}`) } else say(`✓ ${file}`)
+      if (args.coverage) {
+        // the plan is scenario.source (relative to the working directory or to the scenario file), or --source
+        const candidates = typeof args.source === 'string' ? [resolve(args.source)] : scenario.source ? [resolve(scenario.source), resolve(file, '..', scenario.source), resolve(file, '..', '..', scenario.source)] : []
+        let plan = null
+        for (const c of candidates) { try { plan = parsePlan(await readFile(c, 'utf8')); break } catch {} }
+        if (!plan) { say(`  · no acceptance plan found (${scenario.source ? `source: ${scenario.source}` : 'scenario has no source'}); pass --source <ACCEPTANCE.md>`); continue }
+        const cov = coverage(scenario, plan)
+        say(formatCoverage(file, cov))
+        if (cov.missing.length) process.exitCode = 1
+      }
+    }
+    if (failed) process.exitCode = 1
+    await warnRetired(args)
+  },
+
+  async scenarios (args) {
+    const { config, root } = await context(args)
+    for (const s of await catalogFor(config, root)) say(`${s.id.padEnd(36)} ${s.kind.padEnd(5)} ${String(s.runs.length).padStart(3)} runs  ${s.file}`)
+  },
+
+  async start (args) {
+    const { config, root } = await context(args)
+    if (!args.scenario || !args.env) throw new UserError('Usage: kaloko start --scenario <file> --env <name>')
+    const scenarioFile = resolve(args.scenario)
+    const scenario = await loadScenario(scenarioFile)
+    const env = environment(config, args.env)
+    if (scenario.environments && !scenario.environments.includes(env.name)) throw new UserError(`Scenario ${scenario.id} is not allowed on ${env.name} (allowed: ${scenario.environments.join(', ')}).`)
+    if (env.readonly && !scenario.readonly) throw new UserError(`Environment ${env.name} is readonly; the scenario must declare readonly: true.`)
+    const locales = list(args.locales) || scenario.locales || ['default']
+    const vpAll = scenario.viewports || { desktop: [1280, 800], mobile: [390, 844] }
+    const vpNames = list(args.viewports) || Object.keys(vpAll)
+    const scope = { locales, viewports: Object.fromEntries(vpNames.map((n) => [n, vpAll[n]])), ...(args.note ? { note: args.note } : {}) }
+    const git = await gitMeta(root)
+    const executor = { kind: args.executor ? 'agent' : 'cli', name: args.executor || 'kaloko-cli' }
+    const { project, issue } = await projectAndIssue({ cwd: root, config, scenario, branch: git?.branch })
+    const appVer = typeof args['app-version'] === 'string' ? args['app-version'].slice(0, 80) : await appVersion(root)
+    const { dir, meta } = await createRun({ output: config.output, scenario, scenarioFile, env, scope, git, executor, root, project, issue, appVersion: appVer })
+    say(`Run ${meta.id}\n  dir: ${relative(process.cwd(), dir)}\n  env: ${env.name}${env.readonly ? ' (readonly)' : ''}\n  locales: ${locales.join(', ')}  viewports: ${vpNames.join(', ')}\n  project: ${project.slug}${issue ? `  issue: ${issue.repo ? issue.repo + '#' : '#'}${issue.number}` : ''}`)
+    const addr = recipient(env.mail, meta.short)
+    if (addr) say(`  test e-mail: ${addr}`)
+    say(`  other agents may start runs here too: pin this one with --run ${meta.id} or KALOKO_RUN=${meta.id}`)
+  },
+
+  async browser (args) {
+    const { config, root } = await context(args)
+    const action = args._[0] || 'status'
+    let env = null
+    if (typeof args.env === 'string') env = environment(config, args.env)
+    else { try { const run = await resolveRun({ root, output: config.output, run: args.run }); env = environment(config, run.meta.environment.name) } catch {} }
+    if (action === 'start') {
+      const state = await startBrowser({ root, config, env, headed: !!args.headed })
+      say(`${state.reused ? 'Browser already running' : 'Browser started'} for ${env.name}: ${state.cdp} (pid ${state.pid})${state.readonly ? ', readonly policy on' : ''}\nConnect Playwright with chromium.connectOverCDP('${state.cdp}') or Playwright MCP --cdp-endpoint ${state.cdp}`)
+    } else if (action === 'stop') {
+      say(await stopBrowser({ root, config, env }) ? `Browser stopped${env ? ` (${env.name})` : ' (all environments)'}.` : 'Browser was not running.')
+    } else {
+      const states = await allStates({ root, config })
+      say(states.length ? states.map((s) => `${s.environment}: ${s.cdp} (pid ${s.pid})${s.readonly ? ', readonly' : ''}`).join('\n') : 'No shared browser is running.')
+    }
+  },
+
+  async open (args) {
+    const { config, root, run, scenario, env } = await runContext(args)
+    const node = stepOf(scenario, args.step)
+    const locale = args.locale || run.meta.scope.locales[0]
+    const url = urlFor(env, node, locale)
+    if (!url) throw new UserError(`Step ${node.id} has no path.`)
+    const conn = await connectBrowser({ root, config, env })
+    if (!conn) throw new UserError('Start the browser first: kaloko browser start')
+    const page = await currentPage(conn.context, args.page)
+    await page.goto(url, { waitUntil: 'domcontentloaded' })
+    say(`Opened ${url}`)
+    await conn.browser.close()
+  },
+
+  async capture (args) {
+    const { config, root, run, scenario, env } = await runContext(args)
+    const node = stepOf(scenario, args.step)
+    const locale = args.locale || run.meta.scope.locales[0]
+    if (!run.meta.scope.locales.includes(locale)) throw new UserError(`Locale ${locale} is not in the run scope (${run.meta.scope.locales.join(', ')}).`)
+    if (typeof args.image === 'string') {
+      const r = await captureImage({ config, run, scenario, node, locale, args })
+      const failed = Object.entries(r.checks).filter(([, v]) => v.ok === false).map(([k]) => k)
+      say(`✓ ${node.id} ${locale} ${r.viewport}  ${r.platform}${r.device ? ` · ${r.device}` : ''}  ${r.size.width}×${r.size.height}  ${r.files.tree ? `UI tree (${r.capture.tree})` : 'no UI tree'}  ${failed.length ? `failing checks: ${failed.join(', ')}` : 'checks ok'}`)
+      return
+    }
+    if (isApp(scenario.platform)) {
+      // the app's current screen, through the environment's driver (no navigation)
+      const driver = driverFor(scenario.platform, env, { root, scenarioDir: resolve(root, run.meta.scenario_file, '..'), locale })
+      if (driver.web) throw new UserError('For Electron, run kaloko walk --steps <id>, or pass --image.')
+      await driver.open({ locale, attach: true })
+      const enc = await launchEphemeral(config).catch(() => null)
+      try {
+        const r = await captureApp({ snapshot: await driver.snapshot(), node, locale, viewport: typeof args.viewport === 'string' ? args.viewport : Object.keys(run.meta.scope.viewports || {})[0], run, platform: scenario.platform, encoder: enc ? await enc.newPage() : null, maxChars: config.evaluators?.jev?.max_state_chars })
+        say(`✓ ${node.id} ${locale} ${r.viewport}  ${r.device || scenario.platform}  ${r.files.tree ? `UI tree (${r.capture.tree})` : 'no UI tree'}`)
+      } finally { await enc?.close().catch(() => {}) }
+      return
+    }
+    let conn = await connectBrowser({ root, config, env })
+    let ephemeral = null
+    let page
+    if (conn) page = await currentPage(conn.context, args.page)
+    else {
+      if (!args.url && !node.path) throw new UserError('No shared browser is running. Start it (kaloko browser start) or pass --url.')
+      ephemeral = await launchEphemeral(config)
+      page = await (await newContext(ephemeral, env, { root, config })).newPage()
+      observeConsole(page)
+    }
+    try {
+      const target = args.url === true || (!conn && !args.url) ? urlFor(env, node, locale) : args.url
+      if (target) await page.goto(target, { waitUntil: 'domcontentloaded' })
+      if (args.crop) {
+        const entry = await captureCrop({ page, node, locale, selector: args.crop, title: args.title, run })
+        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()
+      const results = await captureStep({ page, node, locale, options: captureOptions(scenario, node), viewports: scopeViewports(run, list(args.viewports)), 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 })
+      for (const r of results) {
+        const failed = Object.entries(r.checks).filter(([, v]) => v.ok === false).map(([k]) => k)
+        say(`✓ ${node.id} ${locale} ${r.viewport}  ${r.size.width}×${r.size.height}px  ${failed.length ? `failing checks: ${failed.join(', ')}` : 'checks ok'}${r.blocked_requests.length ? `  blocked: ${r.blocked_requests.length}` : ''}`)
+      }
+    } finally {
+      if (conn) await conn.browser.close()
+      if (ephemeral) await ephemeral.close()
+    }
+  },
+
+  async mail (args) {
+    const { config, root, run, scenario, env } = await runContext(args)
+    const node = stepOf(scenario, args.step)
+    if (node.kind !== 'email') throw new UserError(`Step ${node.id} is not an email step.`)
+    const locale = args.locale || run.meta.scope.locales[0]
+    // recipient: --to, the node's mail.to, the node's session mailbox, then the environment's address
+    const to = expandRun(args.to || node.mail?.to || (node.session && scenario.sessions?.[node.session]?.mailbox) || recipient(env.mail, run.meta.short), run.meta.short)
+    const subject = args.subject || localized(node.mail?.subject, locale)
+    let message = null
+    if (typeof args.file === 'string') {
+      message = await readMessageFile(resolve(args.file))
+      if (typeof args.subject === 'string') message.subject = args.subject
+      if (typeof args.to === 'string') message.to = [args.to]
+    }
+    let since
+    if (args['any-time']) since = null
+    else if (typeof args.since === 'string') { const t = Date.parse(args.since); if (Number.isNaN(t)) throw new UserError(`--since ${args.since} is not a date (ISO 8601, e.g. 2026-09-27T10:00).`); since = new Date(t).toISOString() }
+    const results = await captureMail({ config, root, run, env, node, locale, to, subject, timeoutMs: (Number(args.timeout) || 60) * 1000, viewports: list(args.viewports), message, since, id: typeof args.id === 'string' ? args.id : null })
+    say(`✓ ${node.id} ${locale}: "${results.subject}" → ${results.count} viewport(s)`)
+  },
+
+  async walk (args) {
+    const { config, root, run, scenario, env } = await runContext(args)
+    if (env.kind === 'design') {
+      await walkDesign({ config, root, run, scenario, env, pick: list(args.steps), locales: list(args.locales) || run.meta.scope.locales, viewports: scopeViewports(run, list(args.viewports)), say, noCache: !!args['no-cache'] })
+      return
+    }
+    if (isApp(scenario.platform)) return walkApp({ config, root, run, scenario, env, args })
+    const pick = list(args.steps)
+    const locales = list(args.locales) || run.meta.scope.locales
+    // --ephemeral: an own browser (own cookies and tabs) even when the shared one runs, so runs can walk in parallel
+    const conn = args.ephemeral ? null : await connectBrowser({ root, config, env })
+    const releaseLock = conn ? await acquireWalkLock({ root, config, env, run: run.meta.id }).catch(async (e) => { await conn.browser.close(); throw e }) : null
+    const ephemeral = conn ? null : await launchEphemeral(config)
+    const ctx = conn ? conn.context : await newContext(ephemeral, env, { root, config })
+    const scenarioDir = resolve(root, run.meta.scenario_file, '..')
+    // semantic questions of every new capture start right away; the walk ends with the verdicts (--no-evaluate: skip)
+    const prefetch = args['no-evaluate'] ? null : semanticPrefetch({ scenario, config, root })
+    const pending = []
+    const failed = []
+    const skipped = []
+    const walked = await readCaptures(run.dir)
+    const sessions = scenario.sessions || null
+    // named sessions: one isolated browser context per person and locale (cookies, storage, sign-in), created lazily
+    const sessionContexts = new Map()
+    // `account` stays the scenario's key; `credentials` resolves it in this environment (config accounts)
+    const sessionInfo = (key) => key && sessions?.[key] ? { key, title: localized(sessions[key].title, locales[0]), mailbox: sessions[key].mailbox ? expandRun(sessions[key].mailbox, run.meta.short) : null, account: sessions[key].account || null, credentials: accountFor(env, sessions[key].account, { root, config }) } : null
+    const contextFor = async (key, locale) => {
+      if (!key || !sessions?.[key]) return null
+      const id = `${key}|${locale}`
+      if (!sessionContexts.has(id)) {
+        // every context gets the environment's gate and readonly policy; an account's saved sign-in is loaded
+        const account = accountFor(env, sessions[key].account, { root, config })
+        const c = await newContext(conn ? conn.browser : ephemeral, env, { root, config, account })
+        const p = await c.newPage()
+        observeConsole(p)
+        sessionContexts.set(id, { context: c, page: p })
+        const saved = account && await access(account.storage_state).then(() => true, () => false)
+        say(`session ${key} (${locale}): new browser context${saved ? ' with the saved sign-in' : ''}`)
+      }
+      return sessionContexts.get(id)
+    }
+    // stop a session after the same failure repeats (shared precondition such as a failed sign-in);
+    // --keep-going walks every step regardless
+    const streak = failureStreak(args['keep-going'] ? 0 : 3)
+    try {
+      for (const locale of locales) {
+        // the walk owns its tab; agents and people keep theirs in the same shared browser
+        const page = await ctx.newPage()
+        if (!conn) observeConsole(page)
+        try {
+          // every locale starts as a new visitor on its first walk in the run
+          if (conn && !walked.some((c) => c.locale === locale)) { await resetSession(ctx, page, baseUrl(env, locale)); say(`session reset (new visitor, ${locale})`) }
+          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
+            if (node.session && sessions?.[node.session]?.blocked_on?.includes(env.name)) { pending.push(`${node.id} (${locale}): session ${node.session} is blocked on ${env.name}`); continue }
+            const sess = await contextFor(node.session, locale)
+            const sPage = sess ? sess.page : page
+            const sCtx = sess ? sess.context : ctx
+            if (node.kind === 'stack') {
+              try {
+                const bad = await walkStack({ node, locale, page: sPage, env, run, scenario, scenarioDir, config, consoleFile: conn && !sess ? consoleLog(root, config.output, env.name) : null, args })
+                for (const b of bad) failed.push(`${node.id} (${locale}) ${b}`)
+              } catch (error) {
+                failed.push(`${node.id} (${locale}): ${error.message.split('\n')[0]}`)
+                say(`✗ ${node.id} ${locale}: ${error.message.split('\n')[0]}`)
+              }
+              continue
+            }
+            if (node.kind === 'email' && (node.mail?.to || sessionInfo(node.session)?.mailbox)) {
+              // an e-mail node with a recipient is walked like a step: wait for the message and capture it
+              try {
+                const to = expandRun(node.mail?.to || sessionInfo(node.session).mailbox, run.meta.short)
+                const results = await captureMail({ config, root, run, env, node, locale, to, subject: localized(node.mail?.subject, locale), timeoutMs: 45000 })
+                say(`✓ ${node.id} ${locale}: "${results.subject}"`)
+              } catch (error) {
+                failed.push(`${node.id} (${locale}): ${error.message.split('\n')[0]}`)
+                say(`✗ ${node.id} ${locale}: ${error.message.split('\n')[0]}`)
+              }
+              continue
+            }
+            if (!['playwright', 'script'].includes(node.execution.strategy) || !node.execution.script) { pending.push(`${node.id} (${locale}): ${node.execution.strategy} — ${node.execution.instructions.split('\n')[0]}`); continue }
+            const streakKey = `${node.session || ''}|${locale}`
+            if (streak.stopped(streakKey)) { skipped.push(`${node.id} (${locale})`); continue }
+            try {
+              const mod = await import(pathToFileURL(resolve(scenarioDir, node.execution.script)).href)
+              // the automatic capture runs unless this script invocation captured the step itself: a crop is an
+              // attachment (#49), and a capture from an earlier walk must not stand in for this one (#50)
+              let captured = false
+              const capture = (opts = {}) => { captured = true; return captureStep({ page: sPage, node, locale, options: captureOptions(scenario, node), viewports: scopeViewports(run, opts.viewports), run, htmlView: htmlViewAllowed(env, scenario) ? { scenarioId: scenario.id } : null, consoleFile: conn && !sess ? consoleLog(root, config.output, env.name) : null, maxChars: config.evaluators?.jev?.max_state_chars, extra: node.session ? { session: node.session } : {} }).then((r) => { prefetch?.add(r, run.dir); return r }) }
+              await mod.default({ page: sPage, context: sCtx, locale, node: { id: node.id, title: localized(node.title, locale), kind: node.kind }, 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 }), acceptDialogs: () => acceptDialogs(sPage) })
+              if (!captured) await capture()
+              say(`✓ ${node.id} ${locale}`)
+              streak.ok(streakKey)
+            } catch (error) {
+              failed.push(`${node.id} (${locale}): ${error.message.split('\n')[0]}`)
+              say(`✗ ${node.id} ${locale}: ${error.message.split('\n')[0]}`)
+              if (streak.record(streakKey, error.message)) say(`  stopping ${node.session ? `session ${node.session}` : 'this walk'} (${locale}): the last 3 steps failed with the same error; fix the shared cause (sign-in, environment) and rerun, or pass --keep-going`)
+            }
+          }
+        } finally { await page.close().catch(() => {}) }
+      }
+    } finally {
+      for (const { context } of sessionContexts.values()) await context.close().catch(() => {})
+      if (conn) await conn.browser.close() // over CDP this only disconnects; the shared browser keeps running
+      if (ephemeral) await ephemeral.close()
+      await releaseLock?.()
+    }
+    if (pending.length) say(`\nSteps for an agent or a person (capture them with kaloko capture --step <id>):\n  - ${[...new Set(pending)].join('\n  - ')}`)
+    if (failed.length) { say(`\nSteps that failed (fix and rerun with --steps):\n  - ${failed.join('\n  - ')}`); process.exitCode = 1 }
+    if (skipped.length) { say(`\nSteps not walked after repeated failures (rerun with --steps once the cause is fixed):\n  - ${skipped.join('\n  - ')}`); process.exitCode = 1 }
+    if (prefetch) await walkVerdicts({ prefetch, run, scenario, config, root })
+  },
+
+  async auth (args) {
+    const { config, root } = await context(args)
+    const action = args._[0]
+    const { stat, mkdir, writeFile: write, chmod } = await import('node:fs/promises')
+    if (action === 'list') {
+      const rows = []
+      for (const name of Object.keys(config.environments)) {
+        let env
+        try { env = environment(config, name) } catch { continue }
+        for (const key of Object.keys(env.accounts || {})) {
+          const file = accountFor(env, key, { root, config }).storage_state
+          const st = await stat(file).catch(() => null)
+          rows.push(`${name.padEnd(12)} ${key.padEnd(16)} ${st ? `saved ${Math.round((Date.now() - st.mtimeMs) / 36e5)} h ago · ${relative(process.cwd(), file)}` : 'no saved session'}`)
+        }
+      }
+      say(rows.length ? rows.join('\n') : 'No accounts in kaloko.config.yml (environments.<env>.accounts).')
+      return
+    }
+    if (action !== 'save' || typeof args.env !== 'string' || typeof args.account !== 'string') throw new UserError('Usage: kaloko auth save --env <name> --account <key> [--url <url>] | kaloko auth list')
+    const env = environment(config, args.env)
+    if (env.readonly) throw new UserError(`Environment ${env.name} is readonly; saved sign-ins are for accounts on non-production environments.`)
+    const account = accountFor(env, args.account, { root, config })
+    if (!account.configured) throw new UserError(`Add the account first: environments.${env.name}.accounts.${args.account} in ${CONFIG_FILE} (it may be empty: {}).`)
+    if (!process.stdin.isTTY) throw new UserError('kaloko auth save needs a person at the terminal: they sign in in the browser window and press Enter.')
+    const { chromium } = await import('playwright')
+    const browser = await chromium.launch({ headless: false, channel: config.browser.channel || undefined })
+    try {
+      const page = await (await newContext(browser, env, { root, config })).newPage()
+      await page.goto(typeof args.url === 'string' ? args.url : baseUrl(env), { waitUntil: 'domcontentloaded' })
+      say(`Sign in as "${args.account}" on ${env.name} in the browser window (SSO, MFA as usual), then press Enter here.`)
+      await new Promise((done) => { process.stdin.resume(); process.stdin.once('data', () => { process.stdin.pause(); done() }) })
+      const state = await page.context().storageState()
+      await mkdir(join(account.storage_state, '..'), { recursive: true })
+      // cookies are credentials: owner-only file, and a .gitignore next to it
+      await write(account.storage_state, JSON.stringify(state, null, 2), { mode: 0o600 })
+      await chmod(account.storage_state, 0o600)
+      await write(join(account.storage_state, '..', '.gitignore'), '*\n').catch(() => {})
+      say(`Saved ${state.cookies.length} cookies and ${state.origins.length} origin storages → ${relative(process.cwd(), account.storage_state)}\nwalk loads it for sessions with account: ${args.account}. Sessions expire; run this again when sign-in is asked for.`)
+    } finally { await browser.close() }
+  },
+
+  async session (args) {
+    if (args._[0] !== 'reset') throw new UserError('Usage: kaloko session reset')
+    const { config, root, env } = await runContext(args)
+    const conn = await connectBrowser({ root, config, env })
+    if (!conn) throw new UserError('Start the browser first: kaloko browser start')
+    try { await resetSession(conn.context, await currentPage(conn.context), env.base_url) } finally { await conn.browser.close() }
+    say('Session reset: cookies and storage cleared (new visitor)')
+  },
+
+  async status (args) {
+    const { config, root, run, scenario, env } = await runContext(args)
+    const caps = await readCaptures(run.dir)
+    say(`Run ${run.meta.id} · ${run.meta.environment.name} · ${run.meta.scope.locales.join(', ')}`)
+    if (env.kind === 'design') {
+      // per step: unchanged / changed here / changed in the draft, from the folder and the last sync (#42)
+      const dir = designDir(env, root)
+      const local = await localRevisions({ dir, scenario, locales: run.meta.scope.locales, allLocales: run.meta.scope.locales, project: run.meta.project?.slug })
+      const branch = typeof args.branch === 'string' ? args.branch : 'main'
+      const base = (await readBase(dir))?.[`${scenario.id}@${branch}`]
+      let remote = null
+      try { remote = Object.fromEntries(((await service(config).request('GET', `/orgs/${config.org}/scenarios/${encodeURIComponent(scenario.id)}/draft?branch=${encodeURIComponent(branch)}`)).heads || []).map((h) => [headKey(h.node, h.locale, h.state), h])) } catch {}
+      say(`Design folder ${relative(process.cwd(), dir)} · draft ${remote ? `synced #${base?.seq ?? '—'}` : 'not reachable (offline or no token)'}`)
+      for (const node of scenario.nodes.filter((n) => n.kind !== 'decision' && n.kind !== 'external')) {
+        const cells = run.meta.scope.locales.map((l) => {
+          const k = headKey(node.id, l), mine = local[k]?.id, b = base?.heads?.[k], r = remote?.[k]?.revision
+          if (!mine) return `${l}:none`
+          if (r && mine === r) return `${l}:synced`
+          if (mine !== b && r && r !== b) return `${l}:CONFLICT`
+          if (mine !== b) return `${l}:changed here`
+          if (r && r !== b) return `${l}:changed in draft`
+          return `${l}:${remote ? 'new' : 'local'}`
+        })
+        const st = remote && Object.values(remote).find((h) => h.node === node.id)?.status
+        say(`  ${node.id.padEnd(28)} ${cells.join('  ')}${st ? `  [${st.replace(/_/g, ' ')}]` : ''}`)
+      }
+      return
+    }
+    for (const node of scenario.nodes.filter((n) => n.kind !== 'decision')) {
+      const got = node.kind === 'stack'
+        ? run.meta.scope.locales.map((l) => `${l}:${new Set(caps.filter((c) => c.type === 'capture' && c.node === node.id && c.locale === l && c.item).map((c) => c.item)).size}`)
+        : run.meta.scope.locales.map((l) => caps.some((c) => c.type === 'capture' && c.node === node.id && c.locale === l) ? l : '·'.repeat(l.length))
+      say(`  ${node.id.padEnd(28)} ${node.kind.padEnd(8)} ${(node.execution?.strategy || (node.kind === 'stack' ? 'pages' : '')).padEnd(10)} ${got.join(' ')}`)
+    }
+  },
+
+  async evaluate (args) {
+    const { config, root, run, scenario, env } = await runContext(args)
+    if (args.recheck) {
+      const r = await recheckCaptures({ run, scenario, config, root, env, only: list(args.steps) })
+      say(`Rechecked deterministic criteria of ${r.rechecked} capture(s) from the stored HTML (console, overflow and performance keep their live result).`)
+      if (r.skipped.length) say(`  skipped: ${r.skipped.join('; ')}`)
+    }
+    const report = await evaluateRun({ run, scenario, config, root })
+    const via = report.via.qawalk ? ` via Kaloko${report.hosted?.limit != null ? ` (${report.hosted.questions} of ${report.hosted.limit} questions this month)` : ''}` : report.via['own-key'] ? ' with your key' : ''
+    say(`Evaluated ${report.evaluated} capture(s); semantic evaluator ${report.model}${via}: ${report.semantic_calls} call(s), ${report.semantic_cached} cached.`)
+    if (report.skipped.length) {
+      // one line per reason: "12 captures: TYPESAFE_API_KEY is not set …"
+      const byReason = new Map()
+      for (const x of report.skipped) { const [where, ...why] = x.split(': '); const k = why.join(': '); byReason.set(k, [...(byReason.get(k) || []), where]) }
+      say(`Semantic criteria not evaluated:\n  - ${[...byReason].slice(0, 8).map(([why, where]) => `${where.length > 1 ? `${where.length} captures (${where.slice(0, 3).join(', ')}${where.length > 3 ? ', …' : ''})` : where[0]}: ${why}`).join('\n  - ')}`)
+    }
+    if (report.outdated.length) say(`Criteria changed after capture of ${report.outdated.join(', ')}: not evaluated. Run "kaloko evaluate --recheck --steps ${report.outdated.join(',')}" (deterministic, from the stored HTML) or walk those steps again.`)
+  },
+
+  async build (args) {
+    const { config, root, run, scenario } = await runContext(args)
+    const manifest = await buildManifest({ run, scenario, config, root, catalog: await catalogFor(config, root) })
+    const file = await writePreview({ run, manifest })
+    const s = manifest.summary
+    say(`${manifest.id}: ${s.pass} pass · ${s.partial} partial · ${s.fail} fail · ${s.skip} not checked\nPreview: ${file}`)
+    return file
+  },
+
+  async preview (args) {
+    const file = await commands.build(args)
+    say(pathToFileURL(file).href)
+  },
+
+  async share (args) {
+    const { config, root, run, scenario, env } = await runContext(args)
+    const client = service(config)
+    // on a design environment, share publishes a version of the flow from the shared draft (#42)
+    if (env.kind === 'design') {
+      const r = await syncDesign({ config, root, run, scenario, env, client, args: { ...args, strict: true }, say, pull: false, render: (steps) => walkDesign({ config, root, run, scenario, env, pick: steps, locales: run.meta.scope.locales, viewports: run.meta.scope.viewports, say }).then(() => evaluateRun({ run, scenario, config, root })) })
+      if (r.conflicts) return
+      const v = await publishVersion({ config, scenario, client, args, say })
+      const meta = await readJson(join(run.dir, 'meta.json'))
+      meta.shared = { url: v.url, at: new Date().toISOString(), version: v.version, run: v.id }
+      await writeFile(join(run.dir, 'meta.json'), JSON.stringify(meta, null, 2) + '\n')
+      return
+    }
+    const manifest = await buildManifest({ run, scenario, config, root, catalog: [] })
+    await writePreview({ run, manifest })
+    const files = new Set()
+    for (const n of manifest.nodes) {
+      for (const byVp of Object.values(n.captures || {})) for (const c of Object.values(byVp)) [c.image || c.png, c.thumb, c.html, c.eval, c.tree].filter(Boolean).forEach((p) => files.add(p))
+      for (const a of n.attachments || []) files.add(a.file)
+      // stack steps: the items index and every page's files
+      if (n.stack?.items) {
+        files.add(n.stack.items)
+        const idx = await readJson(join(run.dir, n.stack.items), { items: [] })
+        for (const it of idx.items) for (const byVp of Object.values(it.captures || {})) for (const c of Object.values(byVp)) [c.png, c.thumb, c.html, c.eval].filter(Boolean).forEach((p) => files.add(p))
+      }
+    }
+    const days = Number(args.expires) || config.share?.expires_days || 30
+    const { stat } = await import('node:fs/promises')
+    let total = 0
+    for (const p of files) total += (await stat(join(run.dir, p))).size
+    try {
+      const u = await client.request('GET', `/orgs/${config.org}/usage`)
+      if (total > u.limits.max_run_bytes) throw new UserError(`This run is ${fmtBytes(total)}; the limit per run is ${fmtBytes(u.limits.max_run_bytes)}. Capture fewer viewports or locales, or ask an admin for a higher limit.`)
+      if (u.usage.bytes + total > u.limits.quota_bytes) throw new UserError(`Storage quota would be exceeded: ${fmtBytes(u.usage.bytes)} used + ${fmtBytes(total)} > ${fmtBytes(u.limits.quota_bytes)}. Delete old runs in Settings or ask for a higher quota.`)
+      say(`Uploading ${files.size} files, ${fmtBytes(total)} (organization uses ${fmtBytes(u.usage.bytes)} of ${fmtBytes(u.limits.quota_bytes)})`)
+    } catch (e) { if (e instanceof UserError && /limit|quota/.test(e.message)) throw e }
+    const created = await client.request('POST', `/orgs/${config.org}/runs?expires_days=${days}`, manifest)
+    // text files travel and rest gzip-compressed; the service serves them with Content-Encoding: gzip
+    const body = async (p) => { const raw = await readFile(join(run.dir, p)); const gz = /\.(html|json)$/.test(p) && raw.length > 512; return { data: gz ? gzipSync(raw, { level: 6 }) : raw, gz } }
+    // the file list goes first: the service checks limits once and each upload is then a plain write
+    // (an older service without the plan answers 404/405 and every upload checks itself, as before)
+    if (files.size > 20) {
+      const plan = []
+      for (const p of files) plan.push({ path: p, bytes: (await body(p)).data.length })
+      await client.request('POST', `/orgs/${config.org}/runs/${manifest.id}/files`, { files: plan }).catch((e) => { if (!/HTTP (404|405)/.test(e.message)) throw e })
+    }
+    const queue = [...files]
+    let done = 0
+    const worker = async () => {
+      while (queue.length) {
+        const p = queue.shift()
+        const { data, gz } = await body(p)
+        await client.upload(`/orgs/${config.org}/runs/${manifest.id}/files/${p.split('/').map(encodeURIComponent).join('/')}`, data, p, gz ? { 'Content-Encoding': 'gzip' } : {})
+        done++
+        if (done % 10 === 0 || done === files.size) process.stdout.write(`\r  uploaded ${done}/${files.size}`)
+      }
+    }
+    await Promise.all(Array.from({ length: files.size > 200 ? 12 : 6 }, worker))
+    if (files.size) process.stdout.write('\n')
+    // experimental HTML views (#42): their bundles travel as blobs and attach to the run as revisions
+    const viewIds = new Set(manifest.nodes.flatMap((n) => Object.values(n.captures || {}).flatMap((vps) => Object.values(vps).map((c) => c.view?.revision).filter(Boolean))))
+    if (viewIds.size) {
+      const revs = []
+      for (const id of viewIds) { const r = await readJson(join(run.dir, 'views', `${id}.json`), null); if (r) revs.push(r) }
+      const blobs = new Map()
+      for (const r of revs) for (const [p, h] of Object.entries(r.files)) blobs.set(h, { abs: join(run.dir, 'live', r.id, p), ext: p.split('.').pop() })
+      try {
+        await uploadBlobs({ client, org: config.org, files: blobs, say })
+        await client.request('POST', `/orgs/${config.org}/runs/${manifest.id}/views`, { revisions: revs.map(({ sizes, ...r }) => r) })
+        say(`Attached ${revs.length} HTML view(s).`)
+      } catch (e) { say(`HTML views not attached: ${e.message.split('\n')[0]}`) }
+    }
+    const fin = await client.request('POST', `/orgs/${config.org}/runs/${manifest.id}/finalize`)
+    const meta = await readJson(join(run.dir, 'meta.json'))
+    meta.shared = { url: fin.url, at: new Date().toISOString(), expires_days: created.expires_days }
+    await writeFile(join(run.dir, 'meta.json'), JSON.stringify(meta, null, 2) + '\n')
+    say(`Shared ${manifest.id} (${files.size} files, expires in ${created.expires_days} days)\n${fin.url}`)
+    const capped = expiryNote(days, created.expires_days)
+    if (capped) say(`Note: ${capped}`)
+    if (args.pr) {
+      const r = await upsertPrComment({ manifest, url: fin.url, cwd: root })
+      say(r.ok ? `PR comment ${r.action}: ${r.url}` : `PR comment skipped: ${r.reason}.`)
+    }
+  },
+
+  async sync (args) {
+    const { config, root, run, scenario, env } = await runContext(args)
+    const client = service(config)
+    await syncDesign({ config, root, run, scenario, env, client, args, say, push: !args.pull, pull: !args.push, render: (steps) => walkDesign({ config, root, run, scenario, env, pick: steps, locales: run.meta.scope.locales, viewports: run.meta.scope.viewports, say }).then(() => evaluateRun({ run, scenario, config, root })) })
+  },
+
+  async history (args) {
+    const { config, root } = await context(args)
+    const scenarioId = await scenarioIdOf(args, config, root)
+    await historyCmd({ config, scenarioId, client: service(config), args, say })
+  },
+
+  async reference (args) {
+    const { config, root } = await context(args)
+    const scenarioId = await scenarioIdOf(args, config, root)
+    await referenceCmd({ config, scenarioId, client: service(config), args, say })
+  },
+
+  async branch (args) {
+    const { config, root } = await context(args)
+    const scenarioId = await scenarioIdOf(args, config, root)
+    await branchCmd({ config, scenarioId, client: service(config), args, say })
+  },
+
+  async tokens (args) {
+    const { config, root } = await context(args)
+    let env = typeof args.env === 'string' ? environment(config, args.env) : null
+    if (!env) { try { const r = await resolveRun({ root, output: config.output, run: args.run }); env = environment(config, r.meta.environment.name) } catch {} }
+    if (!env) env = Object.keys(config.environments).map((n) => environment(config, n)).find((e) => e.kind === 'design') || null
+    const needsService = args._[0] !== 'check'
+    await tokensCmd({ config, root, env, client: needsService ? service(config) : null, args, say, project: typeof args.project === 'string' ? args.project : config.project })
+  },
+
+  async feedback (args) {
+    const { config, root } = await context(args)
+    const client = service(config)
+    // on a design environment the feedback is the draft's comments, pinned ones with their element (#42)
+    let designRun = null
+    try { const r = await resolveRun({ root, output: config.output, run: args.run }); if (r.meta.environment.kind === 'design') designRun = r } catch {}
+    if (designRun && !args.scenario) {
+      const branch = typeof args.branch === 'string' ? args.branch : 'main'
+      const items = await client.request('GET', `/orgs/${config.org}/scenarios/${encodeURIComponent(designRun.meta.scenario.id)}/draft/reviews?branch=${encodeURIComponent(branch)}`)
+      if (args.json) { say(JSON.stringify(items, null, 2)); return }
+      const open = items.filter((r) => !r.resolved_at && r.status !== 'approved')
+      say(`Draft feedback for ${designRun.meta.scenario.id}${branch !== 'main' ? `@${branch}` : ''}: ${open.length} open`)
+      for (const r of open) say(`  ${r.status === 'rejected' ? '✕' : '•'} ${r.node_id}${r.locale ? ` [${r.locale}]` : ''}${r.anchor?.selector ? ` on ${r.anchor.selector}` : ''} — ${r.email}${r.agent ? ` via ${r.agent}` : ''}: ${r.note}`)
+      return
+    }
+    let runId = args.run
+    let scenarioId = args.scenario
+    if (!runId && !scenarioId) {
+      try { const r = await resolveRun({ root, output: config.output }); if (r.meta.shared) runId = r.meta.id; else scenarioId = r.meta.scenario.id } catch {}
+    }
+    const q = new URLSearchParams({ run: runId || 'latest', ...(scenarioId ? { scenario: scenarioId } : {}) })
+    const data = await client.request('GET', `/orgs/${config.org}/feedback?${q}`)
+    if (args.json) { say(JSON.stringify(data, null, 2)); return }
+    if (!data.run) { say('No published run found.'); return }
+    say(`Feedback for ${data.run.id} (${data.scenario}) — run verdict: ${data.verdict?.verdict || 'pending'}${data.verdict?.by ? ` by ${data.verdict.by}` : ''}${data.verdict?.note ? `: ${data.verdict.note}` : ''}${data.verdict?.awaiting?.length ? `\n  awaiting approval from: ${data.verdict.awaiting.join(', ')}` : ''}${data.approved.length ? `\n  approved: ${data.approved.join(', ')}` : ''}`)
+    for (const c of data.criterion_verdicts || []) say(`  ✕ ${c.node_id} ${c.criterion_id}${c.locale ? ` [${c.locale}]` : ''} — ${c.email}: ${c.note}`)
+    const thread = (r, where) => {
+      say(`  ${r.status === 'rejected' ? '✕' : '•'} [${r.id}] ${where}${r.locale ? ` [${r.locale}]` : ''}${r.pin ? ` · pinned at ${Math.round(r.pin.x * 100)}%,${Math.round(r.pin.y * 100)}%${r.pin.viewport ? ` (${r.pin.viewport})` : ''}` : ''}${r.anchor?.selector ? ` · on ${r.anchor.selector}` : ''} — ${r.email}${r.agent ? ` via ${r.agent}` : ''}: ${r.note}`)
+      for (const x of r.replies || []) say(`      ↳ ${x.email}${x.agent ? ` via ${x.agent}` : ''}: ${x.deleted ? '(deleted)' : x.note}`)
+    }
+    const flow = data.flow_comments || []
+    if (!data.items.length && !flow.length) { say('  No open rejections or comments.'); return }
+    for (const r of data.items) thread(r, r.node_id ? `step ${r.node_id}` : 'whole run')
+    for (const r of flow) thread(r, 'whole flow')
+    say(`\nAnswer with: kaloko comment --reply <id> --note "…"; close with: kaloko comment --resolve <id> --note "Fixed in <commit>"${flow.length ? ' (add --flow for flow comments)' : ''}`)
+  },
+
+  /**
+   * Comments from the CLI: on a step (--step), the whole run (default) or the whole flow (--flow); reply, resolve
+   * (with a closing note), reopen, edit and delete by id. Targets the shared run (--run, default the current one).
+   */
+  async comment (args) {
+    const { config, root } = await context(args)
+    const client = service(config)
+    let runId = typeof args.run === 'string' ? args.run : null
+    let scenarioId = typeof args.scenario === 'string' ? args.scenario : null
+    if (!runId || !scenarioId) { try { const r = await resolveRun({ root, output: config.output, run: runId || undefined }); if (!runId && r.meta.shared) runId = r.meta.id; scenarioId ||= r.meta.scenario.id } catch {} }
+    const flow = !!args.flow
+    if (flow && !scenarioId) throw new UserError('--flow needs a scenario: pass --scenario <id> or run it in a project with a current run.')
+    if (!flow && !runId) throw new UserError('No shared run: pass --run <id>, share the current run first, or use --flow for the whole flow.')
+    const base = flow ? `/orgs/${config.org}/scenarios/${encodeURIComponent(scenarioId)}/comments` : `/orgs/${config.org}/runs/${runId}/comments`
+    const note = typeof args.note === 'string' ? args.note : ''
+    const where = flow ? `flow ${scenarioId}` : `run ${runId}`
+    if (typeof args.resolve === 'string') { await client.request('POST', `${base}/${encodeURIComponent(args.resolve)}/resolve`, { note }); say(`✓ resolved ${args.resolve} (${where})${note ? ` with: ${note}` : ''}`); return }
+    if (typeof args.reopen === 'string') { await client.request('POST', `${base}/${encodeURIComponent(args.reopen)}/reopen`, {}); say(`✓ reopened ${args.reopen}`); return }
+    if (typeof args.delete === 'string') { const r = await client.request('DELETE', `${base}/${encodeURIComponent(args.delete)}`); say(`✓ deleted ${args.delete}${r.kept ? ' (kept as "deleted" because others replied)' : ''}`); return }
+    if (typeof args.edit === 'string') { await client.request('PATCH', `${base}/${encodeURIComponent(args.edit)}`, { note }); say(`✓ edited ${args.edit}`); return }
+    if (!note.trim()) throw new UserError('Write the comment with --note "…".')
+    const status = ['rejected', 'approved'].includes(args.status) ? args.status : 'comment'
+    const body = { note, status, node_id: typeof args.step === 'string' ? args.step : '', ...(typeof args.reply === 'string' ? { parent_id: args.reply } : {}), ...(typeof args.locale === 'string' ? { locale: args.locale } : {}) }
+    const c = await client.request('POST', base, body)
+    say(`✓ ${args.reply ? `replied to ${args.reply}` : `commented on ${body.node_id ? `step ${body.node_id} of ` : 'the whole '}${where}`} [${c.id}]`)
+  },
+
+  async runs (args) {
+    const { config } = await context(args)
+    const client = service(config)
+    const all = !!args.all || typeof args.scenario === 'string'
+    const q = new URLSearchParams({ ...(all ? {} : { latest: '1' }), ...(typeof args.scenario === 'string' ? { scenario: args.scenario } : {}), ...(typeof args.environment === 'string' ? { environment: args.environment } : {}), limit: '300' })
+    const runs = await client.request('GET', `/orgs/${config.org}/runs?${q}`)
+    if (args.json) { say(JSON.stringify(runs, null, 2)); return }
+    if (!runs.length) { say('No shared runs match.'); return }
+    for (const r of runs) {
+      const s = r.summary || {}
+      say(`${r.id}  ${r.environment?.name || ''}  ${r.verdict || 'pending'}${r.kept ? ' · kept' : ''}  ${s.pass || 0}✓ ${s.partial || 0}◐ ${s.fail || 0}✕  ${r.author || ''}${r.older ? `  + ${r.older} older` : ''}`)
+    }
+    if (!all) say(`\nNewest run per scenario; --all or --scenario <id> lists every run.`)
+  },
+
+  async trash (args) {
+    const { config } = await context(args)
+    if (!args._.length) throw new UserError('Usage: kaloko trash <run-id>...')
+    const client = service(config)
+    for (const id of args._) { await client.request('DELETE', `/orgs/${config.org}/runs/${encodeURIComponent(id)}`); say(`✓ ${id} moved to the trash (kaloko restore ${id} brings it back)`) }
+  },
+
+  async restore (args) {
+    const { config } = await context(args)
+    if (args._.length !== 1) throw new UserError('Usage: kaloko restore <run-id>')
+    await service(config).request('POST', `/orgs/${config.org}/runs/${encodeURIComponent(args._[0])}/restore`, {})
+    say(`✓ ${args._[0]} restored`)
+  },
+
+  async prune (args) {
+    const { config } = await context(args)
+    const days = typeof args['older-than'] === 'string' ? Number(args['older-than'].replace(/d$/, '')) : null
+    if (days != null && !Number.isInteger(days)) throw new UserError('--older-than takes days, e.g. 14d.')
+    const body = { dry_run: !args.yes, keep_latest: args.keep === undefined ? 3 : Number(args.keep), ...(typeof args.scenario === 'string' ? { scenario: args.scenario } : {}), ...(typeof args.environment === 'string' ? { environment: args.environment } : {}), ...(typeof args.project === 'string' ? { project: args.project } : {}), ...(days != null ? { older_than_days: days } : {}) }
+    const r = await service(config).request('POST', `/orgs/${config.org}/runs/prune`, body)
+    if (args.json) { say(JSON.stringify(r, null, 2)); return }
+    if (!r.trash.length) { say(`Nothing to clean up (keeping the newest ${r.keep_latest} per scenario and environment).`); return }
+    say(`${r.dry_run ? 'Would move' : 'Moved'} ${r.trash.length} run(s) to the trash:`)
+    for (const x of r.trash) say(`  ${x.id}  ${x.environment}  ${x.uploaded_by}`)
+    const others = r.kept.filter((x) => x.reason === 'uploaded by someone else').length
+    if (others) say(`${others} older run(s) of other people stay (only an admin prunes them).`)
+    if (r.dry_run) say('Dry run: nothing changed. Add --yes to move them to the trash (restorable until purge).')
+  },
+
+  async keep (args) {
+    const { config } = await context(args)
+    if (args._.length !== 1) throw new UserError('Usage: kaloko keep <run-id> [--off]')
+    const r = await service(config).request('POST', `/orgs/${config.org}/runs/${encodeURIComponent(args._[0])}/keep`, { keep: !args.off })
+    say(r.kept ? `✓ ${args._[0]} is kept: it never expires and is never pruned` : `✓ ${args._[0]} is no longer kept`)
+  },
+
+  async archive (args) {
+    const { config } = await context(args)
+    if (args._.length !== 1) throw new UserError('Usage: kaloko archive <scenario-id> [--undo]')
+    await service(config).request('POST', `/orgs/${config.org}/scenarios/${encodeURIComponent(args._[0])}/${args.undo ? 'unarchive' : 'archive'}`, {})
+    say(args.undo ? `✓ ${args._[0]} is active again` : `✓ ${args._[0]} archived: hidden from the scenario list, its runs stay reachable (kaloko archive ${args._[0]} --undo)`)
+  },
+
+  async inbox (args) {
+    const { config } = await context(args)
+    const client = service(config)
+    const q = new URLSearchParams(args.all ? {} : { unread: '1' })
+    const data = await client.request('GET', `/orgs/${config.org}/notifications?${q}`)
+    if (args.json) say(JSON.stringify(data, null, 2))
+    else {
+      say(`Inbox for ${config.org}: ${data.unread} unread${args.all ? `, showing ${data.items.length}` : ''}`)
+      const line = (n) => { const d = n.detail || {}; const who = n.actor ? `${n.actor}: ` : ''; const where = n.run_id ? ` (${n.run_id}${n.node_id ? `#${n.node_id}` : ''})` : ''; return `${n.read ? ' ' : '•'} ${n.created_at.slice(0, 16).replace('T', ' ')} ${n.type} ${who}${[d.scenario, d.node, d.note, d.email, d.domain, d.expires_at && `expires ${d.expires_at.slice(0, 10)}`].filter(Boolean).join(' · ')}${where}` }
+      for (const n of data.items) say(line(n))
+    }
+    if (args.read && data.items.some((n) => !n.read)) {
+      const r = await client.request('POST', `/orgs/${config.org}/notifications`, { read: data.items.filter((n) => !n.read).map((n) => n.id) })
+      say(`Marked ${r.read} read.`)
+    }
+  },
+
+  async projects (args) {
+    const { config } = await context(args)
+    const data = await service(config).request('GET', `/orgs/${config.org}/projects`)
+    if (args.json) { say(JSON.stringify(data, null, 2)); return }
+    if (!data.length) { say('No projects yet. Create one in Settings → Projects or with POST /api/v1/orgs/<org>/projects.'); return }
+    for (const p of data) say(`${p.slug.padEnd(24)} ${p.name}${p.adhoc ? ' (from runs only)' : ''}  ${p.scenarios} scenario(s), ${p.runs} run(s)${config.project === p.slug ? '  ← this config' : ''}`)
+  },
+
+  async compare (args) {
+    const { config, root } = await context(args)
+    const { readJson } = await import('./lib/util.mjs')
+    let client = null
+    const remote = async (id) => { client ||= service(config); return client.request('GET', `/orgs/${config.org}/runs/${id}`) }
+    // a run is read locally when its directory has a manifest, otherwise from the service
+    const load = async (id) => {
+      if (!id) return null
+      const local = await readJson(id.includes('/') ? resolve(id, 'run.json') : join(root, config.output, id, 'run.json'), null)
+      return local || remote(id)
+    }
+    let runId = args.run
+    if (!runId) { try { runId = (await resolveRun({ root, output: config.output })).meta.id } catch {} }
+    if (!runId) throw new UserError('--run <id> is required when there is no current run.')
+    const run = await load(runId)
+    if (!run) throw new UserError(`Run ${runId} not found locally or on the service.`)
+    let baseId = typeof args.baseline === 'string' ? args.baseline : null
+    // --design: against the design reference of the scenario (#42)
+    if (args.design && run.scenario?.id) { client ||= service(config); baseId = (await client.request('GET', `/orgs/${config.org}/scenarios/${encodeURIComponent(run.scenario.id)}/references`)).design; if (!baseId) throw new UserError('This scenario has no design reference yet (kaloko reference --design --version <n>).') }
+    if (!baseId) {
+      // the service knows the scenario baseline; locally fall back to the previous run of the scenario
+      if (!run.baseline_id && run.scenario?.id) { try { run.baseline_id = (await remote(runId)).baseline_id } catch {} }
+      baseId = run.baseline_id && run.baseline_id !== run.id ? run.baseline_id : (run.history || []).filter((h) => h.started_at < run.started_at).sort((a, b) => b.started_at.localeCompare(a.started_at))[0]?.id
+      if (!baseId) { const others = (await listRuns(root, config.output)).filter((r) => r.scenario?.id === run.scenario?.id && r.id !== run.id && r.started_at < run.started_at).sort((a, b) => b.started_at.localeCompare(a.started_at)); baseId = others[0]?.id }
+    }
+    if (!baseId) throw new UserError('No baseline or earlier run of this scenario to compare with; pass --baseline <id>.')
+    const base = await load(baseId)
+    if (!base) throw new UserError(`Run ${baseId} not found locally or on the service.`)
+    const d = compareRuns(run, base)
+    if (args.json) { say(JSON.stringify(d, null, 2)); return }
+    say(formatComparison(d))
+    if (config.share?.url && run.org) say(`\nCanvas: ${config.share.url.replace(/\/$/, '')}/${run.org}/runs/${run.id}/#cmp=${base.id}`)
+  },
+
+  async draft (args) {
+    const { root } = await context(args).catch(() => ({ root: process.cwd() }))
+    const urls = args._.filter((u) => /^https?:\/\//.test(u))
+    if (!urls.length) throw new UserError('Usage: kaloko draft <url> [url…] (public pages of one site)')
+    const pages = []
+    for (const url of urls) {
+      let facts = {}
+      try { const res = await fetch(url, { headers: { 'User-Agent': 'Kaloko-draft/1 (+https://kaloko.app)' }, redirect: 'follow', signal: AbortSignal.timeout(10000) }); facts = pageFacts(await res.text()); say(`  ${res.status} ${url}${facts.title ? ` — ${facts.title}` : ''}`) } catch (e) { say(`  ✕ ${url}: ${e.message} (drafted from the URL only)`) }
+      pages.push({ url, facts })
+    }
+    let draft
+    try { draft = draftScenario(pages, { id: typeof args.id === 'string' ? args.id : undefined, title: typeof args.title === 'string' ? args.title : undefined }) } catch (e) { throw new UserError(e.message) }
+    const file = resolve(root, typeof args.out === 'string' ? args.out : join('qa', 'flows', `${new URL(draft.origin).hostname.replace(/^www\./, '').replace(/[^a-z0-9]+/gi, '-')}.yml`))
+    const planFile = file.replace(/\.ya?ml$/, '') + '.ACCEPTANCE.md'
+    draft.scenario.source = relative(root, planFile)
+
+    for (const f of [file, planFile]) if (existsSync(f) && !args.force) throw new UserError(`${relative(process.cwd(), f)} exists; pass --force to overwrite.`)
+    const problems = validateScenario(JSON.parse(JSON.stringify(draft.scenario)))
+    if (problems.length) throw new UserError(`Draft did not validate:\n  - ${problems.join('\n  - ')}`)
+    await mkdir(join(dirname(file), 'steps'), { recursive: true })
+    await writeFile(file, scenarioYaml(draft.scenario))
+    await writeFile(planFile, draft.plan)
+    const consent = join(dirname(file), 'steps', 'consent.mjs'); const open = join(dirname(file), 'steps', 'open.mjs')
+    if (!existsSync(consent)) await writeFile(consent, await readFile(join(packageRoot, 'templates', 'steps', 'consent.mjs'), 'utf8'))
+    if (!existsSync(open)) await writeFile(open, "// Opens the step's page (kaloko draft).\nexport default async ({ page, url }) => { await page.goto(url(), { waitUntil: 'domcontentloaded' }) }\n")
+    say(`Drafted ${draft.scenario.nodes.length} step(s) of ${draft.origin}\n  scenario: ${relative(process.cwd(), file)}\n  plan:     ${relative(process.cwd(), planFile)}\nNext: sharpen the purposes and criteria, make sure environments.production.base_url is ${draft.origin} (readonly: true), then kaloko start --scenario ${relative(process.cwd(), file)} --env production`)
+  },
+
+  async calibrate (args) {
+    const { config } = await context(args)
+    const thresholds = { ...JEV_DEFAULTS.thresholds, ...(config.evaluators?.jev?.thresholds || {}) }
+    const cases = []
+    if (typeof args.golden === 'string') cases.push(...await casesFromGolden(resolve(args.golden)))
+    if (typeof args.scenario === 'string') {
+      const client = service(config)
+      const runs = await client.request('GET', `/orgs/${config.org}/runs?scenario=${encodeURIComponent(args.scenario)}&limit=${Number(args.limit) || 30}`)
+      for (const r of runs) {
+        const m = await client.request('GET', `/orgs/${config.org}/runs/${r.id}`)
+        cases.push(...casesFromRun(m, m.criterion_verdicts))
+      }
+    }
+    if (!cases.length) {
+      throw new UserError(typeof args.scenario === 'string'
+        ? `No labelled cases in the last ${Number(args.limit) || 30} runs of ${args.scenario}: reviewers have not set pass/fail on semantic criteria yet (lightbox → criterion → Pass/Fail), or pass --golden labels.yml.`
+        : 'No labelled cases. Pass --golden labels.yml or --scenario <id> (reviewers set pass/fail on semantic criteria in the canvas).')
+    }
+    const report = calibrate(cases, thresholds, { target: Number(args.target) || 0.95 })
+    say(args.json ? JSON.stringify(report, null, 2) : formatCalibration(report))
+  },
+
+  async export (args) {
+    const { config, root } = await context(args)
+    const client = service(config)
+    if (args.live) {
+      const scenarioId = await scenarioIdOf(args, config, root)
+      let out = typeof args.out === 'string' ? resolve(args.out) : null
+      if (!out) { const d = Object.keys(config.environments).map((n) => environment(config, n)).find((e) => e.kind === 'design'); out = d ? designDir(d, root) : resolve(root, 'design') }
+      await exportLive({ config, scenarioId, client, args, say, out })
+      return
+    }
+    if (typeof args.scenario === 'string') return exportScenario({ args, config, root, client })
+    let runId = args.run
+    if (!runId) { try { runId = (await resolveRun({ root, output: config.output })).meta.id } catch {} }
+    if (!runId || !/^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9-]+$/.test(runId)) throw new UserError('--run <id> is required (a shared run id).')
+    const out = typeof args.out === 'string' ? resolve(args.out) : resolve(root, config.output, `${runId}.zip`)
+    const { createWriteStream } = await import('node:fs')
+    const { Readable } = await import('node:stream')
+    const { pipeline } = await import('node:stream/promises')
+    const res = await client.fetch(`/orgs/${config.org}/runs/${runId}/export.zip`)
+    await pipeline(Readable.fromWeb(res.body), createWriteStream(out))
+    const { size } = await (await import('node:fs/promises')).stat(out)
+    say(`Exported ${runId} → ${out} (${fmtBytes(size)})`)
+  },
+
+  async public (args) {
+    const { config, root } = await context(args)
+    const client = service(config)
+    let runId = args.run
+    if (!runId) { try { runId = (await resolveRun({ root, output: config.output })).meta.id } catch {} }
+    if (!runId || !/^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9-]+$/.test(runId)) throw new UserError('--run <id> is required (a shared run id).')
+    const r = await client.request('POST', `/orgs/${config.org}/runs/${runId}/public`, { public: !args.off })
+    say(r.public ? `Public: ${r.url} (readable without sign-in; only one public run per scenario)` : `Private again: ${runId}`)
+  },
+
+  async doctor (args) {
+    const { config, root } = await context(args)
+    const r = await doctor({ config, root, fix: !!args.fix })
+    say(args.json ? JSON.stringify(r, null, 2) : formatDoctor(r))
+    if (!r.ok) process.exitCode = 1
+  },
+
+  async help () { say(HELP) }
+}
+
+export async function main (argv) {
+  const args = parse(argv)
+  const name = args._.shift() || 'help'
+  const cmd = commands[name] || (args.help ? commands.help : null)
+  if (!cmd) { console.error(`Unknown command "${name}".\n`); say(HELP); process.exitCode = 2; return }
+  try {
+    await cmd(args)
+  } catch (error) {
+    if (error instanceof UserError) { console.error(error.message); process.exitCode = 1 } else throw error
+  }
+}