testbench: drive meter routing with exact restore

[Rzbck]

Scope

Stacked on testbench/meter-feedback-closure.

This PR adds a deliberately write-capable TestBench-only campaign to exercise Scarlett 18i20 (3rd Gen) mix/output meter paths efficiently with one existing PC Playback source, then restore every temporary hardware state from server-confirmed baselines.

It intentionally changes no production src/ code and no module version. Companion must remain on the exact previously audited/live-validated 0.1.16 package; do not install the package rebuilt by this branch.

Why separate from the read-only meter PR

The first real read-only baseline proved two things:

• the r9 meter threshold is -128, equal to the server meter floor, so closure must use numeric floor + real movement rather than a false/true transition;
• random SIGNAL passes are inefficient for paths that are not currently routed.

PR #1 keeps the collector/read-only evidence model. This stacked PR is the explicitly authorised temporary-routing campaign.

Safety / write contract

The launcher now performs a read-only preparation/audit first, before asking for any write permission.

If the current V8 capability-lab harness is not already present exactly on Companion Page 2, it offers the explicit PAGE2_AUTO preparation path. That path reuses the already-tested Companion single-page import mechanism: it replaces only Page 2, preserves audited Page 1, preserves the existing connection set, remaps to the existing Focusrite connection, performs no Focusrite hardware write, then re-runs the read-only preparation audit. If preparation remains uncertain, the hardware campaign stays blocked.

Only after Page 2 preparation is confirmed does the launcher require both typed hardware confirmations:

• ROUTE_METERS
• ALL_ISOLATED

Temporary writes are restricted to already-tested Companion actions:

• mixer strip gain/mute/solo;
• stereo output_pair_source routing.

The campaign does not intentionally use:

• direct Focusrite Control Server <set>;
• Mixer Slot Source/Stereo writes;
• Advanced Raw;
• Monitor gain 1677;
• direct right-member pair-owned Source writes;
• device preset / clock source / sample rate / S/PDIF mode;
• firmware/reset/restore/snapshot commands;
• meter/status writes.

Output pairs with UNKNOWN or UNAVAILABLE availability are omitted from the generated drive surface, and availability is checked again immediately before each pair drive.

Playback source

The campaign does not invent a mixer-slot assignment. It scans the existing server-confirmed mixer-slot Source/Source Name variables, chooses an existing Playback source (preferring stereo), and stops before hardware writes if none exists.

Exact restore

• every touched mix lane requires known gain/mute/solo baselines;
• a write attempt is marked active before awaiting the Companion press, so a transport/API failure after partial application still enters exact restoration;
• no restore failure is thrown from a finally; the restore error is retained and rethrown afterward with the original caught error preserved as cause;
• each lane is restored and server-verified before the next lane;
• output pairs require both original source baselines;
• pair restore attempts themselves are inside the restore/quarantine guard, so a failed restore press cannot bypass quarantine handling;
• pair Source=None guards are used where exact-restorable/available;
• each output-pair drive restores both original source values and verifies them;
• failed pair restore attempts Source=None quarantine and hard-aborts;
• active-change bookkeeping remains non-empty until exact restore is confirmed;
• final local report records hardwareRestored and Page 2 restore state.

Temporary routing Page 2 import preserves Page 1, all other pages and the existing Focusrite connection, then restores the original audited capability-lab Page 2 used for the campaign.

Inputs

The eight analogue input meters are not faked by digital routing. After mixer/output routing is restored, the campaign only offers read-only INPUT_SIGNAL captures. Full input closure still requires real physical input signal (or a later separately guided physical loop).

Tests / software gate

Routing safety tests cover:

• gain-only custom lane drive;
• UNKNOWN/UNAVAILABLE pair omission;
• no unsafe appended action families;
• exact-restorable lane/pair baseline requirements;
• existing Playback selection;
• restore-error causal chaining;
• write-attempt tracking before awaiting Companion batch execution;
• no direct protocol write/unsafe action escape hatch;
• dual permission/isolation flags;
• Page 2/connection preservation contract;
• read-only fail-closed Page 2 preparation;
• launcher ordering: prepare/audit before ROUTE_METERS / ALL_ISOLATED;
• guarded Windows launcher + canonical LF Git blob.

Canonical local Windows gate completed successfully on tested HEAD 44df548806d0f4998a9efa05998b67ab6e0d4e58:

• Node 22.23.2 / Yarn 4.17.0
• immutable dependencies PASS
• Prettier PASS
• ESLint PASS
• source manifest PASS
• 175 / 175 tests PASS
• Companion package build PASS
• RUN OK

The rebuilt focusrite-scarlett-18i20-0.1.16.tgz is only a gate artifact and must not be installed. Companion stays on the exact previously audited/live-validated 0.1.16 archive.

Hardware campaign state

Software gate is complete. Next action is the explicitly confirmed meter-routing exact-restore hardware campaign on the tested HEAD above.

Before running:

• keep Companion on the existing audited 0.1.16 connection;
• lower the physical Monitor knob;
• mute/disconnect active speakers if practical;
• remove headphones or set them to minimum;
• do not run during a live show or critical recording.

Expected launcher flow:

1. read-only Page 2 preparation audit;
2. if required, explicit PAGE2_AUTO single-page preparation and re-audit;
3. ROUTE_METERS;
4. ALL_ISOLATED;
5. SILENT baseline;
6. real Playback reference signal;
7. exact-restored mix/output meter routing campaign.

After the campaign, inspect both sanitized local reports and update docs/CURRENT_HANDOFF.md with the measured meter coverage and exact restoration result. Any unconfirmed restore blocks all subsequent hardware work until reviewed.

[Rzbck]

Hardware attempt checkpoint (2026-08-24): the first meter-routing run stopped before any hardware write after successful model/auth/inventory/output-availability preflight because the current V8 capability-lab harness was not present exactly on Companion Page 2. The preflight had already classified 1436/1436 inventory rows, mapped snapshot/core/feedback coverage, and reported 22 AVAILABLE / 4 UNKNOWN outputs; no routing/mix action was pressed.

The branch now adds a dedicated read-only MeterRoutingPrepare.js bootstrap and updates the Windows launcher so Page 2 preparation happens before ROUTE_METERS / ALL_ISOLATED. If the V8 harness is missing, the launcher offers an explicit PAGE2_AUTO step using the existing audited Companion single-page importer, then performs a mandatory read-only re-audit before hardware permission is requested. Refusing PAGE2_AUTO or any import/re-audit failure exits before hardware writes. The launcher also stays open for result/error capture.

Two bootstrap regression tests were added; expected current-HEAD local gate is now 175 tests. The previous 173/173 gate belongs to the prior hardware-test head and must not be reused as validation for the new bootstrap commits.

[Rzbck]

Hardware checkpoint 2026-08-24 — first meter-routing exact-restore run completed without restore failure.

Observed on exact previously audited/live-tested 0.1.16 Companion package:

• read-only prep PASS; current V8 Page 2 generated/imported/audited with existing connection preserved;
• exact model/auth/shape/evidence coverage PASS (1436/1436, snapshot 1340/1340, core 21/21, 829/31 feedback matrix);
• output availability AVAILABLE=22 / UNKNOWN=4;
• existing Playback source detected on mixer slot 3 (Playback 1, stereo);
• meter baseline then routed campaign completed with zero feedback/oracle mismatch;
• final meter closure 14/46: inputs 8/8 closed, outputs 4/26 closed, mixes 2/12 closed;
• remaining outputs 3–24 floor-only; mixes include floor-only/movement-only/never-observed residuals;
• hardwareRestored=true;
• Page2 base restored=true;
• no hard abort.

The run also exposed two TestBench inefficiencies that must be fixed before another hardware pass:

1. lane eligibility currently requires every existing gain/mute/solo value across all 24 strips to be known, so all 12 lanes were SKIP_BASELINE_UNKNOWN even though the real Playback source is known on slot 3. Next meter drive should be per-selected-Playback-strip with exact per-strip restore, not whole-lane baseline gating.
2. the meter campaign retried Pair Source=None on pairs whose V8 evidence already proves the right member remains on its original source. Those failed guards restored exactly, but repeating them is unnecessary. The next pass should honor profile.evidence.output.pairOwnedSourceRight and not retry impossible both-member None guards.

Do not interpret 0.1.16 pair-action blocking as a production regression yet: canonical V8 pair topology for many pairs is REQUESTED_ORIGINAL / ZERO_ORIGINAL, not true two-member stereo routing. Production changes remain out of this TestBench PR until a separate action-policy audit proves they are warranted.

No rerun is requested until the two TestBench issues above are software-gated.