@hasna/recordings 0.2.13 → 0.3.1

package/scripts/vacuity-manifest-gen.ts

@@ -0,0 +1,96 @@
+/**
+ * Generates the test-literal mutation manifest for the vacuity battery (OPE41-00029).
+ *
+ * This exists instead of a committed manifest of byte offsets. Offsets are correct for exactly one
+ * revision of the test files: the first commit that adds a comment above a converted site shifts
+ * every offset below it, and the battery then reports MUTATION-NOT-APPLIED for rows that were fine.
+ * That happened — 66 of 176 rows went stale in one commit — and while the driver refuses to score a
+ * mutation it could not apply, a stale manifest still costs a full run and reads like a coverage
+ * hole. Generating from the current tree removes the failure mode rather than documenting it.
+ *
+ * For every `expectOrder` / `sliceBetween` / `sliceBetweenUnique` call site it emits one `corrupt`
+ * row per string-literal operand: append a sentinel to that literal in the test file, which is
+ * equivalent — from the assertion's point of view — to deleting the needle from the source, but
+ * needs no map from haystack variable to source path and leaves the script under test byte-identical
+ * so the run still succeeds and only the converted assertion can fail.
+ *
+ * Operands that are `const` variables rather than literals are NOT emitted here; those are covered
+ * by the source-side rows in scripts/vacuity-manifests/variable-operands.tsv.
+ *
+ * Usage: bun scripts/vacuity-manifest-gen.ts > /tmp/corrupt-sites.tsv
+ */
+import { readFileSync } from "node:fs";
+import { Glob } from "bun";
+
+const HELPERS = /\b(expectOrder|sliceBetweenUnique|sliceBetween)\s*\(/g;
+
+/** The nearest enclosing `it(...)` / `test(...)` name, used as the `-t` filter. */
+function enclosingTest(source: string, position: number): string | undefined {
+  let best: string | undefined;
+  const pattern = /\b(?:it|test)\s*\(\s*(["'`])((?:\\.|(?!\1).)*)\1/g;
+  let match: RegExpExecArray | null;
+  while ((match = pattern.exec(source))) {
+    if (match.index >= position) break;
+    best = match[2];
+  }
+  return best;
+}
+
+/** Top-level string-literal arguments of a call, as [offset-of-inner-text, raw-inner-text]. */
+function literalArguments(source: string, openParen: number): Array<[number, string]> {
+  const found: Array<[number, string]> = [];
+  let index = openParen + 1;
+  let depth = 1;
+  while (index < source.length && depth > 0) {
+    const character = source[index];
+    if (character === "(") depth++;
+    else if (character === ")") depth--;
+    else if (character === '"' || character === "'" || character === "`") {
+      const quote = character;
+      const start = ++index;
+      while (index < source.length && source[index] !== quote) {
+        if (source[index] === "\\") index++;
+        index++;
+      }
+      if (depth === 1) found.push([start, source.slice(start, index)]);
+    }
+    index++;
+  }
+  return found;
+}
+
+/** TSV cannot carry a real tab or newline. Backslash sequences pass through untouched, because the
+ *  mutation compares the file's RAW bytes and `\n` inside a TS literal is two of them. */
+function escapeForTsv(text: string): string {
+  return text.replace(/\t/g, "\\t").replace(/\n/g, "\\n");
+}
+
+const emitted = new Set<string>();
+const lines: string[] = [
+  "# GENERATED by scripts/vacuity-manifest-gen.ts - do not hand-edit, regenerate.",
+  "# kind\ttestFile\ttestName\ttargetFile\toffset\tliteral",
+];
+
+for (const path of new Glob("src/**/*.test.ts").scanSync(".")) {
+  // The guards suite calls the helpers on hand-built strings to prove they THROW. Its literals are
+  // fixtures, not needles into a real source file, so corrupting them measures nothing about the
+  // repo and only adds noise to the tally.
+  if (path.endsWith("source-assertions-guards.test.ts")) continue;
+  const source = readFileSync(path, "utf8");
+  HELPERS.lastIndex = 0;
+  let call: RegExpExecArray | null;
+  while ((call = HELPERS.exec(source))) {
+    const testName = enclosingTest(source, call.index);
+    if (!testName) continue;
+    for (const [offset, raw] of literalArguments(source, call.index + call[0].length - 1).slice(0, 2)) {
+      if (raw.length < 3) continue;
+      const key = `${path}:${offset}`;
+      if (emitted.has(key)) continue;
+      emitted.add(key);
+      lines.push(`corrupt\t${path}\t${testName}\t${path}\t${offset}\t${escapeForTsv(raw)}`);
+    }
+  }
+}
+
+console.log(lines.join("\n"));
+console.error(`generated ${emitted.size} corrupt rows`);

package/scripts/vacuity-manifests/enhancement-screen-mirror.tsv

@@ -0,0 +1,44 @@
+# Re-derivation battery for the guards PR #35 introduces (todos 96546cc7).
+#
+# Scope: enhancer.test.ts (the PR's cross-language fixture twins) and
+# enhancement-screen-mirror-contract.test.ts (added because the three claims below were
+# enforced by nothing runnable on Linux). The three station-contended suites are NOT in scope;
+# an already-red target makes every mutation look caught. The Swift suites cannot run here at
+# all -- no Swift toolchain exists on this machine -- so every row below is a TEXT-level check.
+#
+# Rows marked MUST-SURVIVE are controls in the sense of must-survive-controls.tsv, so this
+# manifest exits 1 by design and is not wired into a package.json aggregate script.
+#
+# --- TS side of the cross-language twin. Bound before this task; kept as regression coverage.
+delete	src/__tests__/enhancer.test.ts	enhances: make this sound more professional	src/lib/enhancer.ts	professional|	1
+delete	src/__tests__/enhancer.test.ts	passes through: draft beer is better than bottled in my opinion	src/lib/enhancer.ts	(?:email|message|response|reply|letter|note|text|slack|dm)	1
+# --- SWIFT regex mirror drift. SURVIVED before enhancement-screen-mirror-contract existed:
+# nothing on Linux read EnhancementScreen.swift, so the 'byte-identical' claim was unenforced.
+delete	src/__tests__/enhancement-screen-mirror-contract.test.ts	the instruction pattern sources are byte-identical in the CLI and the Swift mirror	src/native/Recordings/RecordingsLib/EnhancementScreen.swift	professional|	1
+# --- and the same drift introduced on the CLI side must break identity too, not just behaviour.
+delete	src/__tests__/enhancement-screen-mirror-contract.test.ts	the instruction pattern sources are byte-identical in the CLI and the Swift mirror	src/lib/enhancer.ts	professional|	1
+# --- 'shared verbatim fixture table'. SURVIVED before: the tables were the same text only by
+# convention, and the TS fixtures exercised the TS implementation alone.
+delete	src/__tests__/enhancement-screen-mirror-contract.test.ts	the cross-language fixture table is the same text in both suites	src/native/Recordings/RecordingsTests/EnhancementScreenTests.swift	"draft beer is better than bottled in my opinion"	1
+# --- review F2's fail-closed contract at the PRODUCTION call site. SURVIVED before.
+delete	src/__tests__/enhancement-screen-mirror-contract.test.ts	every Swift call site of shouldPasteBeforePersistence states enhanceTriggersJSON	src/native/Recordings/RecordingsLib/RecordingEngine.swift	,\n                    enhanceTriggersJSON: processingConfiguration.enhanceTriggersJSON\n	1
+# --- and at a test call site: these five were shipped without the argument at all, which does
+# not compile. Swift catches that on macOS; this row makes Linux catch it too.
+delete	src/__tests__/enhancement-screen-mirror-contract.test.ts	every Swift call site of shouldPasteBeforePersistence states enhanceTriggersJSON	src/native/Recordings/RecordingsTests/SpeechIntentTests.swift	,\n            enhanceTriggersJSON: "[]"	1
+# --- MUST-SURVIVE: a neutral comment deletion in the CLI must not trip the fixture twins.
+delete	src/__tests__/enhancer.test.ts	enhances: make this sound more professional	src/lib/enhancer.ts	  // Check instruction patterns\n	1
+# --- MUST-SURVIVE: nor may a comment deletion in the Swift mirror trip the identity guard --
+# otherwise the guard is a whole-file checksum rather than an assertion about the patterns.
+delete	src/__tests__/enhancement-screen-mirror-contract.test.ts	the instruction pattern sources are byte-identical in the CLI and the Swift mirror	src/native/Recordings/RecordingsLib/EnhancementScreen.swift	/// Deterministic local pre-screen for the CLI's enhancement decision.\n	1
+
+# --- ADVERSARIAL REVIEW ADDITION (todos 96546cc7). The one place the mirror was LESS
+# conservative than the CLI: `needsEnhancement` tests `lower.includes(trigger.toLowerCase())` and
+# JS `includes("")` is true for every string, so one empty row in enhance_triggers makes the
+# helper rewrite every transcript. Foundation's `contains("")` is FALSE, so the mirror has to
+# special-case the row. It skipped it instead, and deleting the skip SURVIVED all three guards --
+# the fixture twins pin transcript text, never trigger lists. Deleting the fail-closed branch now
+# breaks the new guard's source assertion.
+delete	src/__tests__/enhancement-screen-mirror-contract.test.ts	an empty configured trigger makes both implementations fail closed	src/native/Recordings/RecordingsLib/EnhancementScreen.swift	            guard !loweredTrigger.isEmpty else { return true }\n	1
+# --- and the CLI half of the same claim: deleting the trigger scan makes needsEnhancement stop
+# treating an empty row as a match.
+delete	src/__tests__/enhancement-screen-mirror-contract.test.ts	an empty configured trigger makes both implementations fail closed	src/lib/enhancer.ts	    if (lower.includes(trigger.toLowerCase())) {	1

package/scripts/vacuity-manifests/install-chain.tsv

@@ -0,0 +1,13 @@
+# The "not TSV-expressible" chain markers, expressed via occurrence index instead of a line delete.
+# A bare identifier's FIRST occurrence is the shell function DEFINITION (`name() {`), which is why a
+# newline-free needle appeared unusable; the CALL site is simply a later occurrence.
+delete	src/__tests__/install-maintenance.test.ts	orders exclusivity before recovery and the authoritative stopped-state copy	scripts/install_macos_app.sh	acquire_maintenance_marker	2
+delete	src/__tests__/install-maintenance.test.ts	orders exclusivity before recovery and the authoritative stopped-state copy	scripts/install_macos_app.sh	drain_store_reader_leases	2
+delete	src/__tests__/install-maintenance.test.ts	orders exclusivity before recovery and the authoritative stopped-state copy	scripts/install_macos_app.sh	acquire_sqlite_barrier	3
+delete	src/__tests__/install-maintenance.test.ts	orders exclusivity before recovery and the authoritative stopped-state copy	scripts/install_macos_app.sh	acquire_sqlite_barrier	5
+delete	src/__tests__/install-maintenance.test.ts	orders exclusivity before recovery and the authoritative stopped-state copy	scripts/install_macos_app.sh	acquire_sqlite_barrier	6
+delete	src/__tests__/install-maintenance.test.ts	orders exclusivity before recovery and the authoritative stopped-state copy	scripts/install_macos_app.sh	stop_old_processes	3
+delete	src/__tests__/install-maintenance.test.ts	orders exclusivity before recovery and the authoritative stopped-state copy	scripts/install_macos_app.sh	stop_old_processes	4
+delete	src/__tests__/install-maintenance.test.ts	orders exclusivity before recovery and the authoritative stopped-state copy	scripts/install_macos_app.sh	stop_old_processes	5
+delete	src/__tests__/install-maintenance.test.ts	orders exclusivity before recovery and the authoritative stopped-state copy	scripts/install_macos_app.sh	trap cleanup_install_coordination_and_work EXIT	1
+delete	src/__tests__/install-maintenance.test.ts	orders exclusivity before recovery and the authoritative stopped-state copy	scripts/install_macos_app.sh	write_journal processes-stopped	1

package/scripts/vacuity-manifests/must-survive-controls.tsv

@@ -0,0 +1,10 @@
+# DELIBERATE MUST-SURVIVE CONTROL. `options: .atomic` occurs twice in RecordingsApp.swift and only
+# the SECOND is inside the region under test. Deleting the FIRST (the runtimeSmokeOutput evidence
+# write, outside the region) MUST leave the test green. A battery that reports KILLED here is
+# over-matching, and would send someone to "fix" a guard that is working correctly.
+delete	src/__tests__/macos-smoke-process-identity.test.ts	uses challenge-bound completion with identity-verified failure cleanup	src/native/Recordings/App/RecordingsApp.swift	options: .atomic	1
+# Deleting one of FOUR legitimate `run_swift build` invocations must NOT fail: "tests precede any
+# build" is still true with three left. The reorder in reorder.tsv is the mutation that proves that
+# ordering claim is live. A harness that flagged this as a survivor would be over-matching.
+delete	src/__tests__/native-release-build-hardening-contract.test.ts	pins a clean full source revision before native compilation	src/native/Recordings/build.sh	run_swift build -c "$BUILD_CONFIGURATION"	1
+delete	src/__tests__/macos-artifact-binding.test.ts	verification and durability gates precede final manifest publication	scripts/macos_artifact.ts	fsyncSync(descriptor)	1

package/scripts/vacuity-manifests/reorder.tsv

@@ -0,0 +1,4 @@
+# The semantically meaningful mutation for a 1-of-4 needle: REORDER, not delete. Deleting one of the
+# four legitimate `run_swift build` invocations correctly survives, because "tests precede any build"
+# is still true. Swapping the test past the first build is the mutation the assertion exists for.
+swap	src/__tests__/native-release-build-hardening-contract.test.ts	pins a clean full source revision before native compilation	src/native/Recordings/build.sh	run_swift test -c "$BUILD_CONFIGURATION"	run_swift build -c "$BUILD_CONFIGURATION"

package/scripts/vacuity-manifests/source-side.tsv

@@ -0,0 +1,15 @@
+# Source-side mutations for sites whose expectOrder operands are VARIABLES, so the offset-precise
+# test-literal corruption cannot reach them. Occurrence indices are load-bearing.
+delete	src/__tests__/release-output-publication-contract.test.ts	package notarization also verifies the log digest before stapling	packaging/macos/build_release_pkg.sh	SUBMITTED_PKG_SHA256="$(sha256_file "$PKG")"	1
+delete	src/__tests__/release-output-publication-contract.test.ts	package notarization also verifies the log digest before stapling	packaging/macos/build_release_pkg.sh	"$STAGED_VERIFIER" assert-notary-log	1
+delete	src/__tests__/release-output-publication-contract.test.ts	package notarization also verifies the log digest before stapling	packaging/macos/build_release_pkg.sh	--submitted-archive-sha256 "$SUBMITTED_PKG_SHA256"	1
+delete	src/__tests__/release-output-publication-contract.test.ts	package notarization also verifies the log digest before stapling	packaging/macos/build_release_pkg.sh	/usr/bin/xcrun stapler staple	1
+swap	src/__tests__/release-output-publication-contract.test.ts	package notarization also verifies the log digest before stapling	packaging/macos/build_release_pkg.sh	--submission-id	--submitted-archive-sha256
+delete	src/__tests__/macos-smoke-process-identity.test.ts	uses challenge-bound completion with identity-verified failure cleanup	src/native/Recordings/App/RecordingsApp.swift	options: .atomic	2
+duplicate	src/__tests__/macos-smoke-process-identity.test.ts	uses challenge-bound completion with identity-verified failure cleanup	src/native/Recordings/App/RecordingsApp.swift	Darwin._exit(0)	1
+delete	src/__tests__/macos-smoke-process-identity.test.ts	uses challenge-bound completion with identity-verified failure cleanup	scripts/smoke_macos_app.sh	cleanup()	1
+delete	src/__tests__/macos-artifact-command-pinning.test.ts	production requirement digests use the Darwin-pinned codesign executable	scripts/macos_artifact.ts	function assertFilesystemTree(	1
+# The two residual vacuities the semantics reviewer found. Both PASSED before the fix; both must
+# now be KILLED. Occurrence 1 is the authoritative site in each case.
+delete	src/__tests__/install-maintenance.test.ts	orders exclusivity before recovery and the authoritative stopped-state copy	scripts/install_macos_app.sh	write_journal processes-stopped	1
+delete	src/__tests__/tailscale-cli-resolution.test.ts	keeps all test app and tool overrides after the real Darwin branch	scripts/resolve_tailscale_cli.sh	codesign_executable="${RECORDINGS_TEST_TAILSCALE_CODESIGN_EXECUTABLE:-/usr/bin/codesign}"	1

package/scripts/vacuity-manifests/variable-operands.tsv

@@ -0,0 +1,16 @@
+delete	src/__tests__/native-release-build-hardening-contract.test.ts	normalizes umask-077 staging before nested signing and finalizes data before app signing	src/native/Recordings/build.sh	normalize_unsigned_app_bundle_modes "$APP_DIR"	1
+delete	src/__tests__/native-release-build-hardening-contract.test.ts	normalizes umask-077 staging before nested signing and finalizes data before app signing	src/native/Recordings/build.sh	run_bun "$SOURCE_PACKAGE_ROOT/scripts/macos_artifact.ts" provenance	1
+delete	src/__tests__/native-release-build-hardening-contract.test.ts	normalizes umask-077 staging before nested signing and finalizes data before app signing	src/native/Recordings/build.sh	run_codesign "${APP_SIGN_ARGUMENTS[@]}"	1
+delete	src/__tests__/native-release-build-hardening-contract.test.ts	normalizes umask-077 staging before nested signing and finalizes data before app signing	src/native/Recordings/build.sh	run_codesign "${HELPER_SIGN_ARGUMENTS[@]}"	1
+delete	src/__tests__/native-release-build-hardening-contract.test.ts	normalizes umask-077 staging before nested signing and finalizes data before app signing	src/native/Recordings/build.sh	run_sensitive_tool "$DITTO_EXECUTABLE" "$APP_DIR" "$OUTPUT_APP_DIR"	1
+delete	src/__tests__/native-release-build-hardening-contract.test.ts	pins a clean full source revision before native compilation	src/native/Recordings/build.sh	run_swift build -c "$BUILD_CONFIGURATION"	1
+delete	src/__tests__/native-release-build-hardening-contract.test.ts	pins a clean full source revision before native compilation	src/native/Recordings/build.sh	run_swift test -c "$BUILD_CONFIGURATION"	1
+delete	src/__tests__/native-release-build-hardening-contract.test.ts	pins a validated macOS SDK sysroot before compiling the descriptor guard	scripts/build_native_fs_guard.sh	"$CLANG" "${COMMON[@]}" -arch arm64	1
+delete	src/__tests__/native-release-build-hardening-contract.test.ts	pins bootstrap path tools before deriving the source tree	src/native/Recordings/build.sh	HOST_UNAME_EXECUTABLE="/usr/bin/uname"	1
+delete	src/__tests__/native-release-build-hardening-contract.test.ts	pins bootstrap path tools before deriving the source tree	src/native/Recordings/build.sh	SYSTEM_DIRNAME_EXECUTABLE="/usr/bin/dirname"	1
+delete	src/__tests__/native-release-build-hardening-contract.test.ts	pins bootstrap path tools before deriving the source tree	src/native/Recordings/build.sh	SYSTEM_PWD_EXECUTABLE="/bin/pwd"	1
+delete	src/__tests__/native-release-build-hardening-contract.test.ts	ships a pinned universal descriptor guard and fails closed before installer mutation	scripts/install_macos_app.sh	"$BUN_EXECUTABLE" "$ARTIFACT_TOOL" native-fs-guard-check	1
+delete	src/__tests__/release-output-publication-contract.test.ts	package notarization also verifies the log digest before stapling	packaging/macos/build_release_pkg.sh	"$STAGED_VERIFIER" assert-notary-log	1
+delete	src/__tests__/release-output-publication-contract.test.ts	package notarization also verifies the log digest before stapling	packaging/macos/build_release_pkg.sh	--submitted-archive-sha256 "$SUBMITTED_PKG_SHA256"	1
+delete	src/__tests__/release-output-publication-contract.test.ts	package notarization also verifies the log digest before stapling	packaging/macos/build_release_pkg.sh	SUBMITTED_PKG_SHA256="$(sha256_file "$PKG")"	1
+delete	src/__tests__/release-output-publication-contract.test.ts	package notarization also verifies the log digest before stapling	packaging/macos/build_release_pkg.sh	/usr/bin/xcrun stapler staple	1

package/scripts/vacuity-manifests/version-sites.tsv

@@ -0,0 +1,61 @@
+# Re-derivation battery for the version-site guards (todos 96546cc7), measured on 15303a6.
+#
+# Scope is named explicitly and EXCLUDES the three permanently-red files on this tree
+# (macos-app-lifecycle.test.ts, native-app-companion-contract.test.ts, config.test.ts). An
+# already-red target makes every mutation look caught -- the inverse trap. The driver's
+# RED-ON-CLEAN control enforces that mechanically; the scope is written down so a reader can
+# check it without running anything.
+#
+# Expected verdict for every row below is a kill, EXCEPT the rows explicitly marked
+# MUST-SURVIVE or EXPECTED-SURVIVOR. The driver reports these kills as
+# KILLED-UNATTRIBUTED because these guards assert with `expect` rather than emitting one of the
+# GUARD_SIGNAL messages; attribution was completed by confirming each failure lands on the
+# guard's own assertion line, not on an early throw. GUARD_SIGNAL was deliberately NOT widened
+# to make this file exit 0 -- and, for the same reason must-survive-controls.tsv is not, this
+# manifest is not wired into a package.json aggregate script.
+#
+# --- every version site agrees with package.json. Models 8de7068: one site bumped, the rest not.
+duplicate	src/__tests__/version-site-guard.test.ts	agree in the working tree, on the version package.json declares	src/version.ts	.15	1
+duplicate	src/__tests__/version-site-guard.test.ts	agree in the working tree, on the version package.json declares	src/native/Recordings/RecordingsLib/Info.plist	0.2.15	1
+duplicate	src/__tests__/version-site-guard.test.ts	agree in the working tree, on the version package.json declares	src/native/Recordings/RecordingsLib/Info.plist	0.2.15	2
+# --- a stale site is reported, not silently accepted: the mismatch filter removed.
+delete	src/__tests__/version-site-guard.test.ts	a single stale site is reported rather than silently accepted	scripts/set-version.ts	.filter((reading) => reading.version !== expected)	1
+# --- applyVersion writes every site in one pass: the per-file grouping removed.
+delete	src/__tests__/version-site-guard.test.ts	applyVersion rewrites every site in one pass	scripts/set-version.ts	.filter((candidate) => candidate.file === file)	1
+# --- A DROPPED SITE. The writer silently stops writing a plist key the release path reads, and
+# every site that remains still agrees. Both rows SURVIVED the original assertions
+# (`readings).toHaveLength(versionSites.length)` compares the array to its own source, and
+# `not.toContain("0.0.1")` is satisfied by a key that was never written at all). They are the
+# reason both assertions were re-pointed to independent literal expectations.
+delete	src/__tests__/version-site-guard.test.ts	applyVersion rewrites every site in one pass	scripts/set-version.ts	  {\n    file: "src/native/Recordings/RecordingsLib/Info.plist",\n    label: "Info.plist CFBundleVersion",\n    pattern: /(<key>CFBundleVersion<\/key>\s*<string>)([^<]+)(<\/string>)/,\n  },\n	1
+delete	src/__tests__/version-site-guard.test.ts	agree in the working tree, on the version package.json declares	scripts/set-version.ts	  {\n    file: "src/native/Recordings/RecordingsLib/Info.plist",\n    label: "Info.plist CFBundleVersion",\n    pattern: /(<key>CFBundleVersion<\/key>\s*<string>)([^<]+)(<\/string>)/,\n  },\n	1
+# --- version-format rejection, one anchor at a time. Occurrence 5 of "^" and occurrence 1 of "$"
+# are the two anchors in assertReleaseVersion; the indices are load-bearing. The "$" row SURVIVED
+# until a junk-suffixed case was added, because `v1.2.3` binds only the leading anchor.
+delete	src/__tests__/version-site-guard.test.ts	rejects versions the release path already refuses	scripts/set-version.ts	^	5
+delete	src/__tests__/version-site-guard.test.ts	rejects versions the release path already refuses	scripts/set-version.ts	$	1
+# --- prepack wiring. Nothing asserted version:check was in prepack at all; the one prepack needle
+# in the repo (native-release-build-hardening-contract's toStartWith) was broken outright by
+# putting version:check ahead of the fail-closed macOS gate.
+delete	src/__tests__/version-site-guard.test.ts	prepack checks the version sites after the platform gate and before the build	package.json	bun run version:check && 	1
+# --- MUST-SURVIVE CONTROL. A semantically neutral edit to the same file must NOT trip the guard.
+# A battery with no surviving control cannot distinguish a guard from a checksum.
+delete	src/__tests__/version-site-guard.test.ts	agree in the working tree, on the version package.json declares	scripts/set-version.ts	  /** Label used in check output. */\n	1
+
+# --- ADVERSARIAL REVIEW ADDITIONS (todos 96546cc7).
+#
+# The writer's OWN validation call. Deleting it left this whole file at 5 pass / 0 fail while
+# `bun run version:set v9.9.9` exited 0 and wrote `v9.9.9` into all four sites, after which
+# `version:check` reported them in agreement -- nothing else in the repo pins the version's
+# FORMAT. The first row is the guard added to catch it; the two EXPECTED-SURVIVOR rows are the
+# same mutation against the two pre-existing tests, kept because they are the measurement that
+# neither one ever bound the writer.
+delete	src/__tests__/version-site-guard.test.ts	the writer refuses a version the release path refuses, and writes nothing	scripts/set-version.ts	  assertReleaseVersion(version);\n	1
+# EXPECTED-SURVIVOR
+delete	src/__tests__/version-site-guard.test.ts	rejects versions the release path already refuses	scripts/set-version.ts	  assertReleaseVersion(version);\n	1
+# EXPECTED-SURVIVOR
+delete	src/__tests__/version-site-guard.test.ts	applyVersion rewrites every site in one pass	scripts/set-version.ts	  assertReleaseVersion(version);\n	1
+#
+# The generated SDK's version stamp -- a fifth copy of the release version that `versionSites`
+# deliberately does not write -- goes stale again.
+delete	src/__tests__/version-site-guard.test.ts	the generated SDK header carries the version package.json declares	src/sdk/v1.generated.ts	.15	1

package/scripts/vacuity-mutation-battery.ts

@@ -0,0 +1,266 @@
+/**
+ * Mutation battery for the indexOf/-1 vacuity sweep (OPE41-00029).
+ *
+ * A converted ordering assertion is only proven non-vacuous by an input that makes it FAIL. This
+ * driver takes a manifest of mutations and, for each one:
+ *
+ *   1. asserts the mutation actually CHANGED the file — a positive control, because a needle that
+ *      never matched, or an occurrence index past the last match, would otherwise read as a caught
+ *      mutation when nothing was mutated at all;
+ *   2. runs the target test CLEAN and requires it to PASS — without this control an already-red
+ *      test makes every mutation look caught, which is the inverse trap;
+ *   3. applies the mutation and requires the named test to FAIL;
+ *   4. restores the file byte-for-byte from the copy held in memory, never from git, so sibling
+ *      working-tree edits are never reverted.
+ *
+ * Mutation kinds, and why one is not enough:
+ *
+ *   delete     — remove the Nth occurrence of a needle. The occurrence index is not optional.
+ *                `options: .atomic` occurs twice in RecordingsApp.swift and only the SECOND is
+ *                inside the region under test, so deleting the first must stay GREEN; a harness
+ *                that always deletes the first records a false survivor and sends someone to
+ *                "fix" a guard that was working. Three more needles are masked the same way by an
+ *                earlier occurrence that is the helper's own DEFINITION rather than its call site.
+ *   swap       — exchange two needles' text so the ordering flips. An ordering assertion that
+ *                survives a REORDER is the same vacuity class this sweep exists to close wearing
+ *                different clothes, and it is entirely invisible to a deletion-only harness.
+ *   duplicate  — insert a second copy of a needle. This is what separates a uniqueness bound from
+ *                a bare `toContain`: the `toContain` stays green on a duplicate, the bound does not.
+ *   corrupt    — replace a string literal in the TEST at an exact byte offset with a sentinel that
+ *                cannot occur in any source. Equivalent, from the assertion's point of view, to
+ *                deleting that needle from the source, but it needs no map from haystack variable
+ *                to source path, so it covers every converted site mechanically.
+ *
+ * Needles may contain \n and \t as escapes, because several properties can only be pinned by a
+ * whole-line needle (a bare helper name matches its own definition first).
+ *
+ * Exit codes come from spawnSync status, never through a pipe. Runs are strictly serial: a sibling
+ * assertion in capture-probe.test.ts scans a shared /tmp, so concurrent suites corrupt each other.
+ *
+ * Usage: bun scripts/vacuity-mutation-battery.ts <manifest.tsv> [--only <substring>]
+ * Manifest, tab-separated: kind <TAB> testFile <TAB> testName <TAB> targetFile <TAB> a <TAB> b
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+
+type Kind = "delete" | "swap" | "duplicate" | "corrupt";
+type Row = { kind: Kind; testFile: string; testName: string; target: string; a: string; b: string };
+
+const [manifestPath, ...rest] = process.argv.slice(2);
+if (!manifestPath) {
+  console.error("usage: bun scripts/vacuity-mutation-battery.ts <manifest.tsv> [--only <substr>]");
+  process.exit(2);
+}
+const onlyIndex = rest.indexOf("--only");
+const only = onlyIndex >= 0 ? rest[onlyIndex + 1] : undefined;
+
+const rows: Row[] = readFileSync(manifestPath, "utf8")
+  .split("\n")
+  .filter((line) => line.trim() && !line.startsWith("#"))
+  .map((line, index) => {
+    const [kind, testFile, testName, target, a, b] = line.split("\t");
+    // Fail loudly on a malformed row. Redirecting the generator with `2>&1` merges its progress line
+    // into the manifest, which parsed as a row with an undefined target and crashed the driver 164
+    // rows in — after all the expensive work, and with a stack trace that named the wrong cause.
+    if (!kind || !testFile || !testName || !target) {
+      console.error(`manifest line ${index + 1} is malformed (${line.split("\t").length} fields): ${line.slice(0, 120)}`);
+      process.exit(2);
+    }
+    return { kind: kind as Kind, testFile, testName, target, a: a ?? "", b: b ?? "" };
+  })
+  .filter((r) => !only || `${r.testFile} ${r.testName} ${r.a}`.includes(only));
+
+/** Byte offset of the nth (1-based) occurrence, or -1. */
+function nthIndex(haystack: string, needle: string, n: number): number {
+  let at = -1;
+  for (let i = 0; i < n; i++) {
+    at = haystack.indexOf(needle, i === 0 ? 0 : at + 1);
+    if (at < 0) return -1;
+  }
+  return at;
+}
+
+/** TSV cannot carry literal tabs or newlines, so needles arrive escaped. */
+function unescape(text: string): string {
+  return text.replace(/\\n/g, "\n").replace(/\\t/g, "\t");
+}
+
+/** Apply a mutation, or return undefined — which the caller treats as a control FAILURE. */
+function mutate(row: Row, original: string): string | undefined {
+  const a = unescape(row.a);
+  const b = unescape(row.b);
+
+  if (row.kind === "corrupt") {
+    // Deliberately NOT unescaped: this mutates the test file's RAW bytes, and a `\n` inside a
+    // TypeScript string literal is two bytes on disk. Unescaping it would move the offset and the
+    // guard below would reject every row — silently, as a control failure rather than a survivor.
+    const offset = Number(row.a);
+    if (!Number.isFinite(offset)) return undefined;
+    if (original.slice(offset, offset + row.b.length) !== row.b) return undefined;
+    return (
+      original.slice(0, offset) +
+      row.b +
+      "__OPE41_00029_ABSENT__" +
+      original.slice(offset + row.b.length)
+    );
+  }
+
+  if (row.kind === "delete") {
+    const at = nthIndex(original, a, Number(row.b || "1"));
+    if (at < 0) return undefined;
+    return original.slice(0, at) + original.slice(at + a.length);
+  }
+
+  if (row.kind === "duplicate") {
+    const at = nthIndex(original, a, Number(row.b || "1"));
+    if (at < 0) return undefined;
+    return original.slice(0, at + a.length) + a + original.slice(at + a.length);
+  }
+
+  if (row.kind === "swap") {
+    const atA = original.indexOf(a);
+    const atB = original.indexOf(b);
+    if (atA < 0 || atB < 0 || a === b) return undefined;
+    const firstAt = Math.min(atA, atB);
+    const secondAt = Math.max(atA, atB);
+    const [first, second] = atA < atB ? [a, b] : [b, a];
+    if (firstAt + first.length > secondAt) return undefined; // overlapping; cannot swap cleanly
+    return (
+      original.slice(0, firstAt) +
+      second +
+      original.slice(firstAt + first.length, secondAt) +
+      first +
+      original.slice(secondAt + second.length)
+    );
+  }
+  return undefined;
+}
+
+/**
+ * `bun test -t` takes a REGEX, not a substring.
+ *
+ * A test named `rendering RecordingEngine.logResolvedTrigger()'s format string parses as expected`
+ * contains `()`, which as a pattern is an empty capture group, so the literal parentheses in the
+ * name are never matched and bun reports `matched 0 tests` and exits 1. Unescaped, that presented as
+ * RED-ON-CLEAN — a refusal to conclude rather than a false pass, but still two sites left unproven
+ * for a reason that had nothing to do with them.
+ */
+function escapeForTestFilter(name: string): string {
+  return name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function runTest(testFile: string, testName: string): { code: number; output: string } {
+  const filter = escapeForTestFilter(testName);
+  const result = spawnSync("bun", ["test", testFile, "-t", filter, "--timeout", "120000"], {
+    encoding: "utf8",
+    env: { ...process.env, NO_COLOR: "1" },
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  return { code: result.status ?? 1, output: `${result.stdout ?? ""}${result.stderr ?? ""}` };
+}
+
+/** Did the filter select anything? 0 pass 0 fail exits 0 and would read as a clean pass. */
+function ranSomething(output: string): boolean {
+  const p = output.match(/(\d+)\s+pass/);
+  const f = output.match(/(\d+)\s+fail/);
+  return (p ? Number(p[1]) : 0) + (f ? Number(f[1]) : 0) > 0;
+}
+
+type Verdict =
+  | "KILLED"
+  | "KILLED-UNATTRIBUTED"
+  | "SURVIVED"
+  | "MUTATION-NOT-APPLIED"
+  | "RED-ON-CLEAN"
+  | "FILTER-MATCHED-NOTHING";
+
+/**
+ * A red test is not automatically proof that the converted assertion fired.
+ *
+ * Most of these suites EXECUTE the script they also read, so deleting a needle from
+ * `install_macos_app.sh` can break the run and fail `expect(result.exitCode).toBe(0)` long before
+ * the ordering assertion is reached. The driver would see a non-zero exit and record KILLED while
+ * the assertion under test did nothing at all — a kill credited to the wrong cause is exactly the
+ * "evidence that does not prove the claim" this sweep exists to remove.
+ *
+ * So a kill only counts when the failure output carries one of the guard's own messages. Anything
+ * else is reported as KILLED-UNATTRIBUTED and proves nothing about the site.
+ *
+ * The patterns are deliberately fragments rather than whole sentences. Suites add their own named
+ * guards — "test override is missing entirely: ...", "resolver function is missing entirely: ..." —
+ * and a signal list enumerating only the helper's own wording reported those as UNATTRIBUTED, which
+ * cost two hand-attributions that the driver should have made itself.
+ */
+const GUARD_SIGNAL =
+  /(is missing entirely|marker is missing|marker is not unique|too small to assert anything about|is missing or out of order|no longer sanitizes)/;
+
+function attributed(output: string): boolean {
+  return GUARD_SIGNAL.test(output);
+}
+
+const results: { row: Row; verdict: Verdict }[] = [];
+const cleanCache = new Map<string, "ok" | "red" | "no-match">();
+
+for (const [n, row] of rows.entries()) {
+  const label = `[${n + 1}/${rows.length}] ${row.kind} ${row.testFile} :: ${row.testName}`;
+  const original = readFileSync(row.target, "utf8");
+
+  const mutated = mutate(row, original);
+  if (mutated === undefined || mutated === original) {
+    results.push({ row, verdict: "MUTATION-NOT-APPLIED" });
+    console.log(`${label}\n    MUTATION-NOT-APPLIED  ${row.a.slice(0, 70)}`);
+    continue;
+  }
+
+  // The cache records WHY a clean run was unusable, not merely that it was. Collapsing both causes
+  // into one boolean made every row after the first report RED-ON-CLEAN, so a broken `-t` filter
+  // masqueraded as a failing test and pointed the reader at the wrong thing to fix.
+  const cleanKey = `${row.testFile} ${row.testName}`;
+  if (!cleanCache.has(cleanKey)) {
+    const clean = runTest(row.testFile, row.testName);
+    cleanCache.set(
+      cleanKey,
+      !ranSomething(clean.output) ? "no-match" : clean.code === 0 ? "ok" : "red",
+    );
+  }
+  const cleanState = cleanCache.get(cleanKey);
+  if (cleanState !== "ok") {
+    const verdict: Verdict = cleanState === "no-match" ? "FILTER-MATCHED-NOTHING" : "RED-ON-CLEAN";
+    results.push({ row, verdict });
+    console.log(`${label}\n    ${verdict} - no mutation verdict can be drawn here`);
+    continue;
+  }
+
+  try {
+    writeFileSync(row.target, mutated, "utf8");
+    const after = runTest(row.testFile, row.testName);
+    const verdict: Verdict =
+      after.code === 0 ? "SURVIVED" : attributed(after.output) ? "KILLED" : "KILLED-UNATTRIBUTED";
+    results.push({ row, verdict });
+    console.log(`${label}\n    ${verdict} (mutated exit ${after.code})  ${row.a.slice(0, 60)}`);
+  } finally {
+    writeFileSync(row.target, original, "utf8");
+  }
+}
+
+const tally = results.reduce<Record<string, number>>((acc, r) => {
+  acc[r.verdict] = (acc[r.verdict] ?? 0) + 1;
+  return acc;
+}, {});
+console.log(`\n==== BATTERY SUMMARY (${results.length} mutations) ====`);
+for (const [verdict, count] of Object.entries(tally).sort()) console.log(`${verdict}: ${count}`);
+
+const notKilled = results.filter((r) => r.verdict !== "KILLED");
+if (notKilled.length) {
+  console.log(`\n---- NOT KILLED (${notKilled.length}) ----`);
+  for (const s of notKilled) {
+    console.log(
+      `${s.verdict}\t${s.row.kind}\t${s.row.testFile}\t${s.row.testName}\t${s.row.a.slice(0, 60)}`,
+    );
+  }
+}
+
+// An instrument that always exits 0 is not a gate. Anything other than a clean kill — a survivor, a
+// kill credited to the wrong cause, or a control that could not be applied — has to be able to fail
+// a caller, or the summary is decoration that a script above it will happily ignore.
+process.exit(notKilled.length === 0 ? 0 : 1);

package/src/native/Recordings/App/MenuBarStatusView.swift

@@ -13,8 +13,10 @@ struct MenuBarStatusLabel: View {
     private var presentation: MenuBarPresentation {
         MenuBarPresentation(
             isRecording: store.engine.isRecording,
+            isWarmingUpCapture: store.engine.isWarmingUpCapture,
             canStartRecording: store.engine.canStartRecording,
-            statusMessage: store.engine.statusMessage
+            statusMessage: store.engine.statusMessage,
+            blockedReason: store.engine.blockedReason
         )
     }
 }
@@ -43,7 +45,7 @@ struct MenuBarStatusView: View {
                     .frame(maxWidth: .infinity)
             }
             .buttonStyle(.borderedProminent)
-            .tint(store.engine.isRecording ? .red : .accentColor)
+            .tint(store.engine.captureIsActive ? .red : .accentColor)
             .disabled(!presentation.primaryActionEnabled)
 
             Divider()
@@ -73,27 +75,32 @@ struct MenuBarStatusView: View {
     }
 
     private var statusColor: Color {
-        store.engine.isRecording ? .red : .accentColor
+        if store.engine.captureIsActive { return .red }
+        // The popover repeats the menu-bar signal rather than relying on the caption text, which
+        // is rendered `.secondary` and reads as an aside.
+        return presentation.isBlocked ? .orange : .accentColor
     }
 
     private var presentation: MenuBarPresentation {
         MenuBarPresentation(
             isRecording: store.engine.isRecording,
+            isWarmingUpCapture: store.engine.isWarmingUpCapture,
             canStartRecording: store.engine.canStartRecording,
-            statusMessage: store.engine.statusMessage
+            statusMessage: store.engine.statusMessage,
+            blockedReason: store.engine.blockedReason
         )
     }
 
     private var recordButtonTitle: String {
-        store.engine.isRecording ? "Stop and Transcribe" : "Start Recording"
+        store.engine.captureIsActive ? "Stop and Transcribe" : "Start Recording"
     }
 
     private var recordButtonIcon: String {
-        store.engine.isRecording ? "stop.fill" : "mic.fill"
+        store.engine.captureIsActive ? "stop.fill" : "mic.fill"
     }
 
     private func toggleRecording() {
-        if store.engine.isRecording {
+        if store.engine.captureIsActive {
             store.engine.stopAndTranscribe()
         } else {
             store.engine.startRecording()

package/src/native/Recordings/App/RuntimeSmoke.swift

@@ -21,8 +21,12 @@ final class RuntimeSmokeProbe: ObservableObject {
     var presentation: MenuBarPresentation {
         MenuBarPresentation(
             isRecording: phase == .recording,
+            // The smoke probe drives phases directly and never runs a real recorder, so it has
+            // no warm-up window.
+            isWarmingUpCapture: false,
             canStartRecording: phase == .idle,
-            statusMessage: phase == .transcribing ? "Transcribing" : "Ready"
+            statusMessage: phase == .transcribing ? "Transcribing" : "Ready",
+            blockedReason: nil
         )
     }
 

package/src/native/Recordings/App/SidebarView.swift

@@ -37,7 +37,7 @@ struct SidebarView: View {
                 withAnimation(.spring(response: 0.3, dampingFraction: 0.85)) { store.pane = .record }
             } label: {
                 rowLabel(icon: "mic.fill", label: "Record", count: nil,
-                         selected: store.pane == .record, accentDot: store.engine.isRecording)
+                         selected: store.pane == .record, accentDot: store.engine.captureIsActive)
             }
             .buttonStyle(.plain)
         }