feat(watch): add adaptive audio playout and worker offload

.agents/commands/sync-upstream

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ ${1:-} == --help ]]; then
+	echo 'Usage: bash .agents/commands/sync-upstream [remote [branch]]'
+	echo 'Defaults: upstream main. Fetch, back up HEAD, and prepare a merge for review.'
+	echo 'Requires a clean branch. Never stashes, commits, rebases, or pushes.'
+	exit 0
+fi
+if (($# > 2)) || [[ ${1:-} == -* || ${2:-} == -* ]]; then
+	echo 'Expected a remote name and branch name. Use --help.' >&2
+	exit 2
+fi
+remote=${1:-upstream}
+branch=${2:-main}
+cd "$(git rev-parse --show-toplevel)"
+git symbolic-ref --quiet HEAD >/dev/null || {
+	echo 'Refusing to sync a detached HEAD. Select the intended working branch.' >&2
+	exit 1
+}
+for state in MERGE_HEAD CHERRY_PICK_HEAD REVERT_HEAD rebase-merge rebase-apply; do
+	if [[ -e $(git rev-parse --git-path "$state") ]]; then
+		echo "Finish or abort the existing Git operation first: $state" >&2
+		exit 1
+	fi
+done
+if [[ -n $(git status --porcelain --untracked-files=normal) ]]; then
+	echo 'Commit the intended work first. The sync command does not stash or discard changes.' >&2
+	exit 1
+fi
+git remote get-url "$remote" >/dev/null
+git check-ref-format "refs/heads/$branch"
+git fetch --no-tags "$remote" "refs/heads/$branch"
+target=$(git rev-parse FETCH_HEAD)
+git merge-base HEAD "$target" >/dev/null || {
+	echo 'Refusing to merge unrelated histories.' >&2
+	exit 1
+}
+if git merge-base --is-ancestor "$target" HEAD; then
+	echo "Already contains $remote/$branch at $target."
+	exit 0
+fi
+backup="refs/backups/sync/$(date -u +%Y%m%dT%H%M%SZ)-$$"
+git update-ref "$backup" HEAD ''
+echo "Backup: $backup"
+echo "Incoming commits from $remote/$branch:"
+git log --oneline "HEAD..$target"
+if ! git -c merge.autoStash=false merge --no-commit --no-ff "$target"; then
+	echo 'Merge stopped. Resolve and commit, or run git merge --abort to return to the backup.' >&2
+	exit 1
+fi
+echo 'Review the staged merge, validate affected packages, and commit with your own attribution.'
+echo 'No remote branch has been changed.'

.agents/commands/sync-upstream.test.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+command_path="$(cd "$(dirname "$0")" && pwd)/sync-upstream"
+fixture=$(mktemp -d)
+trap 'rm -rf "$fixture"' EXIT
+export GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_NOSYSTEM=1
+export GIT_AUTHOR_NAME='Sync test' GIT_AUTHOR_EMAIL='sync@example.invalid'
+export GIT_COMMITTER_NAME="$GIT_AUTHOR_NAME" GIT_COMMITTER_EMAIL="$GIT_AUTHOR_EMAIL"
+git init -q -b main "$fixture/upstream"
+cd "$fixture/upstream"
+echo initial >shared
+git add shared
+git commit -qm initial
+git clone -q . "$fixture/work"
+cd "$fixture/work"
+git remote rename origin upstream
+git switch -qc fork
+echo fork >local
+git add local
+git commit -qm fork
+before=$(git rev-parse HEAD)
+cd "$fixture/upstream"
+echo incoming >incoming
+git add incoming
+git commit -qm incoming
+incoming=$(git rev-parse HEAD)
+cd "$fixture/work"
+
+echo dirty >untracked
+if bash "$command_path"; then
+    echo 'Accepted dirty worktree' >&2
+    exit 1
+fi
+[[ $(git rev-parse HEAD) == "$before" && -f untracked ]]
+rm untracked
+bash "$command_path"
+[[ $(git rev-parse HEAD) == "$before" ]]
+[[ $(git rev-parse MERGE_HEAD) == "$incoming" ]]
+[[ $(cat local) == fork && $(cat incoming) == incoming ]]
+[[ $(git for-each-ref --format='%(objectname)' refs/backups/sync) == "$before" ]]
+if bash "$command_path"; then
+    echo 'Accepted pending merge' >&2
+    exit 1
+fi
+git commit -qm 'merge upstream'
+merged=$(git rev-parse HEAD)
+bash "$command_path"
+[[ $(git rev-parse HEAD) == "$merged" ]]
+git merge-base --is-ancestor "$incoming" HEAD
+
+echo fork >shared
+git add shared
+git commit -qm 'fork conflict'
+before=$(git rev-parse HEAD)
+cd "$fixture/upstream"
+echo upstream >shared
+git add shared
+git commit -qm 'upstream conflict'
+cd "$fixture/work"
+if bash "$command_path"; then
+    echo 'Accepted conflicting merge' >&2
+    exit 1
+fi
+[[ -n $(git ls-files -u) ]]
+git merge --abort
+[[ $(git rev-parse HEAD) == "$before" && $(cat shared) == fork ]]
+[[ -z $(git status --porcelain) ]]
+git switch -q --detach
+if bash "$command_path"; then
+    echo 'Accepted detached HEAD' >&2
+    exit 1
+fi
+echo 'Sync command tests passed.'

.claude/skills/sync-upstream/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: sync-upstream
+description: Sync the current MoQ working branch with upstream changes and validate the integration. Use for requests to sync or update the fork from upstream.
+---
+
+Run from the intended worktree. Inspect its branch, status, remotes, and PR base first. Preserve any work in progress with focused commits before syncing; do not stash, reset, or change another worktree.
+
+The shared command is available to any harness with a shell:
+
+```bash
+bash .agents/commands/sync-upstream
+```
+
+It defaults to `upstream main`. Supply another configured remote and branch only when the task requires it. The command fetches, records a backup ref, and prepares a merge without committing or pushing. Repeating it after the merge is committed does nothing until upstream advances. A pending merge must be completed or aborted before another sync.
+
+Resolve conflicts by understanding both sides, including the fork's behavioral fixes and upstream API migrations. Review the entire staged diff, run affected regression tests and the repository's `just check` and `just test` in Nix, and report any incomplete checks. Do not mix builds with live media measurements. Keep before/after measurements on the same upstream base.
+
+Commit the reviewed merge with a conventional subject and your own `Co-Authored-By` trailer. Report the old and new upstream commits, conflict resolutions, validation, and public API or wire impact. Only push or update a PR when the current user request authorizes it, using the requested fork and target branch.
+
+This skill is shared through the repository's `.agents/skills` symlink to `.claude/skills`. Claude Code can invoke `/sync-upstream`; other harnesses can load this skill or run the shell command directly.

.github/justfile

@@ -6,6 +6,7 @@ set fallback
 # Lint GitHub Actions workflows.
 check:
     python3 {{ source_directory() }}/scripts/install-formula.test.py
+    bun test {{ source_directory() }}/scripts/rust-cache.test.ts
     {{ source_directory() }}/scripts/release.test.sh
     @if command -v nfpm >/dev/null 2>&1 && command -v envsubst >/dev/null 2>&1 && command -v dpkg-deb >/dev/null 2>&1 && command -v rpm >/dev/null 2>&1; then python3 {{ source_directory() }}/../rs/scripts/package-rename.test.py; fi
     @if command -v actionlint >/dev/null 2>&1; then actionlint; fi

.github/scripts/rust-cache.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+
+type Mapping = { [key: string]: unknown };
+
+const workflows = [
+	{ file: "interop.yml", job: "interop" },
+	{ file: "nightly.yml", job: "nightly" },
+];
+
+const github = path.resolve(import.meta.dir, "..");
+
+function mapping(value: unknown, label: string): Mapping {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) {
+		throw new TypeError(`${label} is not a YAML mapping`);
+	}
+
+	return { ...value };
+}
+
+function sequence(value: unknown, label: string): unknown[] {
+	if (!Array.isArray(value)) throw new TypeError(`${label} is not a YAML sequence`);
+	return value;
+}
+
+async function yaml(file: string): Promise<Mapping> {
+	return mapping(Bun.YAML.parse(await Bun.file(file).text()), file);
+}
+
+describe("Rust cache boundary", () => {
+	for (const workflow of workflows) {
+		test(`${workflow.file} uses the flake-keyed local cache action`, async () => {
+			const file = path.join(github, "workflows", workflow.file);
+			const document = await yaml(file);
+			const jobs = mapping(document.jobs, `${file}: jobs`);
+			const job = mapping(jobs[workflow.job], `${file}: jobs.${workflow.job}`);
+			const steps = sequence(job.steps, `${file}: jobs.${workflow.job}.steps`).map((step, index) =>
+				mapping(step, `${file}: jobs.${workflow.job}.steps[${index}]`),
+			);
+			const cache = steps.find((step) => step.name === "Rust cache" || step.name === "Rust Cache");
+
+			expect(
+				steps.some((step) => typeof step.uses === "string" && step.uses.startsWith("Swatinem/rust-cache@")),
+			).toBeFalse();
+			expect(cache?.uses).toBe("./.github/actions/rust-cache");
+		});
+	}
+
+	test("cache and restore keys bind the runner and pinned Nix toolchain", async () => {
+		const file = path.join(github, "actions/rust-cache/action.yml");
+		const document = await yaml(file);
+		const runs = mapping(document.runs, `${file}: runs`);
+		const steps = sequence(runs.steps, `${file}: runs.steps`).map((step, index) =>
+			mapping(step, `${file}: runs.steps[${index}]`),
+		);
+		const cache = steps.find(
+			(step) => typeof step.uses === "string" && step.uses.startsWith("jdx/mr-boxington-action@"),
+		);
+		const inputs = mapping(cache?.with, `${file}: cache inputs`);
+		const prefix = `\${{ runner.os }}-\${{ runner.arch }}-mbx-target-\${{ inputs.scope }}-\${{ hashFiles('flake.nix', 'flake.lock', 'rust-toolchain.toml') }}-`;
+
+		expect(inputs["restore-keys"]).toBe(prefix);
+		expect(typeof inputs["cache-key"] === "string" && inputs["cache-key"].startsWith(prefix)).toBeTrue();
+	});
+});

.github/workflows/alert.yml

@@ -25,8 +25,13 @@ on:
     # Rust cache on `main`, and that push run is nobody's check, so a break in
     # it would otherwise go unseen. The cost is a skipped Alert run per Swift
     # pull request.
+    #
+    # Audio quality is here for its manual matrix run, which is not a pull
+    # request. The cost is a skipped Alert run per pull request its replay lane
+    # runs on.
     workflows:
       - apt-repo
+      - Audio quality
       - Cache
       - Cachix
       - Docker