fix: backfill the root CHANGELOG, and give it the gate the per-package ones never needed

CHANGELOG.md

@@ -7,12 +7,66 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Breaking Changes
+
+- **Requires Node.js ≥ 22.** Node 20 reached end of life on 2026-04-30 and no longer receives security
+  patches.
+  `Migrate:` upgrade the Node on the Mac running the agent and on whatever runs the relay. `nvm install 22`
+  or the installer from nodejs.org; `tapflow doctor` reports the version it finds.
+- **Update your agents and your relay together.** Requests now carry an identifier the reply echoes, so
+  the relay can tell which answer belongs to which request. An agent from before this release does not
+  echo it, and the reply is then discarded rather than misattributed — safer, and still a failure: an app
+  install started from the dashboard sits on "Installing…" with no Launch control, and a deep link opened
+  through `open_url` does nothing. A client newer than its relay has the mirror problem on a refused
+  session join, which runs to its deadline instead of saying why.
+  `Migrate:` upgrade every device agent to this release at the same time as the relay. Packages are
+  versioned together, but nothing installs them together — this is the case where a Mac left on the
+  previous agent is the one that breaks.
+
 ### Changed
 
 - Split stable dashboard vendor dependencies into smaller chunks to reduce maximum bundle size and improve cache reuse across releases.
+- **A refused session now says which session it refused and why.** Opening a device someone else already
+  has open, or one whose Mac is under load, used to produce a generic failure the dashboard could not
+  attribute — with two tabs opening at once it could even be shown against the wrong one. The refusal now
+  names the session and carries one of three reasons, so the second tester is told the device is in use
+  rather than that something went wrong.
 
 ### Fixed
 
+- **An input that never reached the device was reported as having landed.** Every path that could refuse
+  or drop an input — a simulator that is not booted, an input channel still starting, an agent that went
+  away, a helper process that died — either said nothing or said success. An LLM driving the device through
+  MCP moved on as though the tap had happened; a `tapflow flow` run failed several steps later with
+  "selector not found", which is the worst place to lose a cause; and the dashboard showed nothing at all.
+  Every one of those now answers, and says which of the two it is: the input was refused, with the reason,
+  or it could not be confirmed — which is not the same as saying it did not happen, because an
+  acknowledgement can arrive after the wait for it has ended. Repeating an input that did land would
+  duplicate it, so the message says to check the device rather than to retry.
+- **A reply could be attributed to the wrong request.** Boots, shutdowns, app installs and launches, URL
+  opens and input acknowledgements carried nothing tying a reply to the request that asked. Two overlapping
+  requests on one session and the first answer settled the wrong one — so a boot that failed could be
+  reported as the one that succeeded, and an acknowledgement that arrived late was read as the next input's.
+  Each of those now carries a correlator the reply echoes.
+- **A dead session hung until the deadline instead of saying so.** When an agent went away mid-command, the
+  relay said so on the wire, and the MCP server and flow runner ignored it — an app
+  install waited out its full two minutes and reported a timeout. They read those messages now and fail with
+  the reason. A device whose agent reconnected is reported as needing a boot rather than as a reset device,
+  because the app is still running.
+- **An app install could fail with "No devices are booted" on a device that was starting up.** Booting a
+  simulator was announced as finished when the command to boot it returned, which is 7.6 seconds before the
+  device is actually ready. Anything issued in that window — an install, a launch, an input — hit a device
+  that was still coming up. The agent now waits for the device to report itself booted before saying so.
+- **A JPEG screenshot could come back as PNG bytes labelled JPEG.** Android always produces PNG whatever is
+  asked for, and the label was taken from the request. The MCP server picks its image parser by that label,
+  so it measured PNG bytes with a JPEG parser and handed the model a wrong screen size — which the model then
+  used as the divisor for every tap coordinate. The format is read from the bytes now.
+- **`tapflow flow` reported an environment failure as a product failure.** A step whose input the relay or
+  the agent refused failed with the selector error from the next step rather than the refusal, so a CI run
+  showed a broken assertion where the device had simply not been reachable.
+- The iOS fallback video path emitted PNG frames under a JPEG label. No entrypoint shipped with tapflow
+  selects it; it affects a consumer of `@tapflowio/ios-agent` that sets `intervalMs` itself.
+
 - **A scrcpy server process error could take down every Android device the agent manages, not just the one session.** The scrcpy server process spawned for a real-device session had no error handler; an unhandled error on it (e.g. the server process failing to spawn, or a permission error on kill) crashed the whole android-agent process, ending every session it was managing. It's now logged instead.
 - `TouchHelper` and `KeyboardHelperDaemon` could leave a wedged helper process running after `stop()` — only `SIGTERM` was sent, with no fallback. Both now escalate to `SIGKILL` after 1s if the process hasn't exited, matching `ScreenCaptureStreamer` and `XCUITreeReader`.
 

scripts/__tests__/auditIntegration.test.mjs

@@ -59,6 +59,95 @@ afterEach(() => rmSync(repo, { recursive: true, force: true }))
 
 const CHANGESET = (body) => `---\n"@tapflowio/relay": patch\n---\n\n${body}\n`
 
+/**
+ * Runs the **PR gate** — the same script with no `--audit` — against a base ref in the throwaway repo.
+ *
+ * The audit is what this file was built for, and the gate had no integration coverage at all: its
+ * branches are unit-tested as pure functions and nothing drove the wiring. That is the half this file's
+ * own header says broke twice.
+ */
+function gate(base = 'main') {
+  const opts = { cwd: repo, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env, PR_BODY: '' } }
+  try {
+    const stdout = execFileSync('node', [SCRIPT, base], opts)
+    return { code: 0, out: stdout }
+  } catch (e) {
+    return { code: e.status, out: (e.stdout ?? '') + (e.stderr ?? '') }
+  }
+}
+
+/** Commit `files` on a branch off main and leave HEAD there — the shape the gate sees on a PR. */
+function branchWith(files) {
+  git('checkout', '-q', '-b', 'feature')
+  for (const [path, body] of Object.entries(files)) {
+    mkdirSync(join(repo, dirname(path)), { recursive: true })
+    writeFileSync(join(repo, path), body)
+  }
+  git('add', '-A')
+  git('commit', '-q', '-m', 'work')
+}
+
+const SHIPPED = 'packages/relay/src/thing.ts'
+
+describe('the PR gate asks for a root CHANGELOG entry', () => {
+  // The root CHANGELOG is hand-written and had nothing enforcing it, so it went four days and 22
+  // merged PRs stale while every one of those PRs carried a changeset. The rule was in CONTRIBUTING
+  // and the enforcement was in neither place.
+  it('fails a changeset that leaves the root CHANGELOG untouched', () => {
+    branchWith({ [SHIPPED]: 'export const a = 1\n', '.changeset/x.md': CHANGESET('a fix') })
+    const r = gate()
+    expect(r.code).toBe(1)
+    expect(r.out).toMatch(/no entry in the root CHANGELOG/i)
+    expect(r.out).toContain('.changeset/x.md')
+  })
+
+  it('passes when the branch also writes the entry', () => {
+    branchWith({
+      [SHIPPED]: 'export const a = 1\n',
+      '.changeset/x.md': CHANGESET('a fix'),
+      'CHANGELOG.md': '## [Unreleased]\n\n### Fixed\n\n- a fix\n',
+    })
+    expect(gate().code).toBe(0)
+  })
+
+  // Not every changeset earns an entry — half a typing cycle is invisible to a user, and forcing a line
+  // for each would fill the file with noise nobody can act on. Opting out is a written decision.
+  it('passes when the changeset says it is internal', () => {
+    branchWith({
+      [SHIPPED]: 'export const a = 1\n',
+      '.changeset/x.md': `${CHANGESET('typing only')}\n<!-- changelog: internal — no observable behaviour -->\n`,
+    })
+    expect(gate().code).toBe(0)
+  })
+
+  // **Not an ordering claim, and a first draft said it was.** There is no gate "ahead of" this one — the
+  // changelog block runs *before* the missing-changeset error, and this passes because a branch with no
+  // changeset has nothing to owe an entry for. Stating the wrong mechanism is worse than stating none: it
+  // reads as covering an ordering that a later edit could break silently. The assertion that matters is
+  // that this branch prints the *changeset* instruction and not the changelog one, since a contributor
+  // told to write a CHANGELOG entry when what they are missing is a changeset goes to the wrong file.
+  it('tells a branch with no changeset to add one, not to write a changelog entry', () => {
+    branchWith({ [SHIPPED]: 'export const a = 1\n' })
+    const r = gate()
+    expect(r.code).toBe(1)
+    expect(r.out).toMatch(/adds no changeset/i)
+    expect(r.out).not.toMatch(/no entry in the root CHANGELOG/i)
+  })
+
+  // The amended and renamed cases, which keying on `--diff-filter=A` let through. A follow-up that
+  // extends an existing unconsumed changeset with new behaviour is the ordinary shape of a second PR on
+  // one subject, and it was invisible.
+  it('demands an entry for an amended changeset, not only a new one', () => {
+    writeFileSync(join(repo, '.changeset', 'existing.md'), CHANGESET('first pass'))
+    git('add', '-A')
+    git('commit', '-q', '-m', 'earlier changeset')
+    branchWith({ [SHIPPED]: 'export const a = 1\n', '.changeset/existing.md': CHANGESET('first pass, now also this') })
+    const r = gate()
+    expect(r.code).toBe(1)
+    expect(r.out).toMatch(/no entry in the root CHANGELOG/i)
+  })
+})
+
 describe('audit --audit against real git history', () => {
   it('reports a merge that shipped code without a changeset', () => {
     mergePr(101, 'fix-a', { 'packages/relay/src/a.ts': 'export const a = 1\n' })

scripts/__tests__/changesetGateAccuracy.test.mjs

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest'
-import { packagesNamedIn, mixedChangesets, ignoredOnlyChangesets, manifestChangeShips, shipsToUsers, packagePublishesAt } from '../check-changeset.mjs'
+import { packagesNamedIn, mixedChangesets, ignoredOnlyChangesets, changelogEntryOwed, manifestChangeShips, shipsToUsers, packagePublishesAt } from '../check-changeset.mjs'
 
 const IGNORED = new Set(['@tapflowio/dashboard', '@tapflowio/playground'])
 const cs = (body) => `---\n${body}\n---\n\nsome note.\n`
@@ -73,6 +73,34 @@ describe('a changeset that names only ignored packages', () => {
   })
 })
 
+describe('a changeset that owes the root CHANGELOG an entry', () => {
+  // The root CHANGELOG is hand-written and had no gate, so it went four days and 22 merged PRs stale
+  // while every one of those PRs carried a changeset. Opting out is a written decision, not a silence.
+  const read = (f) => ({
+    'plain.md': cs('"@tapflowio/relay": patch'),
+    'internal.md': `${cs('"@tapflowio/protocol": patch')}\n<!-- changelog: internal — protocol typing, nothing observable -->\n`,
+    'no-reason.md': `${cs('"@tapflowio/protocol": patch')}\n<!-- changelog: internal -->\n`,
+    'mentions-it.md': `${cs('"@tapflowio/relay": patch')}\n\nSee the changelog: internal notes are not a marker.\n`,
+  })[f]
+
+  it('owes one for a plain changeset', () => {
+    expect(changelogEntryOwed(['plain.md'], read)).toEqual(['plain.md'])
+  })
+  it('is released by the marker', () => {
+    expect(changelogEntryOwed(['internal.md'], read)).toEqual([])
+  })
+  // `internal` alone with no reason still opts out — the word is the marker and a bare one is a
+  // decision someone typed. Requiring prose here would be a second, unstated rule.
+  it('accepts the marker with no reason after it', () => {
+    expect(changelogEntryOwed(['no-reason.md'], read)).toEqual([])
+  })
+  // Anchored to a line of its own, like `no-changeset`. Prose that happens to contain the words is not
+  // an opt-out -- the shape this repo has been bitten by twice, where a comment was read as a value.
+  it('is not released by prose that merely says the words', () => {
+    expect(changelogEntryOwed(['mentions-it.md'], read)).toEqual(['mentions-it.md'])
+  })
+})
+
 describe('a package.json edit that ships', () => {
   const withDev = (dev) => JSON.stringify({ name: 'x', version: '1.0.0', dependencies: { a: '1' }, devDependencies: dev })
   it('ignores a devDependencies-only change', () => {

scripts/check-changeset.mjs

@@ -365,6 +365,38 @@ export function ignoredOnlyChangesets(files, ignored, read) {
   })
 }
 
+/**
+ * Which added changesets still owe the root `CHANGELOG.md` an entry.
+ *
+ * Two changelogs exist and only one has a gate. The per-package `CHANGELOG.md` files are generated by
+ * `changeset version` and cannot be forgotten. The **root** `CHANGELOG.md` is hand-written, is what a
+ * self-hoster reads to decide whether to upgrade, and nothing checked it — so on 2026-08-15 it had been
+ * untouched for four days across 22 merged PRs, while all 22 carried a changeset. The rule was in
+ * CONTRIBUTING and the enforcement was in neither place.
+ *
+ * **Not every changeset earns an entry**, and forcing one would fill the file with noise a user cannot
+ * act on — half of this cycle's changesets are protocol typing with no observable behaviour. So a
+ * changeset opts out by saying so in its own body, on a line of its own:
+ *
+ *     <!-- changelog: internal — protocol typing, nothing a user can observe -->
+ *
+ * The reason is required for the same purpose it is required on `no-changeset`: skipping is a decision
+ * somebody wrote down, not something that happens by forgetting.
+ *
+ * **What this covers, stated rather than implied:** a branch that touches a changeset — added, amended or
+ * renamed — and ships published source. It does **not** cover a branch with no changeset (its
+ * `no-changeset` reason answers the same question one layer up), a bot PR (the CI job is skipped for
+ * those, and a skipped required check passes), or a release branch (exempt by design). Nor does it read
+ * the entry: touching the file is what it checks, because no check can tell whether prose corresponds to
+ * a diff. The measured incident it ends — 22 merged PRs against a four-day-stale file — was 22 PRs that
+ * all carried changesets. The marker lives in the changeset
+ * rather than the PR body because it classifies *that change*, and because a PR carrying two changesets
+ * can need it for one of them.
+ */
+export function changelogEntryOwed(files, read) {
+  return files.filter((f) => !/^<!--\s*changelog:\s*internal\b.*-->$/m.test(read(f)))
+}
+
 function main() {
   // `--audit [since]` walks merges instead of the current branch: the PR gate cannot help with
   // anything already on main, and that is exactly how #410–#413 slipped through. Run at release
@@ -568,6 +600,27 @@ function main() {
     process.exit(1)
   }
 
+  // **`AMR`, not the `added` list above.** A PR that extends an existing unconsumed changeset with new
+  // behaviour shows up as `M` and never as `A`, and a rename is `R` — so keying this on `added` let the
+  // two most ordinary shapes of follow-up work escape. The audit half already counts `AMR` for exactly
+  // that reason. What this still cannot see is a branch with no changeset at all: a `no-changeset`
+  // reason answers the same question one layer up, and a bot PR skips the CI job entirely.
+  const touchedChangesets = git('diff', '--name-only', '--diff-filter=AMR', `${mergeBase}...HEAD`)
+    .split('\n')
+    .filter((f) => /^\.changeset\/.+\.md$/.test(f) && !/^\.changeset\/README\.md$/i.test(f))
+  const owed = changelogEntryOwed(touchedChangesets, (f) => readFileSync(f, 'utf8'))
+  if (owed.length > 0 && !changed.includes('CHANGELOG.md')) {
+    console.error('Changeset added with no entry in the root CHANGELOG.md:\n')
+    for (const f of owed) console.error(`  ${f}`)
+    console.error('\nThat file is what a self-hoster reads to decide whether to upgrade, and unlike the')
+    console.error('per-package changelogs nothing generates it. Add an entry under `## [Unreleased]`, in')
+    console.error('the section CONTRIBUTING lists — a breaking change needs `### Breaking Changes` and a')
+    console.error('`Migrate:` hint. If this change is not something a user can observe, say so in the')
+    console.error('changeset on a line of its own:\n')
+    console.error('  <!-- changelog: internal — reason -->')
+    process.exit(1)
+  }
+
   if (added.length > 0) {
     console.log(`Published source changed and ${added.length} changeset(s) added:`)
     for (const f of added) console.log(`  + ${f}`)