kaloko 0.5.0 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaloko",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "See what your AI agents built: every screen, language and device walked, assessed and approved on one canvas.",
   "keywords": [
     "qa",

package/skills/kaloko/SKILL.md

@@ -52,7 +52,8 @@ Start the shared browser, walk a scenario on a non-production environment,
 create test data there (users, roles, carts), capture screens and e-mails,
 evaluate, build the preview, and fix scenario mechanics (selectors, scripts)
 that do not change what is being accepted, including applying a selector
-proposal with `kaloko walk --heal` when it names the same element. Walk only
+proposal with `kaloko walk --heal` when it names the same element, and pulling
+the regions people drew to ignore into the scenario (`kaloko stability --pull`). Walk only
 the steps a change reaches (`--affected`) and import screenshots into a run. Record steps locally
 (`walk --record`) when a screenshot cannot show what a person has to judge, read traces, and
 export a walkthrough video into the run folder. On a design environment: change
@@ -73,7 +74,8 @@ a whole project (`capture.record` in the config: storage), a real clean-up
 anything the environment profile blocks. Never trash an accepted run, a
 baseline, a run with review comments, or a run linked from an open PR or issue
 comment. Never approve a
-step or accept a run on a person's behalf; report what waits for them
+step or accept a run on a person's behalf, and never hand out a signed
+acceptance record (`kaloko signoff`) for a run a person has not accepted; report what waits for them
 (`kaloko review`, MCP `get_review_queue`) instead. Ask the person
 for secret values (passwords, tokens, gate credentials) and for sign-ins only
 they can do; never write secrets into the config, a scenario or a script.

package/skills/kaloko/reference/acceptance.md

@@ -342,5 +342,7 @@ design pixel check (`AC801`) leave them out:
 
 Do not guess them: `kaloko walk --stability 3` notes what moves while the
 page sits still, and `kaloko stability` compares the step with earlier runs
-and writes suggestions (see [execution.md](execution.md)). Ignore only noise;
-a region that matters to a criterion stays in.
+and writes suggestions (see [execution.md](execution.md)). Reviewers can also
+draw a region on a screenshot on kaloko.app; `kaloko stability --pull` writes
+those into `ignore:`. Ignore only noise; a region that matters to a criterion
+stays in.

package/skills/kaloko/reference/collaboration.md

@@ -72,8 +72,11 @@ comments; at the end they accept or return the run.
 Comments are threads in three places:
 
 - **A step:** optionally pinned to a position on the screenshot
-  (`pin: {x, y}` as fractions, per viewport) or to an element of a live
-  design step (`anchor`).
+  (`pin: {x, y}` as fractions, per viewport), drawn on it (a box, an arrow or
+  a line: `shape`, with `region` giving the area as fractions and in CSS
+  pixels of the page, and for an arrow the point it aims at), or attached to
+  an element of a live design step (`anchor`). Comments may carry images
+  (`attachments`, each with a download URL that needs the token).
 - **The whole run:** `node_id` is `''`.
 - **The whole flow:** these stay across runs, e.g. "add the empty-cart
   state".
@@ -85,8 +88,12 @@ said what.
 
 The loop, for every open thread:
 
-1. **Understand it.** Open the canvas link when a pin or an element
-   matters; the position is on the screenshot of that viewport and locale.
+1. **Understand it.** A `region` says exactly where to look: `px` is
+   `[x, y, width, height]` in CSS pixels of the captured page for that
+   viewport (`region.viewport`) and locale; find the element there in the
+   step's HTML or screenshot. Download attached images (a corrected copy, a
+   reference) before you change anything. Open the canvas link when a pin or
+   an element matters.
 2. **Fix it** in the code or the scenario. When the comment asks for a
    change of intent (criteria, scope), ask the person first.
 3. **Answer and close.** Use
@@ -181,14 +188,25 @@ e-mail works too). Use it when a step needs a decision from a specific person
   Put the relevant lines in the issue comment. On the canvas the same
   comparison is the **Compare** selector in the top bar (or `#cmp=<run>` in
   the URL): pixel differences per step, changed criteria, and a side-by-side
-  or diff view in the lightbox. Pixel diffs are computed in the browser;
-  nothing is uploaded.
+  or diff view in the lightbox, plus *Swipe* (a divider dragged across both
+  screenshots) and *Onion skin* (this run faded over the other). Pixel diffs
+  are computed in the browser; nothing is uploaded. **G** opens the grid: one
+  step in every locale and viewport at once, failing cells marked.
 - **Manual criteria** are decided on the canvas by a reviewer; treat a
   reviewer's `fail` like a failing deterministic check.
 - Admins may name **required approvers** per scenario (Settings). Such a
   run stays `pending` until every one of them approved; `kaloko feedback`
   prints `awaiting approval from: …`, so do not treat a single approval as
   acceptance there.
+- An accepted run has a **signed acceptance record** (Business and up): the
+  run, scenario, commit and environment, who approved what and when (people
+  apart from tokens and agents, approvals carried over unchanged steps with
+  where they came from), criteria results, capture hashes and the hash of
+  `run.json`, signed with the service's Ed25519 key. `kaloko signoff <run>`
+  downloads the JSON and the PDF and checks them; `kaloko signoff --verify
+  <file>` checks a record someone handed over (public key at
+  `/.well-known/kaloko-signoff.json`). Give it to the person when they ask
+  for proof of acceptance; never create one for a run that is not accepted.
 
 ## Cleaning up runs
 
@@ -245,6 +263,17 @@ Everything above is available over the API with an organization token:
   (the whole flow), and per comment `PATCH`, `DELETE`, `POST …/<cid>/resolve`
   (with `note`) and `…/<cid>/reopen`; `GET /api/v1/orgs/<org>/comments?state=open|all&scenario=&run=&mine=1`
   across the organization. Lists of runs and scenarios carry `open_comments`.
+  A comment body may carry `shape` (`{kind: box, box: [x, y, w, h]}`,
+  `{kind: arrow, from, to}` or `{kind: pen, points}` in fractions, with
+  `viewport` and `size`) and `attachments` (ids from
+  `POST …/comments/attachments?name=<file>` with the image as the body: PNG,
+  JPEG, WebP or GIF up to 5 MB, counted in the plan's storage).
+- `GET|POST /api/v1/orgs/<org>/runs/<id>/ignore-regions`,
+  `DELETE …/ignore-regions/<rid>`, `GET …/scenarios/<id>/ignore-regions[?state=all]`
+  and `POST …/scenarios/<id>/ignore-regions/applied` (`{ids}`): regions drawn
+  to leave out of pixel diffs (drawing needs Developer / Tester).
+- `GET /api/v1/orgs/<org>/runs/<id>/signoff` (JSON), `…/signoff.pdf`,
+  `…/signoff.html`: the signed acceptance record of an accepted run.
 - `GET /api/v1/orgs/<org>/notifications[?unread=1]`, `POST` with
   `{"read": "all"}` or `{"read": [ids]}`
 - `GET /api/v1/orgs/<org>/runs[?project=&scenario=&kind=&verdict=&author=&environment=&branch=&q=][&latest=1]`

package/skills/kaloko/reference/execution.md

@@ -88,6 +88,7 @@ When pixel diffs between runs keep flagging the same clock, ad or carousel:
 kaloko walk --stability 3        # 3 screenshots per capture, a moment apart; what moved is noted
 kaloko stability                 # this run against the 3 previous local runs of the scenario
 kaloko stability --apply         # adds the suggested ignore: to each step (block-style YAML only)
+kaloko stability --pull          # regions people drew on screenshots on kaloko.app go into ignore:
 ```
 
 `kaloko stability` writes `stability.json` and `stability.yml` into the run
@@ -98,6 +99,14 @@ changed is not noise. `--same-commit` compares only runs of the same commit,
 `--runs a,b` names them, `--last N` sets how many runs are compared. Capture
 the steps again after applying: the capture records the ignored regions.
 
+People mark noise by hand too: a Developer / Tester draws a rectangle on a
+screenshot (step detail → *Mark a changing region*). It is kept per flow, shows
+dashed on every run and the canvas pixel diff already skips it.
+`kaloko stability --pull` writes those regions into the scenario's `ignore:`
+(appended to an existing block list, never twice) and tells the service they
+are in the file; walk those steps again afterwards. MCP `list_ignore_regions`
+lists them, `add_ignore_region` suggests one.
+
 ## Only what changed
 
 After a fix, walk the steps the change reaches instead of the whole flow:

package/skills/kaloko/reference/mcp.md

@@ -42,8 +42,11 @@ file.
 
 | Tool | Use |
 |---|---|
-| `list_comments` | open threads (or `state: all`) across the organization, filtered by `scenario` or `run_id`, with replies, pins, anchors and who wrote them |
-| `add_comment` | comment on a step (`run_id` + `step`), the whole run (`run_id`) or the whole flow (`scenario`); `parent_id` replies; optional `pin` `{ x, y, viewport }` |
+| `list_comments` | open threads (or `state: all`) across the organization, filtered by `scenario` or `run_id`, with replies, pins, anchors, drawn regions (`region.px`: CSS pixels of the page in `region.viewport`), attached images with URLs, and who wrote them |
+| `add_comment` | comment on a step (`run_id` + `step`), the whole run (`run_id`) or the whole flow (`scenario`); `parent_id` replies; optional `pin` `{ x, y, viewport }` or `shape` (box or arrow in fractions, with `viewport` and `size`) |
+| `list_ignore_regions` | regions people drew to leave out of pixel diffs, per step, with the `ignore:` entry each becomes (`kaloko stability --pull` writes them) |
+| `add_ignore_region` | suggest such a region (`run_id`, `step`, `viewport`, `rect` in CSS px); Developer / Tester, scope upload or full |
+| `get_signoff_record` | the signed acceptance record of an accepted run (Business): approvals with provenance, criteria, capture hashes, signature |
 | `resolve_comment` | close a thread with a `note` that says what changed (it becomes the last reply) |
 | `reopen_comment`, `edit_comment`, `delete_comment` | reopen; edit or delete your own comment |
 

package/src/cli.mjs

@@ -18,7 +18,8 @@ import { configureGate } from './lib/linkcheck.mjs'
 import { rememberEnvironment } from './lib/secrets.mjs'
 import { evaluateRun, semanticPrefetch } from './lib/evaluate.mjs'
 import { buildManifest, writePreview, attentionLines } from './lib/build.mjs'
-import { stabilityCmd } from './lib/stability.mjs'
+import { stabilityCmd, pullDrawn } from './lib/stability.mjs'
+import { signoffCmd } from './lib/signoff.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'
@@ -217,6 +218,15 @@ Results
                                     Regions that change on every run or move while the page is idle (clocks, ads,
                                     carousels): ignore suggestions per step in <run>/stability.yml; --apply adds
                                     them to the scenario (ignore:), and pixel diffs then skip them
+  signoff <run-id> [--out dir] [--lang cs|en] [--json]
+                                    The signed acceptance record of an accepted run (Business): JSON and PDF with who
+                                    approved what and when, criteria results and capture hashes, checked against the
+                                    service's public key
+  signoff --verify <file.json|file.pdf> [--key file|url] [--json]
+                                    Check a record someone handed over (no token needed); exit 1 when it does not verify
+  stability --pull [--scenario id] [--json]
+                                    Regions people drew on screenshots on kaloko.app (step detail → Page → Draw a
+                                    region) go into the scenario's ignore: of their steps; walk them again after
   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)
@@ -257,6 +267,15 @@ Design (environments with kind: design; live HTML steps in a folder)
 Common options: --run <id|dir> (or KALOKO_RUN)  --config <file>   KALOKO_AGENT=<name> labels writes by an agent
 `
 
+/** A comment's drawing for the terminal: "· box 120,340 300×80 px on desktop" (CSS px when the size is known). */
+export function regionText (g) {
+  if (!g) return ''
+  const pct = (v) => `${Math.round(v * 100)}%`
+  const where = g.px ? `${g.px[0]},${g.px[1]} ${g.px[2]}×${g.px[3]} px` : `${pct(g.box[0])},${pct(g.box[1])} ${pct(g.box[2])}×${pct(g.box[3])}`
+  const kind = g.kind === 'arrow' ? 'arrow over' : g.kind === 'pen' ? 'drawing over' : 'box'
+  return ` · ${kind} ${where}${g.viewport ? ` on ${g.viewport}` : ''}`
+}
+
 /** validate: scenarios the service still lists as active whose scenario file no longer exists here (#58). */
 async function warnRetired (args) {
   if (args.offline) return
@@ -1485,6 +1504,8 @@ const commands = {
 
   async stability (args) {
     const { config, root, run, scenario } = await runContext(args)
+    // regions drawn by hand on the canvas (kaloko.app) into the scenario's ignore:
+    if (args.pull) { await pullDrawn({ root, config, run, args, say, client: service(config) }); return }
     await stabilityCmd({ root, config, run, scenario, args, say })
   },
 
@@ -1685,7 +1706,8 @@ const commands = {
     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}`)
+      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}` : ''}${regionText(r.region)} — ${r.email}${r.agent ? ` via ${r.agent}` : ''}: ${r.note}`)
+      for (const f of r.attachments || []) say(`      attached ${f.name} (${f.type}): ${f.url || f.id}`)
       for (const x of r.replies || []) say(`      ↳ ${x.email}${x.agent ? ` via ${x.agent}` : ''}: ${x.deleted ? '(deleted)' : x.note}`)
     }
     const flow = data.flow_comments || []
@@ -1708,6 +1730,22 @@ const commands = {
    * accepted run, returned, commented), the approvals carried over unchanged steps, and the review-mode link. For
    * agents: report it to the person; never approve on their behalf.
    */
+  /**
+   * The signed acceptance record of an accepted run: JSON and PDF downloaded and checked against the service's public
+   * key; --verify checks a record someone handed over (no token, no project needed).
+   */
+  async signoff (args) {
+    if (typeof args.verify === 'string') {
+      const config = await context(args).then((c) => c.config).catch(() => ({}))
+      return signoffCmd({ config, args, say })
+    }
+    const { config, root } = await context(args)
+    let runId = args._[0] || (typeof args.run === 'string' ? args.run : null)
+    if (!runId) { try { const r = await resolveRun({ root, output: config.output }); if (r.meta.shared) runId = r.meta.id } catch {} }
+    if (!runId) throw new UserError('Usage: kaloko signoff <run-id> [--out dir] | kaloko signoff --verify <file.json|file.pdf>')
+    return signoffCmd({ config, args, say, client: service(config), runId })
+  },
+
   async review (args) {
     const { config, root } = await context(args)
     const client = service(config)

package/src/lib/signoff-core.mjs

@@ -0,0 +1,138 @@
+// Signed sign-off records (idea 10): canonical JSON, Ed25519 signatures and their verification. Shared by the service
+// (worker/src/signoff.js) and the CLI (kaloko signoff): WebCrypto only, no node: imports, so it runs in both.
+//
+// What is signed: the record without its `signature` field, serialised as canonical JSON ("kaloko-c14n-v1": object
+// keys sorted by UTF-16 code units at every level, no whitespace, undefined values left out, numbers and strings as
+// JSON.stringify writes them). The signature is Ed25519 over the UTF-8 bytes of that text, base64url without padding.
+
+const enc = new TextEncoder()
+const dec = new TextDecoder()
+
+export const CANONICAL = 'kaloko-c14n-v1'
+export const SIGNOFF_SCHEMA = 'kaloko.signoff.v1'
+export const PDF_ATTACHMENT = 'kaloko-signoff.json'
+/** Marks the embedded file object in a sign-off PDF so the record can be found again without a PDF parser. */
+export const PDF_MARK = '/KalokoSignoff true'
+
+/** Canonical JSON text of a value (see the header). */
+export function canonicalJson (value) {
+  if (value === null || typeof value !== 'object') {
+    if (typeof value === 'number' && !Number.isFinite(value)) return 'null'
+    return JSON.stringify(value) ?? 'null'
+  }
+  if (Array.isArray(value)) return `[${value.map((v) => (v === undefined || typeof v === 'function' ? 'null' : canonicalJson(v))).join(',')}]`
+  if (typeof value.toJSON === 'function') return canonicalJson(value.toJSON())
+  const keys = Object.keys(value).filter((k) => value[k] !== undefined && typeof value[k] !== 'function').sort()
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(',')}}`
+}
+
+const bytesOf = (x) => typeof x === 'string' ? enc.encode(x) : x instanceof Uint8Array ? x : new Uint8Array(x)
+
+/** SHA-256 as lowercase hex of a string (UTF-8) or bytes. */
+export async function sha256Hex (data) {
+  const h = new Uint8Array(await crypto.subtle.digest('SHA-256', bytesOf(data)))
+  return [...h].map((b) => b.toString(16).padStart(2, '0')).join('')
+}
+
+/** base64url without padding. */
+export function b64url (bytes) {
+  const b = bytesOf(bytes); let s = ''
+  for (let i = 0; i < b.length; i += 0x8000) s += String.fromCharCode(...b.subarray(i, i + 0x8000))
+  return btoa(s).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}
+/** Bytes of base64 or base64url (padding optional). */
+export function fromB64url (text) {
+  const s = String(text).trim().replace(/-/g, '+').replace(/_/g, '/').replace(/\s+/g, '')
+  const bin = atob(s + '='.repeat((4 - (s.length % 4)) % 4))
+  const out = new Uint8Array(bin.length)
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i)
+  return out
+}
+
+const PKCS8_SEED_PREFIX = new Uint8Array([0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x04, 0x22, 0x04, 0x20])
+const ED = { name: 'Ed25519' }
+
+/** Key id: the first 16 hex characters of the SHA-256 of the raw public key. */
+export const keyId = async (raw) => (await sha256Hex(raw)).slice(0, 16)
+
+/**
+ * The service's signing key from the secret: a base64/base64url 32-byte Ed25519 seed, a base64 PKCS#8 DER, or a JWK
+ * (JSON with d and x). Returns { privateKey, publicJwk, publicRaw (base64url), kid }.
+ */
+export async function importSigningKey (secret) {
+  const text = String(secret || '').trim()
+  if (!text) throw new Error('No signing key.')
+  let privateKey
+  if (text.startsWith('{')) {
+    const jwk = JSON.parse(text)
+    privateKey = await crypto.subtle.importKey('jwk', { kty: 'OKP', crv: 'Ed25519', d: jwk.d, x: jwk.x, ext: true }, ED, true, ['sign'])
+  } else {
+    const raw = fromB64url(text)
+    let der
+    if (raw.length === 32) { der = new Uint8Array(48); der.set(PKCS8_SEED_PREFIX); der.set(raw, 16) } else der = raw
+    privateKey = await crypto.subtle.importKey('pkcs8', der, ED, true, ['sign'])
+  }
+  const jwk = await crypto.subtle.exportKey('jwk', privateKey)
+  const publicRawBytes = fromB64url(jwk.x)
+  return { privateKey, publicJwk: { kty: 'OKP', crv: 'Ed25519', x: jwk.x }, publicRaw: jwk.x, kid: await keyId(publicRawBytes) }
+}
+
+const unsigned = (record) => { const { signature, ...rest } = record || {}; return rest }
+
+/** Signs a record: { ...record, signature: { alg, kid, value, canonical } }. */
+export async function signRecord (record, key) {
+  const body = unsigned(record)
+  const value = new Uint8Array(await crypto.subtle.sign(ED, key.privateKey, enc.encode(canonicalJson(body))))
+  return { ...body, signature: { alg: 'Ed25519', kid: key.kid, value: b64url(value), canonical: CANONICAL } }
+}
+
+/** SHA-256 (hex) of the signed part of a record: what the PDF and the CLI print as the record hash. */
+export const recordSha256 = (record) => sha256Hex(canonicalJson(unsigned(record)))
+
+/** The public keys of a well-known document ({ keys: [...] }), a list, or one key object, as [{ kid, public_key }]. */
+export function keyList (keys) {
+  const list = Array.isArray(keys) ? keys : Array.isArray(keys?.keys) ? keys.keys : keys ? [keys] : []
+  return list.map((k) => ({ kid: k.kid, public_key: k.public_key || k.x || k.jwk?.x })).filter((k) => k.public_key)
+}
+
+/** Verifies a signed record against public keys. Returns { ok, kid, reason }. */
+export async function verifyRecord (signed, keys) {
+  const sig = signed?.signature
+  if (!sig || typeof sig !== 'object') return { ok: false, kid: null, reason: 'The record has no signature.' }
+  if (sig.alg !== 'Ed25519') return { ok: false, kid: sig.kid || null, reason: `Unknown signature algorithm ${sig.alg}.` }
+  if (sig.canonical && sig.canonical !== CANONICAL) return { ok: false, kid: sig.kid || null, reason: `Unknown canonical form ${sig.canonical}.` }
+  const list = keyList(keys)
+  const candidates = sig.kid ? list.filter((k) => !k.kid || k.kid === sig.kid) : list
+  if (!candidates.length) return { ok: false, kid: sig.kid || null, reason: `No public key with id ${sig.kid} (the service may have rotated its key).` }
+  let value
+  try { value = fromB64url(sig.value) } catch { return { ok: false, kid: sig.kid || null, reason: 'The signature is not base64url.' } }
+  const data = enc.encode(canonicalJson(unsigned(signed)))
+  for (const k of candidates) {
+    try {
+      const pub = await crypto.subtle.importKey('raw', fromB64url(k.public_key), ED, false, ['verify'])
+      if (await crypto.subtle.verify(ED, pub, value, data)) return { ok: true, kid: k.kid || sig.kid || null, reason: null }
+    } catch {}
+  }
+  return { ok: false, kid: sig.kid || null, reason: 'The signature does not match: the record was changed after it was signed, or it was signed with another key.' }
+}
+
+/** Reads bytes as latin1 text (one character per byte), for searching a PDF. */
+const latin1 = (b) => { let s = ''; for (let i = 0; i < b.length; i += 0x8000) s += String.fromCharCode(...b.subarray(i, i + 0x8000)); return s }
+
+/** The signed record embedded in a sign-off PDF (the attached kaloko-signoff.json), or null. */
+export function extractRecordFromPdf (bytes) {
+  const b = bytesOf(bytes)
+  const text = latin1(b)
+  const at = text.lastIndexOf(PDF_MARK)
+  if (at < 0) return null
+  const dictStart = text.lastIndexOf('<<', at)
+  const dictEnd = text.indexOf('>>', at)
+  if (dictStart < 0 || dictEnd < 0) return null
+  const len = Number(text.slice(dictStart, dictEnd).match(/\/Length (\d+)/)?.[1])
+  const s = text.indexOf('stream', dictEnd)
+  if (!Number.isFinite(len) || s < 0) return null
+  let start = s + 'stream'.length
+  if (text[start] === '\r') start++
+  if (text[start] === '\n') start++
+  try { return JSON.parse(dec.decode(b.subarray(start, start + len))) } catch { return null }
+}

package/src/lib/signoff.mjs

@@ -0,0 +1,83 @@
+// `kaloko signoff <run> [--out dir] [--lang cs|en] [--json]` downloads the signed acceptance record of an accepted run
+// (JSON and PDF) and checks its signature; `kaloko signoff --verify <file.json|file.pdf> [--key file|url]` checks a
+// record someone handed over, without a token. The keys come from <service>/.well-known/kaloko-signoff.json.
+import { readFile, writeFile, mkdir } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+import { UserError } from './util.mjs'
+import { serviceUrl } from './service.mjs'
+import { verifyRecord, recordSha256, extractRecordFromPdf, canonicalJson } from './signoff-core.mjs'
+
+/** Public keys from a file, a URL or the service's well-known document. */
+export async function loadKeys ({ config, key }) {
+  const src = typeof key === 'string' && key ? key : `${serviceUrl(config || {})}/.well-known/kaloko-signoff.json`
+  try {
+    if (/^https?:\/\//.test(src)) {
+      const res = await fetch(src, { headers: { Accept: 'application/json' } })
+      if (!res.ok) throw new Error(`HTTP ${res.status}`)
+      return await res.json()
+    }
+    return JSON.parse(await readFile(resolve(src), 'utf8'))
+  } catch (e) { throw new UserError(`Could not read the public keys from ${src}: ${e.message}`) }
+}
+
+/** The signed record in a .json or .pdf file. */
+export async function readRecord (file) {
+  let bytes
+  try { bytes = await readFile(resolve(file)) } catch (e) { throw new UserError(`Cannot read ${file}: ${e.message}`) }
+  if (bytes.subarray(0, 5).toString('latin1') === '%PDF-') {
+    const record = extractRecordFromPdf(new Uint8Array(bytes))
+    if (!record) throw new UserError(`${file} has no Kaloko sign-off record attached.`)
+    return { record, kind: 'pdf' }
+  }
+  try { return { record: JSON.parse(bytes.toString('utf8')), kind: 'json' } } catch { throw new UserError(`${file} is neither a sign-off JSON nor a sign-off PDF.`) }
+}
+
+/** Verification of one record: { ok, kid, reason, sha256, run, verdict }. */
+export async function verifySignoff (record, keys) {
+  const v = await verifyRecord(record, keys)
+  return { ok: v.ok, kid: v.kid, reason: v.reason, sha256: await recordSha256(record), run: record?.run?.id || null, verdict: record?.verdict || null, issuer: record?.issuer?.service || null }
+}
+
+const summary = (r, check) => {
+  const v = r.verdict || {}; const a = r.approvals || {}; const s = r.summary || {}
+  const lines = [
+    `${r.run?.id} · ${r.run?.scenario?.title || r.run?.scenario?.id || ''} · ${r.run?.environment?.name || ''}${r.run?.git?.commit ? ` · ${String(r.run.git.commit).slice(0, 12)}` : ''}`,
+    `  verdict: ${v.verdict} by ${v.by}${v.via && v.via !== 'session' ? ` (${v.via}, not a person's decision)` : ''} on ${String(v.at || '').slice(0, 16).replace('T', ' ')}`,
+    `  approved in the app: ${(a.people || []).map((x) => x.email).join(', ') || 'nobody beyond the verdict'}${(a.tokens_and_agents || []).length ? `; by tokens or agents (not counted as people): ${a.tokens_and_agents.map((x) => x.email).join(', ')}` : ''}`,
+    `  steps: ${s.steps ?? (r.steps || []).length} (${s.pass || 0} pass, ${s.partial || 0} partial, ${s.fail || 0} fail, ${s.skip || 0} not checked)${s.carried ? `, ${s.carried} approval(s) carried over unchanged steps` : ''}`,
+    `  record SHA-256: ${check.sha256}`,
+    `  run.json SHA-256: ${r.manifest?.sha256 || '—'}`,
+    check.ok ? `  ✓ signature valid (Ed25519, key ${check.kid}, ${check.issuer || 'unknown issuer'})` : `  ✕ signature NOT valid: ${check.reason}`
+  ]
+  return lines.join('\n')
+}
+
+/**
+ * The command. `client` is service(config) (only for downloading); `runId` the run to download (a shared run id).
+ */
+export async function signoffCmd ({ config, args, say, client = null, runId = null }) {
+  if (typeof args.verify === 'string') {
+    const { record, kind } = await readRecord(args.verify)
+    const check = await verifySignoff(record, await loadKeys({ config, key: args.key }))
+    if (args.json) say(JSON.stringify({ file: args.verify, kind, ...check }, null, 2))
+    else say(summary(record, check))
+    if (!check.ok) throw new UserError(`The sign-off record in ${args.verify} does not verify: ${check.reason}`)
+    return check
+  }
+  if (!runId) throw new UserError('Usage: kaloko signoff <run-id> [--out dir] [--lang cs|en] | kaloko signoff --verify <file.json|file.pdf> [--key file|url]')
+  if (!client) throw new UserError('Downloading a sign-off record needs the service token (KALOKO_TOKEN).')
+  const base = `/orgs/${config.org}/runs/${encodeURIComponent(runId)}`
+  const lang = args.lang === 'cs' ? 'cs' : 'en'
+  const record = await client.request('GET', `${base}/signoff`)
+  const pdf = Buffer.from(await (await client.fetch(`${base}/signoff.pdf?lang=${lang}`)).arrayBuffer())
+  const dir = resolve(typeof args.out === 'string' ? args.out : '.')
+  await mkdir(dir, { recursive: true })
+  const jsonFile = join(dir, `kaloko-signoff-${runId}.json`); const pdfFile = join(dir, `kaloko-signoff-${runId}.pdf`)
+  await writeFile(jsonFile, canonicalJson(record))
+  await writeFile(pdfFile, pdf)
+  const check = await verifySignoff(record, await loadKeys({ config, key: args.key }))
+  if (args.json) say(JSON.stringify({ json: jsonFile, pdf: pdfFile, ...check }, null, 2))
+  else say(`${summary(record, check)}\nSaved ${jsonFile}\n      ${pdfFile}\nAnyone can check it later: kaloko signoff --verify ${pdfFile}`)
+  if (!check.ok) throw new UserError(`The downloaded record does not verify: ${check.reason}`)
+  return check
+}

package/src/lib/stability.mjs

@@ -227,6 +227,88 @@ export async function applySuggestions (file, report) {
   return { applied, skipped }
 }
 
+const sameEntry = (a, b) => JSON.stringify({ rect: a.rect, viewport: a.viewport, selector: a.selector }) === JSON.stringify({ rect: b.rect, viewport: b.viewport, selector: b.selector })
+
+/**
+ * Adds ignore entries to steps of the scenario file, appending to an existing block-style `ignore:` list or creating
+ * one (comments and formatting stay; flow-style lists are left alone). `byNode`: Map node → entries.
+ * Returns { applied: [{ node, entries }], skipped: [reason] }; entries already in the file are not added twice.
+ */
+export async function mergeIgnore (file, byNode) {
+  let text = await readFile(file, 'utf8')
+  const applied = []; const skipped = []
+  for (const [nodeId, entries] of byNode) {
+    const parsed = yaml.load(text)
+    const node = (parsed?.nodes || []).find((n) => n.id === nodeId)
+    if (!node) { skipped.push(`${nodeId}: not in ${file}`); continue }
+    const fresh = entries.filter((e) => !(Array.isArray(node.ignore) ? node.ignore : []).some((x) => sameEntry(x, e)))
+    if (!fresh.length) { applied.push({ node: nodeId, entries: [] }); continue }
+    const lines = text.split('\n')
+    const at = lines.findIndex((l) => new RegExp(`^(\\s*)- id: ['"]?${nodeId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}['"]?\\s*(#.*)?$`).test(l))
+    if (at < 0) { skipped.push(`${nodeId}: node is not in block style; add the regions by hand`); continue }
+    const dash = lines[at].match(/^(\s*)-/)[1].length
+    const indent = ' '.repeat(dash + 2)
+    // the node's block: lines indented deeper than its dash (blank lines included)
+    let end = at + 1
+    while (end < lines.length && (!lines[end].trim() || lines[end].match(/^(\s*)/)[1].length > dash)) end++
+    while (end > at + 1 && !lines[end - 1].trim()) end--
+    const key = lines.slice(at + 1, end).findIndex((l) => l.startsWith(`${indent}ignore:`))
+    const item = (e, pad) => `${pad}- ${yaml.dump(e, { flowLevel: 0, lineWidth: 400 }).trim()}`
+    let block
+    if (key < 0) {
+      block = { at: end, lines: [`${indent}ignore:`, ...fresh.map((e) => item(e, indent + '  '))] }
+    } else {
+      const k = at + 1 + key
+      if (lines[k].replace(/#.*$/, '').trim() !== 'ignore:') { skipped.push(`${nodeId}: ignore is written inline; add the regions by hand`); continue }
+      // list items follow at the key's indentation or deeper; the list ends at the next line that is neither
+      let j = k + 1; let pad = null
+      while (j < end) {
+        const l = lines[j]
+        if (!l.trim()) { j++; continue }
+        const ind = l.match(/^(\s*)/)[1].length
+        if (pad == null) { if (!l.trimStart().startsWith('- ') || ind < indent.length) break; pad = ' '.repeat(ind) }
+        if (ind < pad.length || (ind === pad.length && !l.trimStart().startsWith('- '))) break
+        j++
+      }
+      while (j > k + 1 && !lines[j - 1].trim()) j--
+      block = { at: j, lines: fresh.map((e) => item(e, pad ?? indent + '  ')) }
+    }
+    const next = [...lines.slice(0, block.at), ...block.lines, ...lines.slice(block.at)].join('\n')
+    let ok = false
+    try { const n2 = (yaml.load(next)?.nodes || []).find((n) => n.id === nodeId); ok = Array.isArray(n2?.ignore) && n2.ignore.length === (Array.isArray(node.ignore) ? node.ignore.length : 0) + fresh.length } catch {}
+    if (!ok) { skipped.push(`${nodeId}: could not add to its ignore list safely; add the regions by hand`); continue }
+    text = next
+    applied.push({ node: nodeId, entries: fresh })
+  }
+  if (applied.some((a) => a.entries.length)) await writeFile(file, text)
+  return { applied, skipped }
+}
+
+/**
+ * `kaloko stability --pull`: regions people drew on the canvas (Developer / Tester and up) become ignore: entries of
+ * their steps in the scenario file; the service then stops showing them as suggestions.
+ */
+export async function pullDrawn ({ root, config, run, args, say, client }) {
+  const scenarioId = typeof args.scenario === 'string' ? args.scenario : run.meta.scenario.id
+  const data = await client.request('GET', `/orgs/${config.org}/scenarios/${encodeURIComponent(scenarioId)}/ignore-regions`)
+  const regions = data.regions || []
+  if (!regions.length) { say(`No drawn regions wait for ${scenarioId}. Draw them on a screenshot on kaloko.app (step detail → Page → Draw a region).`); return { applied: [], skipped: [], regions: [] } }
+  const byNode = new Map()
+  for (const r of regions) (byNode.get(r.node_id) || byNode.set(r.node_id, []).get(r.node_id)).push(r.scenario_entry)
+  const file = resolve(root, run.meta.scenario_file)
+  const out = await mergeIgnore(file, byNode)
+  const done = new Set(out.applied.map((a) => a.node))
+  const ids = regions.filter((r) => done.has(r.node_id)).map((r) => r.id)
+  if (ids.length) await client.request('POST', `/orgs/${config.org}/scenarios/${encodeURIComponent(scenarioId)}/ignore-regions/applied`, { ids })
+  if (args.json) { say(JSON.stringify({ ...out, regions }, null, 2)); return out }
+  const added = out.applied.reduce((n, a) => n + a.entries.length, 0)
+  say(`Pulled ${regions.length} drawn region(s) of ${scenarioId}: ${added} added to ${run.meta.scenario_file}${added < ids.length ? `, ${ids.length - added} already there` : ''}.`)
+  for (const a of out.applied.filter((x) => x.entries.length)) say(`  ${a.node}: ${a.entries.map((e) => `[${e.rect.join(', ')}] on ${e.viewport}`).join('; ')}`)
+  for (const x of out.skipped) say(`  skipped ${x}`)
+  if (added) say('Walk those steps again so the canvas and pixel diffs use them.')
+  return out
+}
+
 /** `kaloko stability`: detect, write stability.json and stability.yml in the run, print, optionally apply. */
 export async function stabilityCmd ({ root, config, run, scenario, args, say }) {
   const report = await detectUnstable({ root, config, run, scenario, last: Number(args.last) || 4, runs: typeof args.runs === 'string' ? args.runs.split(',').map((s) => s.trim()).filter(Boolean) : null, sameCommit: !!args['same-commit'] })