Skip to content

test: add isolated branch stack browser harness - #431

Merged
monkey1sai merged 70 commits into
mainfrom
codex/openspec/isolated-branch-stack-browser-e2e
Jul 30, 2026
Merged

monkey1sai merged 70 commits into
mainfrom
codex/openspec/isolated-branch-stack-browser-e2e

Conversation

@monkey1sai

@monkey1sai monkey1sai commented Jul 29, 2026 •

Copy link
Copy Markdown
Owner

Summary

  • Adds the repo-owned fail-closed isolated A3/A4 browser stack for governance :49103, coordinator :8005, and viewer :5180.
  • Merges current origin/main 8f2ff8b4cb840f1258cc36690f8a13f5f9783a9d at merge commit cdd1f2f0449bc0cb61546bd836d7218256d5b0e1.
  • Starts children from a clean environment, preserves only the minimal OS execution allowlist, then applies the validated role payload; inherited mixed-case runtime and deployment variables are regression-tested as absent.
  • Derives the A3 fixture from the manifest-owned worktree storage/ root and requires realpath equality, regular files, and physical containment.
  • Recovers only identity-proven abandoned reclaim claims when the canonical lock is absent or different; same-ID, malformed, active, and identity-provider failures remain fail closed, with reread/recheck before unlink.
  • Keeps 4.3, 5.2, and 5.3 open: there is still no successful A4 manifest, PNG, runtime ID, or fresh real browser/runtime smoke. PR feat(a4): 隔離 stack 真實 MinIO IFC-ready seeding(a4-console-convergence Task 4.0) #434 owns fixture seeding/root availability.

Change ID: isolated-branch-stack-browser-e2e

AI Coding Governance

Item Result
Change lane S
Behavior contract changed yes
Linked issue no separate issue; merged PR #428 created this governed OpenSpec change
Requirement source superpowers spec and openspec/changes/isolated-branch-stack-browser-e2e/
CODEOWNERS / owner review final committed diff reviewer ACCEPT; P1=0, P2=0, with one nonblocking P3 gap for a dedicated different-canonical-lock-ID branch test; explicit user merge consent granted; branch protection remains authoritative
GitNexus evidence linked-worktree health/index was unavailable/UNKNOWN after the latest-main merge; impact and compare detect are not claimed as passing. Direct source/tests plus a fresh reviewer accepted the residual risk.
Browser E2E evidence prior require-real run p5-20260730-163713 failed closed 6/6 before navigation because no downloaded IFC-ready job existed; the new code subject was not followed by a real browser/runtime smoke and claims no success evidence
Agent workflow changed? yes; repository-owned isolated-stack contract; rollback is reverting this PR
Required checks expected current branch-protected CI, Agent Governance, PR Metadata Contract, CodeRabbit, and local preflight; Trusted Merge Evidence is retired
Evidence item Result
Baseline origin/main 8f2ff8b4cb840f1258cc36690f8a13f5f9783a9d
Latest PR head c1fdb6bfc9ff58b3821e5e168b278fc4e49e9b50
Review-convergence code subject 0170c8dfb58b011e87f3d84252bafd21d7045afd
Latest-main merge commit cdd1f2f0449bc0cb61546bd836d7218256d5b0e1
NOW evidence snapshot 72fcf5f85ee1460b42b5f57a0709634bbf816c02
Lifecycle ledger commit c1fdb6bfc9ff58b3821e5e168b278fc4e49e9b50 (subject_commit=72fcf5f…, current_slice=482, tasks 30/33)

Frontend Verification

Item Result
Frontend route #semantic-search; prior require-real navigation was held by the missing downloaded-job preflight
Main button(s) tested expected a4-refresh-sources and a4-run; not clicked because the prior real-fixture preflight failed before navigation
Fixture used manifest-derived, realpath-validated worktree storage/ with A3 e2e-a3/arch.usdc and str.usdc regular-file containment contract; no successful runtime fixture was available
Backend API called prior isolated coordinator :8005: GET /health, GET /api/governance/search/llm-status, and GET /api/external/ifc-ready?limit=100
Runtime action runtime ID=not_observed; no A4 search request was emitted because the downloaded-job preflight failed
Visible success state loading, success, failure, and retry UI states were not reached; failure occurred before route navigation
E2E command E2E_REQUIRE_REAL=1 with the manifest-owned Playwright A3/A4 projects; fresh real execution remains a known gap
Screenshot / trace ignored prior failure trace/video/error context under artifacts/e2e/isolated-branch-stack-browser-e2e/p5-20260730-163713/playwright-output/; no success screenshot PNG or trace is claimed
Design gate status mixed
Design screen(s) concept.a10.default, concept.a5.default, concept.a6.default, concept.a7.default, concept.a8.default, concept.a9.default, console.home.default, pipeline.default, runtime.ops.default, workspace.a1.default, workspace.a2.default, workspace.a3.default, workspace.a4.default
Reference-missing route(s) / surface(s) #admin, #conv, #gpu, #instances, #issues, #minio, #reports, #review, #sessions, #spec, #viewer
Full completion claimed no
Design reference manifest docs/plans/design-system-reference.manifest.json unchanged
Visual fidelity result required CI output artifacts/e2e/design-system-visual-result.json for head c1fdb6bfc9ff58b3821e5e168b278fc4e49e9b50; pending fresh CI
Visual comparison Chromium DPR1 at 1440x900 and 1920x1080; pixel diff <=1%; semantic parity 100%
Visual artifacts required CI *-actual.png and *-diff.png outputs; pending fresh head and not substituted by old artifacts
Known gaps no downloaded IFC-ready job; no fresh A3/A4 success manifest, screenshot PNG, runtime ID, or Kit/WebRTC first-frame/stage/DataChannel evidence; reference-missing: #admin, #conv, #gpu, #instances, #issues, #minio, #reports, #review, #sessions, #spec, #viewer

Deploy Path Verification

Item Result
Affects runtime / docker / Kit / viewer / ports / env? yes; test-only isolated runtime, viewer, environment, fixture, and reserved-port contracts
Canonical deploy path updated? production path unchanged; scripts/deploy.ps1 -DryRun passed on final code
New root script added? no; the registered launcher remains under scripts/dev/
Deploy dry-run command pwsh -NoProfile -NonInteractive -File scripts/deploy.ps1 -DryRun — passed
Full deploy tested no production/deployment mutation performed
Verify command pwsh -NoProfile -NonInteractive -File scripts/tests/test-isolated-branch-stack.ps1 — passed

Validation

Passed on the final code subject after the latest-main merge:

  • PowerShell isolated launcher contract, static checks, and production-boundary contract.
  • Targeted isolated Vitest: 69/69.
  • Targeted ESLint and git diff --check.
  • npm run typecheck.
  • npm run verify in web-viewer-sample: 78 files / 965 tests, production build, and struct-log 23/23.
  • Verification manifest suites: 22/22, 2/2, and 7/7.
  • OpenSpec strict: selected change valid; all 71/71.
  • Machine-truth core: 24/24; lifecycle current_slice length 482.
  • Deploy dry-run, secret scan, and security exceptions (0 exceptions).
  • GitNexus remained unavailable/UNKNOWN; this is a disclosed gap, not a pass.
  • A fresh real browser/runtime smoke was not run after 0170c8d; no full user-facing completion is claimed.

OpenSpec State

Merge Boundary

  • Explicit user consent to merge test: add isolated branch stack browser harness #431 is recorded.
  • Auto-merge may be enabled only after current protected checks, unresolved review-thread policy, and local preflight permit it.
  • No admin or branch-protection bypass will be used.

Copilot AI review requested due to automatic review settings July 29, 2026 19:35
@coderabbitai

coderabbitai Bot commented Jul 29, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review
📝 Walkthrough

Walkthrough

This PR adds a fail-closed isolated branch stack launcher with run-scoped state, manifests, process ownership checks, and structured logging. It wires manifest-authoritative Playwright E2E validation and evidence publication, updates A3/A4 consumers, and adds governance workflow and lifecycle documentation updates.

Changes

Isolated branch stack verification

Layer / File(s) Summary
Verification contracts and implementation plan
docs/agents/..., openspec/changes/isolated-branch-stack-browser-e2e/..., docs/plans/NOW.md, openspec/lifecycle-ledger.json, scripts/SCRIPT_CONTRACT.md, scripts/script-registry.json
Defines run-scoped state, port, manifest, ownership, evidence, lifecycle, and evidence-scope contracts for isolated governance/coordinator/browser verification.
Backend launcher and lifecycle gate
scripts/dev/start-isolated-branch-stack.ps1, scripts/lib/start-child-with-environment.ps1, scripts/tests/test-isolated-branch-stack.ps1
Implements start, status, and stop with deterministic manifests, reservations, child environment overrides, health checks, process lineage validation, rollback, atomic persistence, and structured lifecycle logs.
Manifest-bound browser configuration and evidence
web-viewer-sample/e2e/support/*, web-viewer-sample/playwright.config.ts, web-viewer-sample/vitest.config.ts, artifacts/e2e/.gitignore
Adds live backend identity checks, HTTP/WebSocket forbidden-port guards, manifest-authoritative Playwright setup, run-scoped output, and fail-closed evidence artifact validation and publication.
Require-real browser consumers and run evidence
web-viewer-sample/e2e/a3-federated-session-chain.spec.ts, web-viewer-sample/e2e/a4-closeout.spec.ts
Removes skip-based gating, strengthens A3 cleanup and request checks, records A4 query_id and runtime identifiers, and adds an explicit empty-result behavior test.
Governance workflow and repository gates
.github/workflows/agent-governance.yml, scripts/tests/test-agent-governance-check.ps1
Adds the isolated-stack PowerShell machine test and task-ledger parity test to governance checks while revising repository, production-boundary, CI, Codex, and ship-item assertions.

Estimated code review effort: 5 (Critical) | ~120 minutes

Sequence Diagram(s)

sequenceDiagram
  participant AgentGovernance
  participant IsolatedLauncher
  participant GovernanceBackend
  participant CoordinatorBackend
  participant Playwright
  participant EvidenceWriter

  AgentGovernance->>IsolatedLauncher: start isolated stack
  IsolatedLauncher->>GovernanceBackend: launch with run-scoped state
  IsolatedLauncher->>CoordinatorBackend: launch after governance health
  IsolatedLauncher-->>Playwright: write stack manifest
  Playwright->>CoordinatorBackend: probe health and verify ownership
  Playwright->>EvidenceWriter: publish same-run evidence
  AgentGovernance->>IsolatedLauncher: run machine tests and stop checks
Loading

Possibly related PRs

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title is concise and accurately reflects the main change: adding an isolated branch stack browser harness and related test infrastructure.
✨ Finishing Touches 💡 1
📝 Generate docstrings 💡
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch codex/openspec/isolated-branch-stack-browser-e2e

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 14

🧹 Nitpick comments (2)
artifacts/e2e/isolated-branch-stack-browser-e2e/p1-consumer-20260730-030207201-c15f2e25/stack-manifest.json (1)

35-56: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Manifest fields not modeled by the consumer type.

stopped_at and processes are emitted by the launcher but absent from IsolatedStackManifest in web-viewer-sample/e2e/support/isolated-stack.ts. The loader ignores extras so nothing breaks today, but the schema drift means consumers can't reason about lifecycle state. Consider adding both fields (optional) to the type.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@artifacts/e2e/isolated-branch-stack-browser-e2e/p1-consumer-20260730-030207201-c15f2e25/stack-manifest.json`
around lines 35 - 56, Update the IsolatedStackManifest type in isolated-stack.ts
to include optional stopped_at and processes fields matching the launcher
manifest schema. Model processes with the existing process-entry shape used by
the consumer, preserving compatibility with manifests where either field is
absent.
web-viewer-sample/e2e/a4-closeout.spec.ts (1)

143-175: 🚀 Performance & Scalability | 🔵 Trivial | ⚡ Quick win

Hoist the deterministic preflight out of beforeEach.

The nested loop issues up to orderedJobs.length × 8 real governance search POSTs, and it repeats for all six tests (3 tests × 2 viewports) even though the resolved (jobId, searchQuery) pair is deterministic for a fixed head/backend pair. Resolve it once (module-scoped memo or a beforeAll-style cached promise) and reuse it; the per-test budget is 180s and this fixture currently dominates it.

♻️ Sketch: memoize the preflight result
+let preflight: Promise<{ jobId: string; searchQuery: string }> | undefined;
+
     test.beforeEach(async ({ page, request }, testInfo) => {
-      jobId = "";
-      searchQuery = "";
-      // ... nested preflight loop ...
+      preflight ??= resolveDeterministicPreflight(request);
+      ({ jobId, searchQuery } = await preflight);
     });
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@web-viewer-sample/e2e/a4-closeout.spec.ts` around lines 143 - 175, Move the
deterministic preflight loop currently executed in beforeEach into a
module-scoped memoized resolver or beforeAll-style cached promise. Cache the
resolved jobId and searchQuery for each fixed head/backend pair, reuse that
result across all tests and viewports, and preserve the existing diagnostics and
requireReal failure behavior.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In
`@artifacts/e2e/isolated-branch-stack-browser-e2e/p1-consumer-20260730-030207201-c15f2e25/stack-manifest.json`:
- Around line 19-24: Update the manifest artifact for run
p1-consumer-20260730-030207201-c15f2e25 so its known-gap evidence matches the
recorded run: either replace it with a passing-ready run that exposes the
coordinator-listed ifc_ready_job_id, or revise the gap text to describe the
actual backend-unreadable, early-stop failure. Do not claim the isolated
Playwright configuration is blocked by a known gap without supporting readiness
evidence.

In `@docs/plans/NOW.md`:
- Line 42: Remove the blank line within the affected blockquote in NOW.md so the
entire progress note remains one contiguous blockquote and passes markdownlint
MD028.

In `@docs/superpowers/plans/2026-07-29-isolated-branch-stack-browser-e2e.md`:
- Line 57: Replace the bare completion output with the repository’s structured
logger: update
docs/superpowers/plans/2026-07-29-isolated-branch-stack-browser-e2e.md at line
57 to prescribe StructLog.psm1 logging, and update
scripts/tests/test-isolated-branch-stack.ps1 at line 361 to import and use the
same logger for the completion event.
- Around line 1-7: Update the document header near “Isolated Branch Stack
Browser E2E Implementation Plan” to explicitly label the document as a working
note and state that implementation is the runtime/API source of truth. Preserve
the existing plan content while satisfying the required docs classification and
authority boundary.
- Around line 2006-2007: Add the missing trailing comma after the
deployment-listeners-after.json entry in the Task 10 PowerShell path array,
preserving the existing evidence-manifest.json entry and ensuring the snippet
parses correctly.

In
`@openspec/changes/isolated-branch-stack-browser-e2e/specs/isolated-branch-stack-verification/spec.md`:
- Around line 34-36: Update Stop-IsolatedBackends and its process-record flow to
carry the resolved backend role/port for each PID, then revalidate the live
listener’s port against that expected resolved backend port immediately before
stopping. Preserve the existing PID, entrypoint, and creation-identity checks,
and fail closed without stopping when the port or any authorization field does
not match.

In `@openspec/changes/isolated-branch-stack-browser-e2e/tasks.md`:
- Line 28: Complete task 3.7 by implementing harness labeling and evidence
eligibility based on the VITE_VIEWER_HARNESS build/query flags. Ensure harness
runs are excluded from real coordinator authority evidence, then rerun the
relevant test until GREEN and execute typecheck, affected Vitest, and applicable
browser E2E checks. Update the task with the preserved RED/GREEN commands and
results and mark it complete.
- Line 41: Correct task 5.4’s status and wording to match the available
evidence: it currently documents a pre-browser failure caused by the absence of
a downloaded IFC-ready job, not a failed require-real browser run. Either
broaden task 5.4 to explicitly cover this failure mode or mark it incomplete,
avoiding the current checked status unless the required evidence exists.

In `@openspec/lifecycle-ledger.json`:
- Around line 1420-1425: Update the current_slice field in the lifecycle ledger
to accurately reflect the still-open launcher validation, harness
implementation, governance checks, browser evidence, and PR-body tasks listed in
tasks.md, rather than stating that only PR-only closeout remains. Keep the
ledger’s completed and total task counts consistent with the actual task status.

In `@scripts/dev/start-isolated-branch-stack.ps1`:
- Around line 195-197: Update the cleanup loop over the verified processes to
attempt every Stop-Process call even when an earlier stop throws, while
collecting any failures instead of aborting immediately. Persist a recoverable
partial-stop state in the manifest when only some stops succeed, so retries can
continue stopping surviving backends without failing ownership validation for
already-stopped PIDs. Add a failure-injection test covering a later stop failure
and verifying the manifest and retry behavior.
- Around line 338-342: Update the isolated-stack startup flow around the
preflight handling and backend launch so it acquires an exclusive run
reservation before invoking any backend start. Replace reliance on the
non-atomic preflight Test-Path check with the reservation, and retain that
reservation through manifest finalization; release it only after successful
manifest persistence or after the catch rollback completes, including cleanup
when startup fails.
- Around line 138-143: Update StartProcessFn and its coordinator launch call to
preserve argument boundaries when paths contain spaces: construct one argument
string with escaped inner quotes around the tsx entrypoint and index path before
passing it to -ArgumentList, rather than passing a raw string array. Add a
regression test covering coordinator startup from a worktree path containing
spaces.

In `@web-viewer-sample/e2e/a3-federated-session-chain.spec.ts`:
- Around line 51-59: Remove the mutating federated-set POST probe from
beforeEach and replace it with an existing read-only coordinator/governance
readiness route. Update the associated response validation to match that route,
while preserving the readiness failure handling and avoiding creation of any
federated_model_sets row.

In `@web-viewer-sample/e2e/support/isolated-stack.ts`:
- Around line 58-70: Harden URL parsing for request listeners so malformed or
non-HTTP(S) URLs cannot escape as uncaught exceptions: in
web-viewer-sample/e2e/support/isolated-stack.ts lines 58-70, update
createForbiddenRequestGuard().observe to safely parse and ignore unparsable or
non-HTTP(S) URLs before checking RESERVED_PORTS; in
web-viewer-sample/e2e/a4-closeout.spec.ts lines 100-104, apply the same guarded
parsing before reading pathname, or reuse the hardened helper for the
generic-route check.

---

Nitpick comments:
In
`@artifacts/e2e/isolated-branch-stack-browser-e2e/p1-consumer-20260730-030207201-c15f2e25/stack-manifest.json`:
- Around line 35-56: Update the IsolatedStackManifest type in isolated-stack.ts
to include optional stopped_at and processes fields matching the launcher
manifest schema. Model processes with the existing process-entry shape used by
the consumer, preserving compatibility with manifests where either field is
absent.

In `@web-viewer-sample/e2e/a4-closeout.spec.ts`:
- Around line 143-175: Move the deterministic preflight loop currently executed
in beforeEach into a module-scoped memoized resolver or beforeAll-style cached
promise. Cache the resolved jobId and searchQuery for each fixed head/backend
pair, reuse that result across all tests and viewports, and preserve the
existing diagnostics and requireReal failure behavior.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 0c1abfc9-8545-4ca3-b9ff-bda84d8d4898

📥 Commits

Reviewing files that changed from the base of the PR and between deb5af5 and 678abc1.

📒 Files selected for processing (26)
  • .github/workflows/agent-governance.yml
  • artifacts/e2e/isolated-branch-stack-browser-e2e/p1-consumer-20260730-030207201-c15f2e25/consumer-result.json
  • artifacts/e2e/isolated-branch-stack-browser-e2e/p1-consumer-20260730-030207201-c15f2e25/deployment-listeners-after.json
  • artifacts/e2e/isolated-branch-stack-browser-e2e/p1-consumer-20260730-030207201-c15f2e25/deployment-listeners-before.json
  • artifacts/e2e/isolated-branch-stack-browser-e2e/p1-consumer-20260730-030207201-c15f2e25/deployment-listeners-during.json
  • artifacts/e2e/isolated-branch-stack-browser-e2e/p1-consumer-20260730-030207201-c15f2e25/stack-manifest.json
  • docs/agents/product-operability-and-script-contract.md
  • docs/plans/NOW.md
  • docs/superpowers/plans/2026-07-29-isolated-branch-stack-browser-e2e.md
  • openspec/changes/isolated-branch-stack-browser-e2e/design.md
  • openspec/changes/isolated-branch-stack-browser-e2e/proposal.md
  • openspec/changes/isolated-branch-stack-browser-e2e/specs/isolated-branch-stack-verification/spec.md
  • openspec/changes/isolated-branch-stack-browser-e2e/tasks.md
  • openspec/lifecycle-ledger.json
  • scripts/SCRIPT_CONTRACT.md
  • scripts/dev/start-isolated-branch-stack.ps1
  • scripts/script-registry.json
  • scripts/tests/test-agent-governance-check.ps1
  • scripts/tests/test-isolated-branch-stack.ps1
  • web-viewer-sample/e2e/a3-federated-session-chain.spec.ts
  • web-viewer-sample/e2e/a4-closeout.spec.ts
  • web-viewer-sample/e2e/support/isolated-stack-global-setup.ts
  • web-viewer-sample/e2e/support/isolated-stack.test.ts
  • web-viewer-sample/e2e/support/isolated-stack.ts
  • web-viewer-sample/playwright.config.ts
  • web-viewer-sample/vitest.config.ts

Comment thread docs/plans/NOW.md
Comment thread docs/superpowers/plans/2026-07-29-isolated-branch-stack-browser-e2e.md Outdated
Comment thread docs/superpowers/plans/2026-07-29-isolated-branch-stack-browser-e2e.md Outdated
Comment thread scripts/dev/start-isolated-branch-stack.ps1
Comment thread scripts/dev/start-isolated-branch-stack.ps1
Comment thread scripts/dev/start-isolated-branch-stack.ps1 Outdated
Comment thread web-viewer-sample/e2e/a3-federated-session-chain.spec.ts Outdated
Comment thread web-viewer-sample/e2e/support/isolated-stack.ts Outdated

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR adds a fail‑closed, repo‑owned harness for running an isolated governance/coordinator "branch stack" so that unmerged branches can produce CPU/browser operability evidence without touching the single test‑deployment ports. It introduces a PowerShell launcher with per‑run identity, offset/port validation, process‑lineage ownership gates, and an immutable per‑run manifest; a TypeScript support module that binds Playwright to the manifest and writes typed browser evidence atomically; and it rewrites the A3/A4 Playwright specs to require‑real mode. It also wires a new machine check into the agent-governance workflow and records the first A4 consumer run honestly as a pre‑browser known gap (no A4 browser completion is claimed). This slots into the repo's existing OpenSpec governance and design/runtime evidence contracts.

Changes:

  • New launcher scripts/dev/start-isolated-branch-stack.ps1 (start|stop|status) with reserved‑port disjointness, offset 0..4 domain, ownership‑verified stop, and atomic manifest writes; registered in script registry + SCRIPT_CONTRACT.md and covered by test-isolated-branch-stack.ps1 (now run in agent-governance.yml).
  • New web-viewer-sample/e2e/support/isolated-stack.ts (+ tests + global setup) validating manifest identity/ports/head SHA and writing evidence manifests; playwright.config.ts/vitest.config.ts updated to consume it, and A3/A4 specs converted to require‑real (no skip‑to‑green).
  • OpenSpec artifacts updated (proposal/design/spec/tasks/ledger/NOW.md, 21/31 tasks) plus committed consumer evidence recording the A4 downloaded‑job known gap.

Reviewed changes

Copilot reviewed 25 out of 26 changed files in this pull request and generated 1 comment.

Show a summary per file
File Description
scripts/dev/start-isolated-branch-stack.ps1 New backend‑only launcher: port resolution, ownership gates, atomic manifest, rollback.
scripts/tests/test-isolated-branch-stack.ps1 Machine test for launcher behavior, registry/doc/workflow wiring.
scripts/tests/test-agent-governance-check.ps1 Asserts the workflow runs the new isolated‑stack test.
scripts/script-registry.json / scripts/SCRIPT_CONTRACT.md Registers launcher as non‑canonical branch adapter.
.github/workflows/agent-governance.yml Adds isolated‑stack machine test step.
web-viewer-sample/e2e/support/isolated-stack.ts Manifest validation, reserved‑port guard, atomic evidence writer.
web-viewer-sample/e2e/support/isolated-stack.test.ts Vitest coverage for the helper.
web-viewer-sample/e2e/support/isolated-stack-global-setup.ts Pre‑spec coordinator/viewer probes.
web-viewer-sample/playwright.config.ts / vitest.config.ts Manifest‑authoritative wiring; includes support tests.
web-viewer-sample/e2e/a4-closeout.spec.ts / a3-federated-session-chain.spec.ts Rewritten to require‑real mode using the helper.
openspec/**, docs/plans/NOW.md, docs/agents/product-operability-and-script-contract.md Contract/spec/tasks/ledger updates for the change.
artifacts/e2e/.../*.json Committed consumer/manifest/listener evidence (known‑gap run).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 678abc1562

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread web-viewer-sample/e2e/support/isolated-stack.test.ts
Comment thread web-viewer-sample/e2e/a3-federated-session-chain.spec.ts Outdated
Comment thread scripts/dev/start-isolated-branch-stack.ps1 Outdated
Comment thread web-viewer-sample/e2e/a3-federated-session-chain.spec.ts Outdated
Comment thread web-viewer-sample/e2e/a4-closeout.spec.ts Outdated
Comment thread web-viewer-sample/e2e/support/isolated-stack-global-setup.ts Outdated
Comment thread scripts/dev/start-isolated-branch-stack.ps1 Outdated
Comment thread scripts/dev/start-isolated-branch-stack.ps1 Outdated

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ed69a72d4c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread web-viewer-sample/e2e/support/isolated-stack-global-setup.ts Outdated
Comment thread web-viewer-sample/e2e/support/isolated-stack.ts Outdated
Comment thread openspec/lifecycle-ledger.json Outdated
Comment thread web-viewer-sample/e2e/a4-closeout.spec.ts Outdated
Comment thread scripts/dev/start-isolated-branch-stack.ps1 Outdated
Comment thread scripts/dev/start-isolated-branch-stack.ps1 Outdated

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3

🧹 Nitpick comments (2)
scripts/dev/start-isolated-branch-stack.ps1 (2)

120-149: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Unapproved verbs Acquire-/Release-.

PSScriptAnalyzer PSUseApprovedVerbs flags both; approved equivalents are Lock-/Unlock- or New-/Remove-. Worth renaming now (with the test call sites) since the analyzer wasn't runnable in this PR.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@scripts/dev/start-isolated-branch-stack.ps1` around lines 120 - 149, Rename
Acquire-IsolatedStackReservations and Release-IsolatedStackReservations to
approved-verb equivalents, preferably Lock-IsolatedStackReservations and
Unlock-IsolatedStackReservations, and update every corresponding test and
call-site reference. Preserve the existing reservation creation and cleanup
behavior.

104-111: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Embedded-quote escaping is wrong and untested. .NET replacement strings expand only $-substitutions, so '$1$1\\"' emits two backslashes plus a bare "; CommandLineToArgvW then sees a literal backslash and a quote toggle, breaking the argument boundary. The gap survives because the only regression covers a spaced path with no quotes.

  • scripts/dev/start-isolated-branch-stack.ps1#L104-L111: change the replacement to $1$1\" so each inner quote is escaped with exactly one backslash.
  • scripts/tests/test-isolated-branch-stack.ps1#L41-L46: add a case with an argument containing an embedded " (and a trailing backslash) and assert the exact expected command line.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@scripts/dev/start-isolated-branch-stack.ps1` around lines 104 - 111, The
embedded-quote replacement in ConvertTo-IsolatedWindowsArgumentLine is
over-escaping backslashes; update it to emit exactly one backslash before each
inner quote. In scripts/dev/start-isolated-branch-stack.ps1 lines 104-111, make
that replacement change. In scripts/tests/test-isolated-branch-stack.ps1 lines
41-46, add coverage for an argument containing an embedded quote and trailing
backslash, asserting the exact generated command line.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In
`@openspec/changes/isolated-branch-stack-browser-e2e/specs/isolated-branch-stack-verification/spec.md`:
- Around line 66-72: Update the wording in the partial-stop recovery scenario so
“listener時” becomes “listener 時,” preserving all surrounding behavior and
requirements unchanged.

In `@openspec/changes/isolated-branch-stack-browser-e2e/tasks.md`:
- Line 50: Update the completion status in tasks.md so it does not claim “Full
completion claimed” while tasks 2.5, 3.7, 4.3, 5.2, and 5.3 remain unresolved.
Mark the change as partial/known-gap, or complete or formally delegate every
outstanding task before retaining the full-completion claim; archive tasks.md
only after all tasks are checked or an accepted successor inherits them.
- Line 49: Update checklist item 6.4 to require recording the stable repository
verification gate, npm run verify, in the completion evidence. If that command
is intentionally not run, document an explicit exception alongside the existing
targeted checks, while preserving the current deploy dry-run, diff, secret scan,
and status requirements.

---

Nitpick comments:
In `@scripts/dev/start-isolated-branch-stack.ps1`:
- Around line 120-149: Rename Acquire-IsolatedStackReservations and
Release-IsolatedStackReservations to approved-verb equivalents, preferably
Lock-IsolatedStackReservations and Unlock-IsolatedStackReservations, and update
every corresponding test and call-site reference. Preserve the existing
reservation creation and cleanup behavior.
- Around line 104-111: The embedded-quote replacement in
ConvertTo-IsolatedWindowsArgumentLine is over-escaping backslashes; update it to
emit exactly one backslash before each inner quote. In
scripts/dev/start-isolated-branch-stack.ps1 lines 104-111, make that replacement
change. In scripts/tests/test-isolated-branch-stack.ps1 lines 41-46, add
coverage for an argument containing an embedded quote and trailing backslash,
asserting the exact generated command line.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 947dc9dd-2570-4ae3-890a-ff1a7d08fc0c

📥 Commits

Reviewing files that changed from the base of the PR and between 678abc1 and aef24b2.

📒 Files selected for processing (19)
  • artifacts/e2e/isolated-branch-stack-browser-e2e/review-repair-b4d3c55/consumer-result.json
  • artifacts/e2e/isolated-branch-stack-browser-e2e/review-repair-b4d3c55/deployment-listeners-after.json
  • artifacts/e2e/isolated-branch-stack-browser-e2e/review-repair-b4d3c55/deployment-listeners-before.json
  • artifacts/e2e/isolated-branch-stack-browser-e2e/review-repair-b4d3c55/deployment-listeners-during.json
  • artifacts/e2e/isolated-branch-stack-browser-e2e/review-repair-b4d3c55/stack-manifest.json
  • docs/plans/NOW.md
  • docs/superpowers/plans/2026-07-29-isolated-branch-stack-browser-e2e.md
  • openspec/changes/isolated-branch-stack-browser-e2e/design.md
  • openspec/changes/isolated-branch-stack-browser-e2e/specs/isolated-branch-stack-verification/spec.md
  • openspec/changes/isolated-branch-stack-browser-e2e/tasks.md
  • openspec/lifecycle-ledger.json
  • scripts/dev/start-isolated-branch-stack.ps1
  • scripts/tests/test-isolated-branch-stack.ps1
  • web-viewer-sample/e2e/a3-federated-session-chain.spec.ts
  • web-viewer-sample/e2e/a4-closeout.spec.ts
  • web-viewer-sample/e2e/support/isolated-stack-global-setup.ts
  • web-viewer-sample/e2e/support/isolated-stack.test.ts
  • web-viewer-sample/e2e/support/isolated-stack.ts
  • web-viewer-sample/playwright.config.ts
💤 Files with no reviewable changes (1)
  • web-viewer-sample/e2e/support/isolated-stack-global-setup.ts
🚧 Files skipped from review as they are similar to previous changes (8)
  • docs/plans/NOW.md
  • openspec/lifecycle-ledger.json
  • web-viewer-sample/playwright.config.ts
  • web-viewer-sample/e2e/support/isolated-stack.test.ts
  • web-viewer-sample/e2e/a4-closeout.spec.ts
  • docs/superpowers/plans/2026-07-29-isolated-branch-stack-browser-e2e.md
  • web-viewer-sample/e2e/a3-federated-session-chain.spec.ts
  • openspec/changes/isolated-branch-stack-browser-e2e/design.md

Comment thread openspec/changes/isolated-branch-stack-browser-e2e/tasks.md Outdated
Comment thread openspec/changes/isolated-branch-stack-browser-e2e/tasks.md Outdated

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: aef24b2dea

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread web-viewer-sample/e2e/support/isolated-stack.ts
Comment thread web-viewer-sample/e2e/a4-closeout.spec.ts Outdated
Comment thread scripts/dev/start-isolated-branch-stack.ps1 Outdated

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c4c759a274

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread web-viewer-sample/e2e/support/isolated-stack.ts
Comment thread web-viewer-sample/e2e/support/isolated-stack.ts
Comment thread web-viewer-sample/e2e/support/isolated-stack.ts
Comment thread scripts/dev/start-isolated-branch-stack.ps1
Comment thread web-viewer-sample/playwright.config.ts Outdated

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2d6ee9c78e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread scripts/dev/start-isolated-branch-stack.ps1
Comment thread scripts/dev/start-isolated-branch-stack.ps1

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 63ba35c8ab

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread web-viewer-sample/e2e/support/isolated-stack.ts Outdated
Comment thread scripts/dev/start-isolated-branch-stack.ps1 Outdated
Comment thread scripts/dev/start-isolated-branch-stack.ps1 Outdated

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2eeab7e2d4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread web-viewer-sample/playwright.config.ts
Comment thread web-viewer-sample/e2e/support/isolated-stack.ts Outdated

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: cb27856c42

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread scripts/dev/start-isolated-branch-stack.ps1 Outdated

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9ed319ae81

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread scripts/lib/start-child-with-environment.ps1 Outdated
Comment thread web-viewer-sample/e2e/a3-federated-session-chain.spec.ts Outdated
Comment thread web-viewer-sample/e2e/support/isolated-stack.ts Outdated
@monkey1sai
monkey1sai enabled auto-merge (squash) July 30, 2026 17:24
@monkey1sai
monkey1sai merged commit 257e8f1 into main Jul 30, 2026
34 checks passed
@monkey1sai
monkey1sai deleted the codex/openspec/isolated-branch-stack-browser-e2e branch July 30, 2026 17:27

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c1fdb6bfc9

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +654 to +655
if ($Role -eq 'governance') {
return @{

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Inject a run-local A4 internal token

When a downloaded IFC-ready job is available, the A4 preflight still cannot reach governance: the child wrapper removes inherited A4_INTERNAL_CONTEXT_TOKEN, but neither environment returned by New-IsolatedBackendEnvironment supplies a replacement. forwardTrustedA4 therefore returns 503 a4_trusted_context_unavailable for every /for-ifc-ready/ search before contacting governance, so tasks 5.2/5.3 remain impossible even after the documented fixture gap is fixed; generate one run-local token and inject the same value into both backend environments.

AGENTS.md reference: AGENTS.md:L43-L43

Useful? React with 👍 / 👎.

Comment on lines +1357 to +1358
$rollbackResults = @(Stop-IsolatedBackends -Processes @($started) -IdentityLookup $IdentityLookup -ProcessHandleLookup $ProcessHandleLookup -StopProcessFn $StopProcessFn -MissingProcessFn $rollbackMissingProcessFn -AllowMissing)
$rollbackFailures = @($rollbackResults | Where-Object { $_.status -in @('not_owned','stop_failed') })

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Verify descendant exit during startup rollback

Fresh evidence beyond the earlier normal-stop finding is that the startup catch path still treats Stop-IsolatedBackends returning stopped as a complete rollback without calling Wait-IsolatedBackendTermination. If health checking or manifest publication fails after a backend spawns, the default stop callback waits only for the wrapper process; a descendant listener can remain briefly or indefinitely, yet this path releases the reservations and writes no recovery manifest, leaving the isolated port occupied with no ownership-gated retry path.

Useful? React with 👍 / 👎.

"scripts/tests/test-isolated-branch-stack.ps1"
],
"subject_commit": "deb5af552022c3ee171e3174f59c9f1e3dfb5936",
"subject_commit": "72fcf5f85ee1460b42b5f57a0709634bbf816c02",

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Bind ledger subjects to the squashed history

Fresh evidence specific to reviewed commit 8786735 is that the squash made this subject_commit non-ancestral: git merge-base --is-ancestor 72fcf5f 8786735 fails, as does the shared 6fc759d subject now assigned to the other ledger rows. collectSourceObservations explicitly rejects every non-ancestor subject with subject_not_ancestor, so the required full machine-truth verifier cannot validate this checkout even when those otherwise-unreachable objects happen to exist locally; update the ledger and NOW projection to snapshots that are ancestors of the squashed head.

AGENTS.md reference: openspec/AGENTS.md:L32-L32

Useful? React with 👍 / 👎.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants