test(shields): verify child exit before policy restore

[cjagwani]

Summary

The Shields hung-owner takeover test now proves that the exact weakening child process is gone or a zombie before policy restoration. This replaces a wall-clock sentinel oracle without changing production behavior.

Related Issue

Closes #7259

Part of #7451

Changes

• Keep the weakening child alive until takeover instead of scheduling a delayed sentinel write.
• Identify that child by PID and process-start identity at the policy restoration boundary.
• Preserve assertions for owner-stop ordering, descendant enumeration, transition cleanup, policy restoration, and cleanup of the exact child.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification:
• Docs updated for user-facing behavior changes
• Docs not applicable — justification: this is test-only oracle hardening; documented Shields behavior and public contracts are unchanged.
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification: exact refreshed diff changes only src/lib/shields/flow.test.ts; the nine-category review passes because no production, credential, authorization, dependency, configuration, logging, cryptography, or runtime behavior changes.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: no-docs-needed
• Evidence: src/lib/shields/flow.test.ts only strengthens coverage that the weakening child exits before policy restoration. It changes no command, output, configuration, workflow, or supported behavior. Existing runtime-controls and command-reference docs already describe this ordering. The focused CLI suite passed 22/22, npm run test:changed exited 0 with no additional tests, and Biome passed.
• Agent: Codex Desktop

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit:
• Station profile/scenario:
• Result:
• Supporting evidence:

Verification

• PR description includes a Signed-off-by: line and every published commit appears as Verified in GitHub
• npm run check:diff reproduced the pre-commit, commit-msg, and pre-push gates on exact refreshed head e3e9eaa45; all applicable checks passed.
• Targeted behavior tests pass for the current change set — npx vitest run --project cli src/lib/shields/flow.test.ts: 22/22 passed; npm run test:changed: exited 0 with no additional test files; npm run typecheck:cli and Biome passed.
• Applicable broad gate passed — not required for this one-file test-only change; focused tests and exact-diff hooks passed, with broad coverage delegated to CI.
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Charan Jagwani cjagwani@nvidia.com

Summary by CodeRabbit

• Tests
  • Improved coverage for recovering from a stalled policy owner.
  • Added stronger verification that policy restoration completes, transition state is cleaned up, and takeover events occur in the expected order.
  • Simplified test coordination for more reliable validation of subprocess replacement and recovery behavior.

[coderabbitai]

📝 Walkthrough

Walkthrough

The Shields takeover test replaces sentinel-based timing with readiness-file coordination, process liveness checks at policy restoration, transition-file cleanup assertions, and takeover event-order validation.

Changes

Shields takeover test

Layer / File(s)	Summary
Replace sentinel coordination src/lib/shields/flow.test.ts	Embedded owner and child scripts use readiness-file coordination and long-running intervals; the owner spawn arguments and test setup are updated accordingly.
Validate deterministic takeover src/lib/shields/flow.test.ts	A custom harness verifies policy restoration and weakening-child termination state, while assertions check transition cleanup and takeover event ordering.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested reviewers: ericksoa

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The test-only changes match #7259 by replacing timer-based safety with a deterministic restore-boundary check and preserving cleanup/order assertions.
Out of Scope Changes check	✅ Passed	The PR stays within the Shields test file and doesn't introduce unrelated production or extra feature changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately reflects the test-only Shields change to verify the child exits before policy restoration.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/7451-shields-child-lifecycle

---

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

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit e3e9eaa in the codex/7451-shields-c... branch remains at 96%, unchanged from commit 5f5971c in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit e3e9eaa in the codex/7451-shields-c... branch remains at 81%, unchanged from commit 5f5971c in the main branch.

Show a code coverage summary of the most impacted files.

File	main 5f5971c	codex/7451-shields-c... e3e9eaa	+/-
src/lib/sandbox...rce-identity.ts	87%	87%	0%
src/lib/domain/.../connect-env.ts	89%	97%	+8%

---

_{Updated July 26, 2026 00:26 UTC}

[github-actions]

PR Review Advisor — No blocking findings reported

Advisor assessment: No blocking advisor findings reported
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings match; normalized E2E selections differ; severity counts match.

Nemotron output stays in workflow artifacts and does not change the assessment above.

E2E guidance

Advisory only. E2E / PR Gate selects and runs jobs independently.

Recommended E2E: None

1 optional E2E recommendation

• shields-config

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.

[cv]

Approved at exact head e3e9eaa after product-scope, DCO/Verified, documentation-writer, nine-category security, unresolved-thread, exact-head advisor, focused local validation, canonical CI, and selected E2E gates passed. Canonical gate checker reports allPass=true with all 51 current checks green.