pi-ui-extend 1.0.40 → 1.0.42

package/external/pi-tools-suite/docs/context-gateway-p01r-rg-evidence.md

@@ -0,0 +1,235 @@
+# Context Gateway P01-R / R-G storeless release evidence
+
+<!-- markdownlint-disable MD013 -->
+
+> Scope frozen before the R-G measurement gate on 7 September 2026.
+> Repository HEAD: `daa1b06`; tested source tree is dirty and earlier live run identities must not be inferred from HEAD alone.
+> This document does not authorise Context Gateway enforce mode or P02 durable storage.
+
+## Scope fixed before measurement
+
+The candidate storeless release is deliberately small:
+
+| Surface | Decision for R-G | Runtime effect |
+| --- | --- | --- |
+| Context Gateway observe | Keep available, `off` by default | Aggregate measurement/classification only; no result replacement or archive. |
+| `repo_*` Native Compact | Accept as explicit opt-in profile | Existing bounded native flags/cursors/validation; no store. |
+| `truncation-metadata-normalizer` | Accept as separate explicit opt-in module | Removes only proven duplicate truncation metadata for measured Read/shell/ast_grep shapes. |
+| test/build parser | Keep observe-only | Safe classification/metrics only; no result replacement. |
+| mutation/LSP | Native passthrough | Existing outcome/diagnostics behavior only. |
+| web/document | Native passthrough / limited | No second fetch, no archive. |
+| structured JSON | Native passthrough / limited | No generic parse/rewrite. |
+| subagent result | Native passthrough / producer-managed lifetime | No parent grant or lifetime extension. |
+| images | Native passthrough | No text replacement. |
+| direct browser / MCP | Unsupported | Not in the claimed denominator. |
+
+Provider-specific equality claims are limited to the installed OpenAI-completions
+serialization path already exercised by the deterministic harness. UI claims are
+limited to the current TUI result renderers and the existing ACP/Desktop lazy
+persisted-result flow. Native temp-output contents do not get a new UI/ACP reader.
+
+## Metrics and release criteria fixed before measurement
+
+R-G evaluates the following dimensions independently:
+
+- task/fact correctness and execution outcome;
+- initial delivered result bytes and all continuation/recovery calls;
+- JSONL/details bytes for metadata-only cleanup;
+- actual checked provider payload equality/usage rather than converting metadata
+  bytes into token estimates;
+- tool-call/refusal/retry counts and elapsed time for model-driven evidence that
+  already exists;
+- parser/capability CPU work through explicit scan/output bounds rather than a
+  claim based on one timing sample;
+- native temp/current-file/index lifetime limitations and unavailable recovery;
+- unsupported paths and failures remain in the report rather than being removed
+  from the denominator.
+
+There is no aggregate batch-budget claim. P00 proved stable per-call identity and
+source-order delivery, but not a host API that supplies a durable whole-batch
+budget before execution. Batch cost is therefore the sum of actual per-result
+traffic/calls in measurements.
+
+## Measurement results
+
+The measurements below were run after the scope and criteria above were written.
+
+### Native Compact deterministic paired corpus
+
+`PI_CONTEXT_GATEWAY_BENCHMARK_REPORT=1 bun test test/context-gateway/benchmark.test.ts`
+compares the historical baseline behavior with the current Native Compact profile
+over search, structure, AST, explain and dependency scenarios. All eight critical
+facts are recovered in both arms.
+
+| Metric | Baseline | Native Compact | Delta |
+| --- | ---: | ---: | ---: |
+| Delivered repo bytes including continuations | 71,025 | 27,519 | **-61.25%** |
+| Tool calls | 6 | 8 | +2 |
+| Continuation calls | 1 | 3 | +2 |
+| Refusals | 0 | 0 | 0 |
+| Full overrides | 0 | 0 | 0 |
+| Critical facts | 8/8 | 8/8 | equal |
+
+This is the expected trade-off for narrow native paging: substantially fewer
+delivered bytes, but potentially more calls. It is not evidence of lower total
+model cost by itself.
+
+### Historical model-driven paired evidence
+
+The retained `zai/glm-5.3` paired report
+`test/evals/artifacts/p01n-2026-09-07T17-30-21-479Z/p01n-paired-report.json`
+contains three Prompt Compact / Native Compact pairs; all **6 arm-runs passed**.
+It predates R-A v2 source/corpus identity, so R-G uses it only as historical
+model-behavior/cost evidence rather than pretending it certifies the current dirty
+tree byte-for-byte.
+
+| Aggregate metric | Prompt Compact | Native Compact | Delta |
+| --- | ---: | ---: | ---: |
+| Repo-result bytes | 1,286 | 983 | **-23.6%** |
+| All tool-result bytes | 9,737 | 9,149 | **-6.0%** |
+| Tool calls | 14 | 12 | **-14.3%** |
+| Parent tokens | 179,855 | 207,611 | **+15.4%** |
+| Parent cost | $0.0682 | $0.0923 | **+35.4%** |
+| Elapsed | 88.682s | 96.219s | **+8.5%** |
+| Native refusals / full overrides / refusal retries | 0 / 0 / 0 | 0 / 0 / 0 | equal |
+
+The live evidence therefore argues **against** making Native Compact the default:
+repo traffic improved, but total token/cost/latency did not consistently improve.
+It remains a useful explicit opt-in for workloads where repo-result volume is the
+binding constraint.
+
+### Metadata normalizer
+
+The normalizer changes only `details.truncation.content` on proven Read/shell/
+`ast_grep` SDK shapes. A deterministic 24,007-byte duplicate fixture measured:
+
+| Metric | Raw | Normalized | Delta |
+| --- | ---: | ---: | ---: |
+| Serialized tool-result JSON | 48,396 B | 24,376 B | **-24,020 B (-49.6%)** |
+| Ten identical persisted results | — | — | **240,200 B avoided** |
+
+The actual SDK fixtures in R-B also remove more than 40 KiB of duplicated metadata
+from large Read/Bash results while preserving visible content and structural
+truncation fields.
+
+This is deliberately reported as JSONL/metadata savings only. The installed
+OpenAI-completions serialization contract is byte-equivalent before/after cleanup
+because tool-result `details` are not serialized to that provider payload. R-G
+therefore claims **no token, cache or model-quality saving** from the normalizer.
+
+An additional 52,000-byte duplicate sample, matching the approximate size of the
+live observe residual details, measured `104,408 → 52,395 B` for the serialized
+tool-result object and `52,279 → 266 B` for `details`: **52,013 B** removed while
+visible content remained `52,035 B`. Seven reference-machine rounds of 10,000
+normalizer calls on that sample measured approximately `3.5–4.3 µs/call`. These
+timings are diagnostics, not a portable release threshold.
+
+### Residual and negative corpus
+
+The live observe-only residual run shows the measured large classes remain real:
+Read/Bash/ast_grep each delivered roughly 52 KiB of result content and roughly
+another 52 KiB of details at the checked boundary. The Bash task assertion failed
+because the model made an extra call; the large Bash observation itself remained
+valid. That failure stays visible rather than being removed from the denominator.
+
+R-A–R-F deterministic contracts cover the rest of the offline release corpus:
+
+- small/exact/control results and current-file Read continuation;
+- Unicode/CRLF/long-line and changed file/index behavior;
+- successful Bash/ast_grep native recovery plus missing/replaced temp output;
+- timeout/abort/nonzero and unavailable structured recovery handles;
+- parser middle failures, PASS→exit-1 conflict, ANSI/CR, mixed/compound commands,
+  unknown formats and a bounded 1 Mi-character parser scan;
+- mutation/LSP outcomes, web errors/cancellation, opaque large-integer JSON,
+  subagent producer-managed artifacts, image passthrough and unsupported browser/MCP;
+- late/reloaded/session-switched results, parallel calls and UI/history replay.
+
+The test/build parser is bounded but remains observe-only. Its prospective compact
+candidate is all-or-passthrough and must fit the configured result budget; no
+runtime result delivery, provider traffic, calls or token usage are changed by it.
+On a 4,550,063-character synthetic input the 1 Mi-character scan bound produced
+`scan-limited / partial`; seven rounds of 100 parses measured about
+`16.2–16.9 ms/call` on the reference machine. This is CPU/telemetry evidence only,
+not a shaping or provider-saving claim.
+
+## Live-run decision
+
+R-G does **not** request another live model run for the selected release scope:
+
+- the metadata normalizer is provider-invisible on the checked serializer and has
+  deterministic JSONL/provider equality contracts;
+- the test/build parser does not replace results;
+- mutation/LSP, web/JSON/subagent/image surfaces remain native passthrough;
+- Native Compact already has retained paired model-driven evidence, while all
+  post-run changes relevant to this scope are deterministic policy/validation
+  hardening rather than a new model-visible adapter.
+
+The R-A v2 recovery runner remains available for a future claim that specifically
+depends on exact model-driven native-handle recovery. Such a run still requires
+separate authorization and must create a new v2-identity report. R-G does not
+reinterpret the old v1 recovery reports as v2 passes.
+
+## Release decision
+
+Accept the verified storeless scope with conservative defaults:
+
+1. **Context Gateway stays `off` by default.** Observe remains an explicit passive
+   measurement mode; `enforce` remains unavailable.
+2. **Native Compact is accepted only as explicit opt-in.** Default
+   `repoDiscovery.profile` remains `baseline` because live total-cost evidence is
+   mixed despite lower repo-result traffic.
+3. **`truncation-metadata-normalizer` is accepted as a separate explicit opt-in.**
+   It remains disabled by default and claims JSONL/metadata reduction, not token
+   savings.
+4. **Test/build parsing stays observe-only.** No production compact-result adapter
+   is enabled without a proven recovery/lifetime contract for omitted data.
+5. **Mutation/LSP, web/document, JSON, subagent and visual paths remain their R-E
+   passthrough/limited decisions.** Browser/MCP direct adapters remain unsupported.
+6. **P02 durable store remains deferred.** R-G found no task requiring new durable
+   snapshot identity strongly enough to justify store/readers/quotas now.
+
+Rollback is configuration-only for future calls: disable the normalizer module,
+return `repoDiscovery.profile` to `baseline`, and/or set Context Gateway mode to
+`off`. Rollback does not delete session history, native temp files, user data or
+DCP state and does not require a manual sync operation.
+
+## Deterministic R-G gate
+
+The final gate reuses the independently proven R-A–R-F contracts rather than one
+monolithic test process where unrelated LSP/AgentSession suites can interfere with
+shared process/temp state. The required groups are:
+
+- Context Gateway/storeless contracts, Native Compact, recovery validator/corpus,
+  eval harness and coverage registry;
+- ACP lazy history/replay and typecheck;
+- root tab ownership/session UI contracts;
+- suite/root `git diff --check` and source typechecks.
+
+No new live model call, manual suite sync, durable store, reader tool or DCP change
+is part of the R-G release gate.
+
+The final external-suite P01-R gate is:
+
+```text
+bun test \
+  test/context-gateway \
+  test/repo-native-compact.test.ts \
+  test/repo-discovery.test.ts \
+  test/config.test.ts \
+  test/evals/extension-contracts.test.ts \
+  test/evals/harness.test.ts \
+  test/evals/recovery-corpus.test.ts \
+  test/evals/recovery-run-identity.test.ts \
+  test/evals/recovery-report.test.ts \
+  test/evals/recovery-validation.test.ts
+```
+
+Result: **144 pass, 0 fail, 1011 assertions**; suite typecheck and
+`git diff --check` pass. Root SDK pin remains `0.85.1`; generated schemas are
+unchanged when checked through `node --import tsx` (the sandbox blocks the normal
+`tsx` CLI IPC socket), and root `tsc --noEmit` passes.
+
+R-F's separate host/UI gates remain green: root TUI/session **98/98**, ACP lazy
+current-result **4/4** plus an additional **6/6** persisted-history/request-boundary
+suite and typecheck, and Desktop transcript/client **28/28** with Desktop check at
+zero errors (two pre-existing accessibility warnings).

package/external/pi-tools-suite/docs/evals.md

@@ -137,7 +137,7 @@ The current extension registry covers all 19 modules:
 | `web-search` | web-search tests | deterministic only |
 | `dcp` | DCP prompt/pruning/state tests | existing prompt evals |
 | `prompt-commands` | eval extension contracts | deterministic only |
-| `skill-installer` | eval extension contracts | deterministic only |
+| `resource-registry` | resource-registry integration + eval extension contracts | deterministic only |
 | `credential-firewall` | firewall tests | deterministic only |
 | `codex-reasoning-fix` | reasoning-fix tests | deterministic only |
 

package/external/pi-tools-suite/docs/session-recovery.md

@@ -2,6 +2,14 @@
 
 Status: implemented MVP contract (semantic search is intentionally deferred).
 
+## Type
+
+As-is
+
+## Lifecycle
+
+Active implemented contract.
+
 ## Goal
 
 Let an agent recover the task, recent instructions, file activity, and useful raw
@@ -28,19 +36,29 @@ active model context by compaction remains discoverable.
 
 A section starts at the first selected entry, a user message, a compaction, or a
 branch summary. Its stable ID is derived from the start entry ID. The overview
-reports bounded head and tail sections with entry ranges, counts, and compact
-role/tool/error/file statistics. Labels are previews, not inferred decisions.
+reports bounded section pages with entry ranges, counts, and compact
+role/tool/error/file statistics. When more sections exist it returns an opaque
+`nextCursor`; continuing with that cursor resumes after the last delivered
+section. Labels are previews, not inferred decisions.
 
 ### Reading and search
 
-`session_read_section` requires a section ID produced for the same scope. It
-renders message roles and text, tool calls and arguments, tool results,
+`session_read_section` accepts either a section ID produced for the same scope or
+one exact raw `entry_id`. Direct entry reads avoid scanning from the start of a
+section and are useful when overview/search already identified the exact entry.
+Without a continuation cursor, callers must pass exactly one of `section_id` or
+`entry_id`.
+
+The reader renders message roles/text, tool calls/arguments, tool results,
 compaction summaries, and branch summaries with per-entry and total output
-limits.
+limits. Long entry bodies and multi-entry pages return an opaque `nextCursor`;
+passing that cursor continues at the exact entry/body offset and must use the
+same scope.
 
 `session_search` is case-insensitive by default and searches message text, tool
 arguments/results, custom-message content, and compaction or branch summaries.
-It returns entry and section IDs plus bounded snippets. Regex and semantic
+It returns entry and section IDs plus bounded snippets. Search pages use an
+opaque cursor bound to scope, query, and case-sensitivity. Regex and semantic
 search are out of scope for the MVP.
 
 ### Recovery context
@@ -60,6 +78,8 @@ tools are not guessed to be mutations.
 
 - Results use small defaults and hard caps for result count, entry body size,
   and total text size.
+- Overview, read, and search pagination use opaque validated cursors; a cursor
+  from another scope/query or a stale section is rejected rather than guessed.
 - Empty or in-memory sessions return a normal explanatory result.
 - Unknown or partially shaped entries are ignored or rendered conservatively.
 - Concurrent sibling tool results might not yet be visible when recovery runs.
@@ -68,17 +88,23 @@ tools are not guessed to be mutations.
 - Parent-session metadata is reported when Pi exposes it; parent files are not
   traversed.
 
+## Related files
+
+- `external/pi-tools-suite/src/session-recovery/index.ts`
+- `external/pi-tools-suite/src/tool-descriptions.ts`
+- `external/pi-tools-suite/test/session-recovery.test.ts`
+
 ## Verification
 
 Deterministic tests cover active versus all branches, raw pre-compaction search,
-stable section IDs, Unicode case-insensitive search, bounded output, empty
-sessions, current-call exclusion, recent errors, file carry-forward details,
-and conservative handling of unknown entries. Release verification runs the
-suite typecheck/tests/smoke gate, host `npm run check`, and then syncs the suite
-with `npm run sync:pi-tools-suite`.
+stable section IDs, overview/search pagination, direct late-entry reads,
+continued long bodies, Unicode case-insensitive search, bounded output, empty
+sessions, DCP-control filtering, current-call exclusion, recent errors, file
+carry-forward details, and conservative handling of unknown entries. Release
+verification runs the suite typecheck/tests/smoke gate and host checks.
 
 ## Evidence
 
-Evidence is recorded by the implementation tests in
-`test/session-recovery.test.ts` and the verification commands reported with the
-change.
+Evidence is recorded by
+`external/pi-tools-suite/test/session-recovery.test.ts` and the implementation
+in `external/pi-tools-suite/src/session-recovery/index.ts`.

package/external/pi-tools-suite/docs/subagent-model-pools.md

@@ -0,0 +1,120 @@
+# Sub-agent model pools
+
+Sub-agents primarily reduce the cost of bounded work and keep intermediate
+source, searches and logs out of the parent context. The parent owns planning,
+integration, decisions and the final answer. Actual savings depend on worker
+quality, retries and how much work the parent repeats; the configuration is
+not a price oracle.
+
+## Six execution modes
+
+- `research`: read-only evidence gathering, searches and focused review questions.
+- `implement`: bounded code, documentation, test and frontend changes.
+- `verify`: run checks and interpret logs, without fixing source or tests.
+- `browser-qa`: isolated browser workflow with assertions and visual artifacts.
+- `frontier-review`: independent post-implementation code review on a strong
+  model; hidden when the current parent model matches the role's availability
+  gate.
+- `oracle`: a deliberate strong second opinion, not automatic worker escalation.
+
+Task-specific discipline belongs in the brief or `promptAppend`. A new project
+agent is warranted when it adds a durable contract, capabilities or resources,
+not merely a professional title. `verify` has a behavioral no-edit contract;
+shell access is not a read-only filesystem sandbox.
+
+## Agent priority, preset availability
+
+Each Markdown profile owns its ordered `models` list. This is one candidate
+chain for initial selection and subsequent quota fallbacks:
+
+```yaml
+---
+description: Make bounded implementation changes.
+models:
+  - zai/glm-5.3-flash
+  - openai-codex/gpt-5.6-terra
+  - openai-codex/gpt-5.6-luna
+thinking: medium
+---
+```
+
+A preset contains a set of available models, not a per-agent matrix. Project
+pools live in `.pi/agents/presets.jsonc`:
+
+```jsonc
+{
+  "gpt": {
+    "description": "Models available for this project",
+    "models": [
+      "openai-codex/gpt-5.6-luna",
+      "openai-codex/gpt-5.6-terra",
+      "openai-codex/gpt-5.6-sol"
+    ]
+  }
+}
+```
+
+The example agent selects Terra, not Luna: the agent's order wins. Sol is
+available in the pool but absent from this worker's chain, so it cannot become
+an automatic implementation fallback. The oracle and frontier-review can
+declare Sol in their own chains. Model references in `models` must be exact
+`provider/model` values, not wildcards.
+
+The resolver intersects the agent chain with the selected pool. Runtime
+selection then skips unregistered, unauthenticated or session-exhausted models.
+Tasks with images and browser QA require confirmed image support. The first
+eligible candidate runs; only the remaining eligible candidates are passed to
+quota fallback. An empty intersection or unavailable chain rejects the batch
+before any children or run state are created. Model selection makes no LLM
+completion request; the optional role router is a separate operation.
+
+Oracle prefers another provider when possible, but still respects the pool.
+It never substitutes an ordinary cheap candidate merely to avoid a selection
+error. A single-provider pool cannot promise cross-provider independence.
+
+Explicit task `model`, CLI `--model`, and `FORCE_CURRENT_MODEL` remain deliberate
+overrides: they bypass the pool and do not add automatic fallback candidates.
+The parent should not use these to evade the configured budget. The pool is
+a selection policy, not a security boundary against explicit overrides.
+
+## Selection and compatibility
+
+Use `/subagent-preset <name>`, `AGENTS_PRESET=<name>` or
+`/subagent-preset session <name>`. Clearing the preset uses agent priorities
+without a pool filter. The shipped names remain compatible with saved choices:
+`cheap` is the GLM pool, `gpt` the GPT pool, and `deep` the mixed pool. The last
+name no longer means that ordinary workers should escalate to flagship models.
+Bundled definitions live beside the built-in agents in
+`src/async-subagents/agents/presets.jsonc`; a project file with the same preset
+name overrides that pool.
+
+Old role names are not implicit aliases. `quick`, `scan`, `review`, `deep`,
+`docs`, `frontend`, and `tests` work only when explicitly defined as ordinary
+custom/project types. This keeps the effective catalog and accepted names exact.
+
+Agent frontmatter can gate whether a role exists for the current parent model:
+`forParentModels` is an optional allow-list and `notForParentModels` is an
+optional deny-list; deny wins when both match. These fields accept model
+patterns such as `zai/*` and affect the parent catalog, explicit role
+validation, and automatic routing. They do not change which model the child
+runs on; `models` / legacy model selectors still own child model selection.
+
+Legacy `model` plus `fallbackModels` and `modelByParent` still load when they are
+declared in an agent Markdown file. New profile `models` replaces inherited
+legacy selection fields. Empty `models` means no candidates, not permission to
+inherit the parent model. Model-less project specialists must declare candidates
+or receive an explicit model override.
+
+The removed `asyncSubagents` section is no longer part of the public config
+schema and is not read at runtime. Existing legacy files are left untouched but
+have no effect. Migrate role definitions to `.pi/agents/*.md` and custom pools to
+`.pi/agents/presets.jsonc`.
+
+## Compact handoff
+
+Give workers a scope, acceptance criteria and the evidence needed to start.
+Read compact results first and inspect raw artifacts selectively. One noisy
+sequential investigation can justify a worker; a command whose exit status is
+sufficient usually only needs a saved log, not another LLM. Independent review
+of substantive code changes uses `frontier-review` when it is present in the
+current parent catalog; use `research` for focused evidence/review questions.

package/external/pi-tools-suite/package.json

@@ -33,6 +33,9 @@
     "test:evals:live": "PI_TOOLS_SUITE_EVALS_LIVE=1 bun test --concurrent --max-concurrency=4 test/evals/live-evals.test.ts",
     "evals": "npm run test:evals:contracts && bun test test/evals/live-evals.test.ts",
     "evals:report": "bun test/evals/run-evals.ts",
+    "evals:p01n": "bun test/evals/run-p01n-paired.ts",
+    "evals:context-gateway-observe": "bun test/evals/run-context-gateway-observe.ts",
+    "evals:context-gateway-recovery": "bun test/evals/run-context-gateway-recovery.ts",
     "bench:locate": "PI_LOCATE_BENCH_ITERATIONS=5 PI_LOCATE_BENCH_FAKE_IDX=0 PI_LOCATE_BENCH_MODEL=zai/glm-5-turbo PI_LOCATE_BENCH_MODES=direct-read-grep,ast-structural,repo-search-hybrid,repo-discovery,subagent-search,unrestricted-suite node test/fixtures/hard-to-find-project/benchmark/run-locate-benchmark.mjs",
     "bench:locate:analyze": "node test/fixtures/hard-to-find-project/benchmark/analyze-locate-benchmark.mjs",
     "test:locate-benchmark-e2e": "PI_LOCATE_BENCH_E2E=1 PI_LOCATE_BENCH_MODEL=zai/glm-5-turbo bun test test/locate-benchmark-e2e.test.ts",

package/external/pi-tools-suite/src/async-subagents/{private-skills → agents}/browser-qa/scripts/browser-qa-runner.mjs

@@ -2206,12 +2206,60 @@ foreach ($candidatePid in $descendants) {
 		});
 		return;
 	}
+
+	// Prefer parent-based enumeration when available. macOS sandboxed hosts can
+	// deny `ps` while still allowing pgrep(1); relying only on `ps` leaves a
+	// detached Playwright/browser process alive after a timeout. Collect the
+	// whole tree before killing anything so descendants cannot be re-parented
+	// out of reach, then terminate deepest-first. A detached child is normally a
+	// process-group leader, so also try its negative PID before the individual
+	// PID; non-group-leaders simply yield ESRCH and fall through safely.
+	const pgrepDescendants = [];
+	const pgrepPendingParents = [process.pid];
+	let pgrepAvailable = true;
+	for (let index = 0; index < pgrepPendingParents.length; index += 1) {
+		const parentPid = pgrepPendingParents[index];
+		const result = spawnSync("pgrep", ["-P", String(parentPid)], {
+			encoding: "utf8",
+			timeout: 1000,
+			maxBuffer: 256 * 1024,
+		});
+		if (result.error?.code === "ENOENT") {
+			pgrepAvailable = false;
+			break;
+		}
+		if (result.status !== 0 && result.status !== 1) {
+			pgrepAvailable = false;
+			break;
+		}
+		for (const line of (result.stdout ?? "").split("\n")) {
+			const pid = Number(line.trim());
+			if (!Number.isInteger(pid) || pid <= 0 || pgrepDescendants.includes(pid)) continue;
+			pgrepDescendants.push(pid);
+			pgrepPendingParents.push(pid);
+		}
+	}
+	if (pgrepAvailable) {
+		for (const pid of [...pgrepDescendants].reverse()) {
+			try { process.kill(-pid, "SIGKILL"); } catch { /* not a group leader or already gone */ }
+			try { process.kill(pid, "SIGKILL"); } catch { /* already gone */ }
+		}
+		return;
+	}
+
 	const snapshot = spawnSync("ps", ["-axo", "pid=,ppid=,pgid="], {
 		encoding: "utf8",
 		timeout: 1000,
 		maxBuffer: 2 * 1024 * 1024,
 	});
-	if (snapshot.status !== 0 || !snapshot.stdout) return;
+	if (snapshot.status !== 0 || !snapshot.stdout) {
+		// Sandboxed macOS hosts can deny `ps` process enumeration while still
+		// allowing parent-scoped `pgrep -P`. Fall back to a bounded recursive
+		// parent walk so a detached browser process is not left behind merely
+		// because the broader process snapshot is unavailable.
+		terminateRunnerDescendantsWithPgrep(process.pid);
+		return;
+	}
 	const processes = snapshot.stdout
 		.split("\n")
 		.map((line) => line.trim().split(/\s+/).map(Number))
@@ -2241,6 +2289,39 @@ foreach ($candidatePid in $descendants) {
 	}
 }
 
+function terminateRunnerDescendantsWithPgrep(rootPid) {
+	const descendants = [];
+	const seen = new Set([rootPid]);
+	const pendingParents = [rootPid];
+	for (let index = 0; index < pendingParents.length && descendants.length < 4096; index += 1) {
+		const parentPid = pendingParents[index];
+		const result = spawnSync("pgrep", ["-P", String(parentPid)], {
+			encoding: "utf8",
+			timeout: 500,
+			maxBuffer: 256 * 1024,
+		});
+		// pgrep exits 1 when there are no matching children. Any other failure is
+		// fail-closed for this fallback; callers still terminate the runner itself.
+		if (result.status !== 0 && result.status !== 1) continue;
+		for (const line of (result.stdout ?? "").split("\n")) {
+			const pid = Number.parseInt(line.trim(), 10);
+			if (!Number.isInteger(pid) || pid <= 0 || seen.has(pid)) continue;
+			seen.add(pid);
+			descendants.push(pid);
+			pendingParents.push(pid);
+		}
+	}
+
+	// Kill leaves before their parents so descendants cannot be reparented
+	// before we have sent them a signal. Detached children are killed by PID;
+	// unlike the primary `ps` path this fallback does not need their PGID.
+	for (let index = descendants.length - 1; index >= 0; index -= 1) {
+		try {
+			process.kill(descendants[index], "SIGKILL");
+		} catch { /* already gone */ }
+	}
+}
+
 function sanitizeTraceArchiveInWorker(tracePath, secrets, deadline) {
 	return new Promise((resolve, reject) => {
 		const worker = new Worker(new URL(import.meta.url), {