test: add the local install-matrix harness (scenario runner, runas contract, JSON results) #2559

Goal

Provide a runner that executes a scenario as each of the four local matrix accounts and emits machine-readable results.

Background

The dev Mac has four non-admin accounts for the 2x2 matrix of shell (Bash, Zsh) and install route (Homebrew, source checkout): base-source-bash, base-source-zsh, base-brew-bash, and base-brew-zsh. The macOS validation checklist is the spec, but its Automation Boundary table assigns real Homebrew install, profile update, and activation to manual runs.

Findings on 2026-10-14: all four accounts have /bin/zsh as login shell; /etc/shells lists only the Intel path /usr/local/bin/bash, so Homebrew Bash 5 at /opt/homebrew/bin/bash is not a registered login shell; there is no passwordless runas to the accounts. An admin setup script (sudoers drop-in scoped to those four runas users, /etc/shells entry, login-shell change for the two Bash accounts) was drafted and dry-run on 2026-10-15 and should land in the repo with this issue.

Caution from #2519: Python placed under tools/ is outside the coverage ratchet; keep new Python under measured source or extend .coveragerc.

Next-release planning review of 2026-10-14/15 against main at 7faf6dfb. Tracking: #2555.

Scope

• Land the admin setup script with --dry-run and --remove, plus documentation of the one-time admin steps and their blast radius.
• Runner that executes a scenario file as a named matrix user through sudo -n -u <user> -i, refusing any user outside the matrix list.
• Scenario contract: name, cell, preconditions, ordered steps, expected exit code and output assertions.
• Result schema (JSON): run ID, cell, Base ref, route, shell, macOS version and architecture, per-step command, exit code, duration, finding IDs, log path; plus a human summary.
• Redact secrets from captured output using Base's existing redaction.

Acceptance Criteria

• A trivial scenario runs in all four cells and its results validate against the schema.
• The runner refuses a non-matrix user and a non-interactive context without the runas rule.
• The admin script is idempotent; --remove restores login shells and removes the drop-in and the /etc/shells entry it added.
• The runner has BATS coverage against a stubbed runas (no real sudo in CI).

Validation

bats <new runner BATS file>
shellcheck <changed shell files>
python -m pytest <new schema test>
env -u BASE_HOME ./bin/base-test
git diff --check

Non-Goals

• No clean-install scenarios here (separate issues).
• The matrix does not run in hosted CI; accounts are local.
• No VM tooling.

Project Fields

• Status: Ready
• Priority: P1
• Area: CI
• Initiative: Contract Hardening
• Size: M
• Milestone: v1.11.0
• Category: ci

Agent Assignment

Assignee: codeforester. Implementation-ready; use an issue-backed worktree. Applying the admin script needs the maintainer's sudo and cannot be done by an agent.