Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

Expose the browser suite gate's block reason for callers that only report

[._.]/ Adam Eivy8b99b3d3b477
diff --git a/server/lib/README.md b/server/lib/README.md
index 29e5540792..2da096b270 100644
--- a/server/lib/README.md
+++ b/server/lib/README.md
@@ -776,7 +776,7 @@ The barrel `server/lib/index.js` is a machine-checkable enumeration of every pub
| Module | Purpose |
|---|---|
-| `browserSuiteGate.js` | `probeChromeH264(path)` runs the H.264 probe as an owned, deadline-bound child (own process group, SIGTERM→SIGKILL ladder awaiting `close`) and resolves `{ ok }` or `{ ok:false, cause }` — `missing-executable`, `codec-unavailable`, `probe-timeout`, `teardown-failed` (answered, then exited nonzero: never trusted, never a missing codec), `no-answer`; `describeH264Probe` is its path/PID-free one-liner; `chromeWithH264(path)` (async) returns the path only when that Chrome decodes H.264, null when the executable or codec is genuinely absent, and `{ probeFailure }` when the probe itself failed (reported by `browserSuiteCanRun` as a lifecycle failure, not a missing prerequisite); `browserSuiteCanRun(label, prerequisites)` is the `canRun` guard for the cross-workspace `*.browser.test.js` suites (Chrome + ffmpeg + the client bundler). Pass `{ name: discoveredValue }`; a falsy value is missing. Returns `false` with a visible skip log locally, but throws naming the missing prerequisites when `PORTOS_REQUIRE_BROWSER_SUITES` is set — the flag the CI `database` job sets for the browser suites the planner selected (#10312). |
+| `browserSuiteGate.js` | `probeChromeH264(path)` runs the H.264 probe as an owned, deadline-bound child (own process group, SIGTERM→SIGKILL ladder awaiting `close`) and resolves `{ ok }` or `{ ok:false, cause }` — `missing-executable`, `codec-unavailable`, `probe-timeout`, `teardown-failed` (answered, then exited nonzero: never trusted, never a missing codec), `no-answer`; `describeH264Probe` is its path/PID-free one-liner; `chromeWithH264(path)` (async) returns the path only when that Chrome decodes H.264, null when the executable or codec is genuinely absent, and `{ probeFailure }` when the probe itself failed (reported by `browserSuiteCanRun` as a lifecycle failure, not a missing prerequisite); `browserSuiteCanRun(label, prerequisites)` is the `canRun` guard for the cross-workspace `*.browser.test.js` suites (Chrome + ffmpeg + the client bundler). Pass `{ name: discoveredValue }`; a falsy value is missing. Returns `false` with a visible skip log locally, but throws naming the missing prerequisites when `PORTOS_REQUIRE_BROWSER_SUITES` is set; `browserSuiteBlockReason(prerequisites)` is that verdict alone (the same wording, or `null`) for a caller that only reports, such as `scripts/pregate.js` — the flag the CI `database` job sets for the browser suites the planner selected (#10312). |
| `dbTestGate.js` | `requireDbOrSkip(label, dbReady, reason)` keeps a missing local test database as a visible skipped suite, but throws when `PORTOS_REQUIRE_DB` is set so CI cannot pass after DB-backed suites disappear. |
| `gitTestRepo.js` | Shared real-git sandbox for integration tests (#4394): one initialized template (working tree + bare origin) per worker, then `fs.cp` into a fresh temp dir. `makeGitSandbox({ origin })`, `attachBareOrigin(scratch, repo)`, `materializeGitRepo(dest)`, `destroyGitSandbox`, plus `SKIP_HEAVY_INTEGRATION` (`VITEST_FAST=1`). `resetGitSandbox({ scratch, repo, initialHead })` / `resetGitWorktreeSandbox(repo, initialHead)` restore a sandbox in place (branches, worktrees, remote) so a `describe` can build one sandbox in `beforeAll` and reset between tests instead of paying the fs.cp/rm cycle per test (#5902). Every entry point runs `assertTempPath` first, so a path outside `os.tmpdir()` throws instead of `git init`-ing or `rm -rf`-ing a real checkout (#4554). Fixture-local maintenance/GC detachment is disabled so awaited Git operations retain their writers through teardown. Still real git — just not rebuilt from `init`+`commit`+`push` in every `beforeEach`. |
| `mirrorParity.js` | Source-extraction and comparison primitives for declaration-level contract tests: the vendored `aiToolkit/` copy of `TOOL_USE_RE` (`localModelHeuristics.mirror.test.js`), and the bootstrap sequence's body assertions (`bootstrap*.test.js`). A pure module the browser needs is imported by the client rather than mirrored, so no client↔server copy test should need these: `stripCommentsAndNormalize` (so per-side commentary may diverge but logic may not), `extractDeclaration(src, name)` (balanced `{}`/`()`/`[]` walk over `function` / `async function` / `const`), and `compareDeclaration(serverSrc, clientSrc, name)`. Use these instead of hand-rolling a brace-walker per mirror. Pure — no `vitest` import — so callers own the assertions. |
diff --git a/server/lib/browserSuiteGate.js b/server/lib/browserSuiteGate.js
index 445a66e112..308971af45 100644
--- a/server/lib/browserSuiteGate.js
+++ b/server/lib/browserSuiteGate.js
@@ -13,19 +13,28 @@ import { join } from 'node:path';
* also report `{ probeFailure }` for a probe that ran and failed). `onUnavailable` runs
* before the skip or the throw: prerequisite discovery can initialize mocked
* path fixtures, and Vitest runs no cleanup hooks for a skipped (or failed) file.
+ *
+ * `browserSuiteBlockReason` is the verdict alone (null when every prerequisite
+ * is present), so a caller that only reports — the local pregate — can share
+ * the exact wording the suites print without the skip/throw side effects.
*/
-export function browserSuiteCanRun(label, prerequisites, { onUnavailable } = {}) {
+export function browserSuiteBlockReason(prerequisites) {
const entries = Object.entries(prerequisites);
// A probe that ran but failed is a distinct verdict from an absent prerequisite.
const failed = entries.filter(([, found]) => found?.probeFailure);
const missing = entries.filter(([, found]) => !found).map(([name]) => name);
- if (missing.length === 0 && failed.length === 0) return true;
-
- onUnavailable?.();
- const reason = [
+ if (missing.length === 0 && failed.length === 0) return null;
+ return [
...(missing.length ? [`missing ${missing.join(', ')}`] : []),
...failed.map(([name, found]) => `${name} probe failed (${found.probeFailure})`),
].join('; ');
+}
+
+export function browserSuiteCanRun(label, prerequisites, { onUnavailable } = {}) {
+ const reason = browserSuiteBlockReason(prerequisites);
+ if (reason === null) return true;
+
+ onUnavailable?.();
if (process.env.PORTOS_REQUIRE_BROWSER_SUITES) {
throw new Error(`${label}: browser suite skipped but PORTOS_REQUIRE_BROWSER_SUITES is set — ${reason}`);
}