@hasna/recordings 0.4.0 → 0.5.0

package/scripts/release-suite-gate.ts

@@ -1,174 +1,251 @@
 #!/usr/bin/env bun
-/**
- * Release-suite gate (wired into `prepublishOnly`).
- *
- * Runs the app's own Linux-CI-partitioned suite — `test:gated`, which covers
- * every discovered `*.test.ts` (the quarantine file is empty by design) — and
- * fails on ANY failure.
- *
- * The allowlist is SELF-INVALIDATING, the same property as
- * `.github/linux-quarantine.txt`: if an allowlisted failure stops failing
- * (the owning lane lands its fix, or a quarantined package ages out of the
- * 7-day window), the gate exits 1 and demands the entry be removed. Any
- * failure outside the allowlist fails the gate.
- *
- * Allowlist history (both entries removed 2026-08-23 by the 0.3.9 release
- * lane, publish-all-recordings, per this gate's own self-invalidation
- * contract — each failure stopped failing at head 15b6181c6):
- *   - service-contract-manifest.test.ts (credential_seam_compliance): the
- *     contracts-surface migration landed in hasna/apps PR #957
- *     (resolveStorageClient now imported from @hasna/contracts/client), so
- *     the conformance check passes; the entry's own reason said "Remove this
- *     entry when the lane lands."
- *   - native-app-companion-contract.test.ts (release supply-chain policy):
- *     the companion build's --minimum-release-age=604800 quarantine no longer
- *     bites because @hasna/contracts is on the fleet minimumReleaseAgeExcludes
- *     list (the sanctioned mechanism for fresh publishes); the test passes.
- * Both removals are the gate's designed behaviour, not a weakening: any
- * future failure now fails the gate with zero allowlisted exceptions.
- *
- * The gate FAILS CLOSED on abnormal termination: a non-zero suite exit is
- * acceptable only when it is fully explained by allowlisted failures — the
- * runner completed (its summary line is present), every parsed failure is
- * allowlisted, at least one allowlisted failure fired, and the runner's
- * reported failure count equals the parsed count. A crash, signal kill,
- * timeout, or runner error that produces a non-zero exit without a complete
- * summary fails the gate (remediation cycle 2 of PR hasna/apps#826).
+/** Run every selected manifest test once, using each Darwin fixture's required boundary.
+ * There are no allowed failures. Missing/empty reports, crashes (including exit-zero
+ * early exits), unexpected files and overlapping or incomplete selections fail closed.
  */
 import { spawnSync } from "node:child_process";
-import { mkdtempSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, readFileSync, realpathSync, symlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-const SEP = "::";
-
-const GATED_KEYS: Array<{ file: string; test: string; owner: string; reason: string }> = [];
-
-function run(argv: string[], env: Record<string, string>): { status: number; stdout: string; stderr: string } {
-  const res = spawnSync(process.execPath, argv, { encoding: "utf8", env: { ...process.env, ...env } });
-  return { status: res.status ?? -1, stdout: res.stdout ?? "", stderr: res.stderr ?? "" };
+export interface SuiteGroup {
+  id: string;
+  files: string[];
+  runner: "bun" | "publication" | "recorder";
+  pattern?: string;
 }
-
-// 1. Validate the partition (quarantine file must be consistent).
-const check = run(["scripts/ci-linux-suite.ts", "--check"], {});
-if (check.status !== 0) {
-  console.error("release-suite-gate: partition check failed:\n" + (check.stderr || check.stdout));
-  process.exit(1);
+export interface GroupReport {
+  id: string;
+  status: number | null;
+  signal?: string | null;
+  error?: string;
+  output: string;
+  junit: string;
 }
+const LIFECYCLE = "src/__tests__/macos-app-lifecycle.test.ts";
+const PUBLICATION = "src/__tests__/release-output-publication-contract.test.ts";
+const RECORDER = "src/__tests__/recorder.test.ts";
+const PUBLICATION_NAMES = "(?:macOS finalized artifact installer|release output publication contract)(?:\\s|$)";
 
-// 2. Collect the gated file list.
-const gated = run(["scripts/ci-linux-suite.ts", "--gated"], {});
-if (gated.status !== 0) {
-  console.error("release-suite-gate: could not enumerate gated files:\n" + (gated.stderr || gated.stdout));
-  process.exit(1);
+export function planReleaseSuite(files: string[], platform: string): SuiteGroup[] {
+  if (!files.length || new Set(files).size !== files.length || files.some(f => !/^src\/(?:[a-zA-Z0-9_-]+\/)*[a-zA-Z0-9_.-]+\.test\.ts$/.test(f))) {
+    throw new Error("empty, duplicate or unsafe manifest-gated files");
+  }
+  const recorder: SuiteGroup[] = files.includes(RECORDER) ? [{ id: "recorder", files: [RECORDER], runner: "recorder" }] : [];
+  const remaining = files.filter(f => f !== RECORDER);
+  if (platform !== "darwin") return [...recorder, ...(remaining.length ? [{ id: "ordinary", files: remaining, runner: "bun" as const }] : [])];
+  for (const file of [LIFECYCLE, PUBLICATION, RECORDER]) if (!files.includes(file)) throw new Error(`required Darwin fixture file missing: ${file}`);
+  const ordinary = remaining.filter(f => f !== LIFECYCLE && f !== PUBLICATION);
+  if (!ordinary.length) throw new Error("empty ordinary group");
+  return [
+    ...recorder,
+    { id: "publication", files: [LIFECYCLE, PUBLICATION], runner: "publication", pattern: `^${PUBLICATION_NAMES}` },
+    { id: "lifecycle", files: [LIFECYCLE], runner: "bun", pattern: `^(?!${PUBLICATION_NAMES})` },
+    { id: "ordinary", files: ordinary, runner: "bun" },
+  ];
 }
-const gatedFiles = gated.stdout.split("\n").filter(Boolean);
-if (gatedFiles.length === 0) {
-  console.error("release-suite-gate: zero gated files - refusing to pass on an empty suite.");
-  process.exit(1);
+interface TestCase { key: string; file: string; name: string; skipped: boolean }
+function fail(message: string): never { throw new Error(message); }
+function entity(text: string): string {
+  return text.replace(/&([^;]+);/g, (_, value: string) => {
+    const entities: Record<string, string> = { amp: "&", quot: '"', apos: "'", lt: "<", gt: ">" };
+    if (value in entities) return entities[value]!;
+    const number = /^#x[0-9a-f]+$/i.test(value) ? parseInt(value.slice(2), 16) : /^#[0-9]+$/.test(value) ? Number(value.slice(1)) : NaN;
+    if (!Number.isInteger(number) || number <= 0 || number > 0x10ffff) fail("invalid JUnit entity");
+    return String.fromCodePoint(number);
+  });
 }
-
-// 3. Run the gated suite exactly like `test:gated`.
-const logDir = mkdtempSync(join(tmpdir(), "recordings-release-gate-"));
-const logPath = join(logDir, "suite.log");
-const suite = spawnSync(
-  process.execPath,
-  ["test", "--timeout", "120000", ...gatedFiles],
-  {
-    encoding: "utf8",
-    env: { ...process.env, RECORDINGS_TEST_TIMEOUT_MS: "120000" },
-    maxBuffer: 64 * 1024 * 1024,
-  },
-);
-const output = (suite.stdout ?? "") + (suite.stderr ?? "");
-try {
-  writeFileSync(logPath, output);
-} catch {
-  /* log capture is best-effort */
+function count(value: string | undefined): number {
+  if (!value || !/^\d+$/.test(value) || !Number.isSafeInteger(Number(value))) fail("missing or invalid JUnit count");
+  return Number(value);
 }
-const suiteStatus = suite.status ?? -1;
-
-// 4. Parse failing tests as (file, description) pairs, in output order.
-const failPairs: Array<{ file: string; test: string }> = [];
-let currentFile = "";
-for (const line of output.split("\n")) {
-  const fileMatch = /^(?:\.\/)?(src\/[^\s:]+\.test\.ts):$/.exec(line);
-  if (fileMatch) {
-    currentFile = fileMatch[1];
-    continue;
-  }
-  const failMatch = /^\(fail\) (.+) \[\d+.*\]$/.exec(line);
-  if (failMatch) {
-    failPairs.push({ file: currentFile, test: failMatch[1].trim() });
+/** Strictly parse the small XML vocabulary emitted by Bun's JUnit reporter. Unlike
+ * console output, it includes filtered tests as skipped, providing a registration
+ * inventory without executing the same tests again in a discovery pass.
+ */
+function casesFromJUnit(xml: string): TestCase[] {
+  const stack: Array<{ tag: string; attrs: Record<string, string> }> = [];
+  const cases: TestCase[] = [];
+  const occurrences = new Map<string, number>();
+  let root: Record<string, string> | undefined;
+  let current: TestCase | undefined;
+  let closed = false;
+  const tokens = /<\?xml[^?]*\?>|<\/?[a-zA-Z]+(?:\s+[a-zA-Z]+="[^"]*")*\s*\/?>|[^<]+/gy;
+  let offset = 0;
+  while (offset < xml.length) {
+    tokens.lastIndex = offset;
+    const match = tokens.exec(xml);
+    if (!match || match.index !== offset) fail("malformed or truncated JUnit XML");
+    const token = match[0]; offset = tokens.lastIndex;
+    if (token.startsWith("<?xml")) { if (root) fail("misplaced JUnit declaration"); continue; }
+    if (!token.startsWith("<")) { if (token.trim()) fail("unexpected JUnit text"); continue; }
+    const tag = /^<\/?([a-zA-Z]+)/.exec(token)![1]!;
+    if (token.startsWith("</")) {
+      if (!/^<\/[a-zA-Z]+\s*>$/.test(token) || stack.pop()?.tag !== tag) fail("unbalanced JUnit XML");
+      if (tag === "testcase") current = undefined;
+      if (tag === "testsuites") closed = true;
+      continue;
+    }
+    if (closed) fail("data after JUnit completion");
+    const attrs: Record<string, string> = {};
+    for (const attr of token.matchAll(/\s+([a-zA-Z]+)="([^"]*)"/g)) {
+      if (attr[1]! in attrs) fail("duplicate JUnit attribute");
+      attrs[attr[1]!] = entity(attr[2]!);
+    }
+    const parent = stack.at(-1)?.tag;
+    if (tag === "testsuites") {
+      if (root || parent) fail("duplicate JUnit root");
+      root = attrs;
+    } else if (tag === "testsuite") {
+      if (parent !== "testsuites" && parent !== "testsuite") fail("misplaced JUnit suite");
+    } else if (tag === "testcase") {
+      if (parent !== "testsuite" || !attrs.file || attrs.name === undefined) fail("invalid JUnit testcase");
+      const names = stack.filter(s => s.tag === "testsuite").slice(1).map(s => s.attrs.name ?? fail("unnamed JUnit suite"));
+      const file = attrs.file.replace(/^\.\//, "");
+      const identity = JSON.stringify([file, names, attrs.name, attrs.line ?? ""]);
+      const instance = occurrences.get(identity) ?? 0; occurrences.set(identity, instance + 1);
+      current = { file, name: [...names, attrs.name].join(" "), key: `${identity}:${instance}`, skipped: false };
+      cases.push(current);
+    } else if (tag === "skipped") {
+      if (parent !== "testcase" || !current || current.skipped) fail("misplaced or duplicate JUnit skip");
+      current.skipped = true;
+    } else fail(`unexpected JUnit element: ${tag}`);
+    if (!token.endsWith("/>")) stack.push({ tag, attrs });
+    else if (tag === "testcase") current = undefined;
+    else if (tag === "testsuites") closed = true;
   }
+  if (!root || !closed || stack.length || !cases.length) fail("missing, empty or incomplete JUnit report");
+  if (count(root.tests) !== cases.length || count(root.failures) !== 0 || count(root.skipped) !== cases.filter(c => c.skipped).length || (root.errors !== undefined && count(root.errors) !== 0)) fail("JUnit totals do not explain the complete run");
+  return cases;
 }
+const sorted = (values: Iterable<string>) => [...values].sort();
+const equal = (a: string[], b: string[]) => JSON.stringify(a) === JSON.stringify(b);
 
-// 5. Classify.
-const failuresByKey = new Map<string, number>();
-for (const key of GATED_KEYS) {
-  failuresByKey.set(key.file + SEP + key.test, 0);
-}
-const unexpected: Array<{ file: string; test: string }> = [];
-for (const pair of failPairs) {
-  const key = pair.file + SEP + pair.test;
-  if (failuresByKey.has(key)) {
-    failuresByKey.set(key, (failuresByKey.get(key) ?? 0) + 1);
-  } else {
-    unexpected.push(pair);
+export function validateReleaseRun(groups: SuiteGroup[], reports: GroupReport[]): { passed: number; skipped: number; tests: number; files: number } {
+  if (!groups.length || groups.some(g => !g.files.length) || new Set(groups.map(g => g.id)).size !== groups.length || reports.length !== groups.length || new Set(reports.map(r => r.id)).size !== reports.length) fail("missing, repeated or empty release group");
+  const inventories = new Map<string, string[]>();
+  const owned = new Map<string, number>();
+  let passed = 0, skipped = 0;
+  for (const group of groups) {
+    const report = reports.find(r => r.id === group.id) ?? fail(`missing report: ${group.id}`);
+    if (report.status !== 0 || report.signal || report.error) fail(`${group.id}: runner exited abnormally (${report.error ?? report.signal ?? report.status})`);
+    const cases = casesFromJUnit(report.junit);
+    if (!equal(sorted(new Set(cases.map(c => c.file))), sorted(group.files))) fail(`${group.id}: executed files differ from the planned group`);
+    const selector = group.pattern ? new RegExp(group.pattern) : undefined;
+    const selected = cases.filter(c => !selector || selector.test(c.name));
+    if (!selected.length || group.files.some(f => !selected.some(c => c.file === f))) fail(`${group.id}: empty selected file or group`);
+    if (cases.some(c => selector && !selector.test(c.name) && !c.skipped)) fail(`${group.id}: executed a test owned by another group`);
+    for (const file of group.files) {
+      const inventory = sorted(cases.filter(c => c.file === file).map(c => c.key));
+      const previous = inventories.get(file);
+      if (previous && !equal(previous, inventory)) fail(`${group.id}: shared file registration inventory changed: ${file}`);
+      inventories.set(file, inventory);
+    }
+    const selectedSkips = selected.filter(c => c.skipped).length;
+    const tally = (kind: string) => {
+      const values = [...report.output.matchAll(new RegExp(`^\\s*(\\d+) ${kind}\\s*$`, "gm"))];
+      return values.length === 1 ? Number(values[0]![1]) : undefined;
+    };
+    const summaries = [...report.output.matchAll(/^Ran (\d+) tests? across (\d+) files?\./gm)];
+    if (summaries.length !== 1 || Number(summaries[0]![1]) !== selected.length || Number(summaries[0]![2]) !== group.files.length || tally("pass") !== selected.length - selectedSkips || (tally("skip") ?? 0) !== selectedSkips || tally("fail") !== 0 || /^\s*[1-9]\d* errors?\s*$/m.test(report.output)) fail(`${group.id}: console completion does not match selected JUnit tests`);
+    for (const c of selected) owned.set(c.key, (owned.get(c.key) ?? 0) + 1);
+    passed += selected.length - selectedSkips; skipped += selectedSkips;
   }
+  for (const inventory of inventories.values()) for (const key of inventory) if (owned.get(key) !== 1) fail("release test must belong to exactly one completed group");
+  return { passed, skipped, tests: passed + skipped, files: inventories.size };
 }
 
-if (unexpected.length > 0) {
-  console.error(
-    "release-suite-gate: FAIL - unexpected test failures:\n" +
-      unexpected.map((u) => "  " + u.file + " :: " + u.test).join("\n"),
-  );
-  console.error("Full suite log: " + logPath);
-  process.exit(1);
+/** Credentials and account/storage selectors never enter a release test process.
+ * This is supplemental isolation; Darwin host tools still require the audited OS
+ * fixture boundaries (changing HOME cannot isolate defaults, Keychain or TCC).
+ */
+export function groupEnvironment(root: string, inherited: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+  for (const directory of ["home", "tmp", "bin"]) mkdirSync(join(root, directory), { mode: 0o700 });
+  // Shell children must use this exact runner even when the caller's PATH has a
+  // different Bun version. No global bin or existing symlink is modified.
+  symlinkSync(process.execPath, join(root, "bin", "bun"));
+  return {
+    HOME: join(root, "home"), TMPDIR: join(root, "tmp") + "/",
+    PATH: `${join(root, "bin")}:${inherited.PATH ?? "/usr/bin:/bin:/usr/sbin:/sbin"}`,
+    XDG_CONFIG_HOME: join(root, "config"), XDG_CACHE_HOME: join(root, "cache"),
+    XDG_DATA_HOME: join(root, "data"), NPM_CONFIG_CACHE: join(root, "npm-cache"),
+    BUN_RUNTIME_TRANSPILER_CACHE_PATH: join(root, "bun-cache"),
+    RECORDINGS_TEST_TIMEOUT_MS: "120000", NO_COLOR: "1", TERM: "dumb",
+    ...(inherited.CI ? { CI: inherited.CI } : {}),
+    ...(inherited.LANG ? { LANG: inherited.LANG } : {}),
+  };
 }
 
-// 6. Fail closed on abnormal termination. A non-zero suite exit is only
-// acceptable when it is fully explained by the allowlisted failures: the
-// runner completed (summary line present), every parsed failure is
-// allowlisted, at least one allowlisted failure fired, and the runner's
-// reported failure count equals the parsed count (no unparsed failures).
-// A crash, signal kill, timeout, or runner error produces a non-zero exit
-// without a complete summary and must fail the gate.
-if (suiteStatus !== 0) {
-  const summaryMatch = /Ran (\d+) tests across (\d+) files/.exec(output);
-  // The tally is "N pass[,/ ] M fail" in the runner's closing summary. The
-  // LAST match is taken (bun prints the tally once, but a naive first match
-  // can hit "0.13.3 failed to resolve" -> "3 fail" inside a version string).
-  const tallyMatches = [...output.matchAll(/(\d+) pass[\s,/]+(\d+) fail/g)];
-  const failCountMatch = tallyMatches.length > 0 ? tallyMatches[tallyMatches.length - 1] : null;
-  const reportedFails = failCountMatch ? Number(failCountMatch[2]) : null;
-  const anyAllowlistedFired = failPairs.length > 0;
-  const complete = summaryMatch !== null && reportedFails !== null && reportedFails === failPairs.length;
-  if (!anyAllowlistedFired || !complete) {
-    console.error(
-      "release-suite-gate: FAIL - suite exited " + suiteStatus +
-        " with " + failPairs.length + " parsed failure(s) but the run is incomplete or unexplained:" +
-        "\n  summary line present: " + (summaryMatch !== null) +
-        "\n  reported failure count: " + String(reportedFails) +
-        "\n  parsed failure count: " + failPairs.length,
-    );
-    console.error("Full suite log: " + logPath);
-    process.exit(1);
-  }
+export function groupCommand(group: SuiteGroup, junitPath: string): string[] {
+  return group.runner === "publication"
+    ? ["/usr/bin/python3", "-I", "-B", "src/__tests__/helpers/run-publication-fixtures.py", "--bun", process.execPath, "--report-outfile", junitPath]
+    : group.runner === "recorder"
+    ? [process.execPath, "scripts/test-recorder-fixtures.ts", "--junit-output", junitPath]
+    : [process.execPath, "test", "--no-orphans", "--timeout", "120000", ...group.files.map(f => `./${f}`), ...(group.pattern ? ["--test-name-pattern", group.pattern] : []), "--reporter=junit", "--reporter-outfile", junitPath];
 }
 
-// 7. Self-invalidation: an allowlisted failure that no longer fails must be removed.
-const stale = GATED_KEYS.filter((key) => (failuresByKey.get(key.file + SEP + key.test) ?? 0) === 0);
-if (stale.length > 0) {
-  console.error(
-    "release-suite-gate: FAIL - allowlisted failure no longer fails; remove the entry from scripts/release-suite-gate.ts:\n" +
-      stale.map((s) => "  " + s.file + " :: " + s.test + " - " + s.owner).join("\n"),
-  );
-  process.exit(1);
+/** Keep the first failing assertions and the runner summary visible in CI even
+ * when a disposable runner's complete logs cannot be recovered. Prefix every
+ * line so fixture output cannot be interpreted as a workflow command.
+ */
+export function failureDiagnostics(report: GroupReport): string {
+  const lines = report.output.replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "").replace(/[\x00-\x08\x0b-\x1f\x7f]/g, "").split("\n");
+  const selected = new Set<number>();
+  let failures = 0;
+  for (let index = 0; index < lines.length && failures < 8; index++) {
+    if (!/^\s*(?:\(fail\)|error:|Error:|AssertionError:|TimeoutError:)/.test(lines[index]!)) continue;
+    failures++;
+    for (let context = Math.max(0, index - 12); context <= Math.min(lines.length - 1, index + 6); context++) selected.add(context);
+  }
+  const tailStart = Math.max(0, lines.length - 20);
+  const output = [...selected].filter(index => index < tailStart).sort((a, b) => a - b)
+    .map(index => "recordings gate | " + lines[index]!.slice(0, 1000)).join("\n").slice(0, 14_000);
+  const summary = lines.slice(tailStart).map(line => "recordings gate | " + line.slice(0, 350)).join("\n");
+  return `release-suite-gate: ${report.id} status=${report.status} signal=${report.signal ?? "none"}\n`
+    + output + "\n" + summary;
 }
 
-console.log(
-  "release-suite-gate: PASS - " + failPairs.length + " classified pre-existing failure(s) allowlisted:" +
-    failPairs.map((p) => "\n  " + p.file + " :: " + p.test).join(""),
-);
-process.exit(0);
+export function releaseMain(): number {
+  const args = process.argv.slice(2);
+  if (new Set(args).size !== args.length || args.some(arg => arg !== "--all" && arg !== "--plan")) fail("usage: release-suite-gate.ts [--all] [--plan]; arbitrary test filters would invalidate coverage");
+  const enumeration = (mode: string) => {
+    const child = spawnSync(process.execPath, ["scripts/ci-linux-suite.ts", mode], { encoding: "utf8", timeout: 60000 });
+    if (child.status !== 0 || child.signal || child.error) fail(`partition ${mode} failed: ${child.stderr || child.stdout}`);
+    return child.stdout;
+  };
+  // --all validates discovery and quarantine metadata itself, while still running
+  // when the gated subset is empty. The default gate must retain its empty-set refusal.
+  if (!args.includes("--all")) enumeration("--check");
+  const groups = planReleaseSuite(enumeration(args.includes("--all") ? "--all" : "--gated").trim().split("\n").filter(Boolean), process.platform);
+  if (args.includes("--plan")) { console.log(JSON.stringify(groups, null, 2)); return 0; }
+  const logDir = realpathSync(mkdtempSync(join(tmpdir(), "recordings-release-gate-")));
+  console.log(`release-suite-gate: reports and logs: ${logDir}`);
+  const reports: GroupReport[] = [];
+  for (const group of groups) {
+    console.log(`release-suite-gate: running ${group.id} (${group.files.length} files)`);
+    const junitPath = join(logDir, `${group.id}.xml`);
+    const command = groupCommand(group, junitPath);
+    const environmentRoot = mkdtempSync(join(logDir, `${group.id}-environment-`));
+    const child = spawnSync(command[0]!, command.slice(1), { encoding: "utf8", env: groupEnvironment(environmentRoot), maxBuffer: 128 * 1024 * 1024, timeout: group.runner === "publication" ? 360000 : group.runner === "recorder" ? 60000 : 30 * 60 * 1000 });
+    const output = (child.stdout ?? "") + (child.stderr ?? "");
+    writeFileSync(join(logDir, `${group.id}.log`), output);
+    let junit = ""; try { junit = readFileSync(junitPath, "utf8"); } catch { /* Missing reports fail validation. */ }
+    reports.push({ id: group.id, status: child.status, signal: child.signal, error: child.error?.message, output, junit });
+  }
+  writeFileSync(join(logDir, "suite.log"), reports.map(r => `=== ${r.id} ===\n${r.output}`).join("\n"));
+  let result: ReturnType<typeof validateReleaseRun>;
+  try { result = validateReleaseRun(groups, reports); }
+  catch (error) {
+    const failed = reports.filter(report => report.status !== 0 || report.signal || report.error);
+    // Exit-zero truncated receipts also need diagnostics. Coverage validation
+    // remains authoritative; printing evidence never changes its result.
+    for (const report of failed.length ? failed : reports) console.error(failureDiagnostics(report));
+    throw error;
+  }
+  console.log(`release-suite-gate: PASS - ${result.passed} pass, ${result.skipped} skip, 0 fail; ${result.tests} tests across ${result.files} files, each selected once`);
+  return 0;
+}
+if (import.meta.main) {
+  try { process.exitCode = releaseMain(); }
+  catch (error) { console.error(`release-suite-gate: FAIL - ${(error as Error).message}`); process.exitCode = 1; }
+}

package/scripts/resolve_tailscale_cli.sh

@@ -77,6 +77,27 @@ recordings_tailscale_stat_owner_and_mode() {
   esac
 }
 
+# macOS does not ship /usr/bin/realpath on every supported host. Resolve with
+# Bash's physical-directory builtins, without a PATH tool or interpreter. The
+# callers still reject leaf symlinks and compare this physical path exactly.
+recordings_tailscale_physical_path() {
+  local candidate="$1"
+  local parent
+  local leaf
+
+  recordings_validate_tailscale_cli_shape "$candidate" || return 1
+  if [ -d "$candidate" ]; then
+    (unset CDPATH; builtin cd -P -- "$candidate" && builtin pwd -P)
+    return
+  fi
+  [ -e "$candidate" ] && [ ! -L "$candidate" ] || return 1
+  parent="${candidate%/*}"
+  leaf="${candidate##*/}"
+  [ -n "$parent" ] || parent=/
+  parent="$(unset CDPATH; builtin cd -P -- "$parent" && builtin pwd -P)" || return 1
+  printf '%s/%s\n' "${parent%/}" "$leaf"
+}
+
 recordings_validate_trusted_tailscale_app_cli() {
   local candidate="$1"
   local real_host_kernel="$2"
@@ -96,7 +117,7 @@ recordings_validate_trusted_tailscale_app_cli() {
     echo "Trusted Tailscale CLI must be a canonical non-symlink trusted executable." >&2
     return 1
   fi
-  canonical="$(/usr/bin/realpath "$candidate" 2>/dev/null)" || {
+  canonical="$(recordings_tailscale_physical_path "$candidate" 2>/dev/null)" || {
     echo "Trusted Tailscale CLI could not be resolved canonically." >&2
     return 1
   }
@@ -145,7 +166,7 @@ recordings_validate_private_tailscale_snapshot_parent() {
     echo "Tailscale snapshot parent must be an existing private directory." >&2
     return 1
   fi
-  canonical="$(/usr/bin/realpath "$snapshot_parent" 2>/dev/null)" || {
+  canonical="$(recordings_tailscale_physical_path "$snapshot_parent" 2>/dev/null)" || {
     echo "Tailscale snapshot parent could not be resolved canonically." >&2
     return 1
   }
@@ -270,7 +291,7 @@ recordings_verify_official_tailscale_app_and_cli() {
     echo "Trusted Tailscale app must be a canonical non-symlink directory." >&2
     return 1
   fi
-  canonical_app="$(/usr/bin/realpath "$app" 2>/dev/null)" || {
+  canonical_app="$(recordings_tailscale_physical_path "$app" 2>/dev/null)" || {
     echo "Trusted Tailscale app could not be resolved canonically." >&2
     return 1
   }

package/src/native/Recordings/RecordingsLib/BlockingOperation.swift

@@ -0,0 +1,29 @@
+import Dispatch
+
+/// Bridge synchronous, potentially blocking APIs without occupying a cooperative worker.
+/// The caller still owns cancellation and generation checks: submitted work drains to its
+/// existing API deadline and returns its exact result even if its awaiting task is cancelled.
+/// Operations must not depend on Swift task-local values or task cancellation state.
+enum BlockingOperation {
+    private static let queue = DispatchQueue(
+        label: "md.recordings.blocking-operations",
+        attributes: .concurrent
+    )
+    static func run<Value: Sendable>(
+        qos: DispatchQoS.QoSClass = .userInitiated,
+        _ operation: @escaping @Sendable () -> Value
+    ) async -> Value {
+        await withCheckedContinuation { continuation in
+            queue.async(qos: DispatchQoS(qosClass: qos, relativePriority: 0)) {
+                continuation.resume(returning: operation())
+            }
+        }
+    }
+
+    static func runThrowing<Value: Sendable>(
+        qos: DispatchQoS.QoSClass = .userInitiated,
+        _ operation: @escaping @Sendable () throws -> Value
+    ) async throws -> Value {
+        try await run(qos: qos) { Result(catching: operation) }.get()
+    }
+}

package/src/native/Recordings/RecordingsLib/Info.plist

@@ -17,11 +17,11 @@
     <key>CFBundleIdentifier</key>
     <string>com.hasna.recordings</string>
     <key>CFBundleVersion</key>
-    <string>0.4.0</string>
+    <string>0.5.0</string>
     <key>CFBundlePackageType</key>
     <string>APPL</string>
     <key>CFBundleShortVersionString</key>
-    <string>0.4.0</string>
+    <string>0.5.0</string>
     <key>LSMinimumSystemVersion</key>
     <string>26.0</string>
     <key>NSMicrophoneUsageDescription</key>

package/src/native/Recordings/RecordingsLib/ProjectStore.swift

@@ -288,7 +288,7 @@ public final class ProjectStore: ObservableObject {
         isReadyForRecording = false
         let registrations: [(String, RecordingsCLI.CanonicalProject)]
         do {
-            registrations = try await Task.detached(priority: .utility) {
+            registrations = try await BlockingOperation.runThrowing(qos: .utility) {
                 try original.projects.map { project in
                     let canonical = try RecordingsCLI.registerProject(
                         name: project.name,
@@ -297,7 +297,7 @@ public final class ProjectStore: ObservableObject {
                     )
                     return (project.id, canonical)
                 }
-            }.value
+            }
         } catch {
             let message = "Failed to register projects: \((error as? RecordingsCLI.Failure)?.message ?? error.localizedDescription)"
             synchronizationError = message
@@ -347,9 +347,9 @@ public final class ProjectStore: ObservableObject {
         let local = RecProject(name: name, path: path, systemPrompt: systemPrompt, color: color)
         let canonical: RecordingsCLI.CanonicalProject
         do {
-            canonical = try await Task.detached(priority: .userInitiated) {
+            canonical = try await BlockingOperation.runThrowing {
                 try RecordingsCLI.registerProject(name: local.name, path: local.registrationPath, home: home)
-            }.value
+            }
         } catch {
             persistenceError = "Failed to register project: \((error as? RecordingsCLI.Failure)?.message ?? error.localizedDescription)"
             throw error