feat(supervisor): add managed Pi admission bridge

[johnnygreco]

What changed

• add a general agent-conversation supervisor middleware operation and binding metadata
• expose a managed sandbox loopback bridge for Pi admission requests
• preserve upstream HTTP and WebSocket middleware behavior while adding deny, redact, and receipt responses
• document the managed Pi admission flow and its current boundaries

Why

This allows a Pi extension to submit rendered user input to OpenShell middleware before Pi appends it to conversation history. A denial prevents persistence, while an allowed replacement supports redaction.

Validation

• mise run pre-commit
• cargo test -p openshell-supervisor-middleware -p openshell-supervisor-middleware-builtins (100 passed)
• cargo test -p openshell-sandbox agent_bridge (2 passed)
• cargo check --manifest-path examples/supervisor-middleware-content-guard/Cargo.toml

[johnnygreco]

Review Record — Phase 0

Frozen target: openshell/pi-egress-admission 8332c459..openshell/pi-egress-admission 5f542b70
Diff command: git diff 8332c459..5f542b70

Panel:

• OpenShell Phase 0 independent reviewer: robustness/correctness, maintainability/complexity, tests, security impact, documentation/adoption, integration -> clean after rerun

Skipped Review-Standard lenses: user UI experience — no UI behavior changed; performance/concurrency — removal of one environment alias has no meaningful hot-path or concurrency surface.

Accepted findings fixed:

• Two current agent skills still documented the removed OPENSHELL_PI_CONVERSATION_URL alias -> both now direct all harnesses to OPENSHELL_AGENT_CONVERSATION_URL only.

Rejected findings:

• none

Validation after fixes:

• cargo test -p openshell-sandbox -> 134 passed
• mise run pre-commit -> passed after the review fix
• mise run test -> passed
• acceptance grep and git diff --check -> passed
• mise run ci -> reached one pre-existing unrelated Go converter coverage failure for ProviderProfileCredential.delivery; the Phase 0 diff changes no Go/protobuf files

Final status: rerun reviewer clean at 5f542b70.

[johnnygreco]

Phase 2 Review Record

Frozen range: 5f542b70..8f208f5c

Scope: the single bridge behavior required by Phase 2—an admission allow with empty attestation returns the existing optional handle: None; nonempty allows and denials remain unchanged.

Independent review returned clean. It confirmed provider-port validation and handle issuance remain on the nonempty path, deny/unspecified behavior is unchanged, None already serializes as an omitted handle, and no provider-context authorization bypass is introduced.

Scope remained one Rust file and one focused regression. No protobuf, caller identity, provider, compatibility, documentation, or framework changes.

Validation:

• cargo fmt --check: passed.
• Focused bridge tests: 6 passed.
• Full cargo test -p openshell-sandbox: 135 passed.
• mise run pre-commit: passed.
• git diff --check: passed.

[johnnygreco]

Phase 3 Review Record

Frozen range: 8f208f5c..f5212b58

Scope reviewed: strict base64 bridge JSON boundary, empty-vs-absent replacement semantics, encoded/logical size limits, malformed/legacy input rejection, workload metadata removal, and focused middleware/sandbox/reference documentation.

Independent findings and fixes:

• Current docs incorrectly described one binding and omitted agent binding identity/payload/timeout behavior. f5212b58 corrects only those factual paragraphs.
• The bridge still exposed middleware metadata although the Phase 3 workload contract drops it. f5212b58 deletes the field/forwarding and adds a focused non-forwarding assertion.
• Base64 and final metadata/docs re-reviews returned clean with no blocker/high/medium findings.

Scope audit:

• Base64 implementation is five files, including the existing workspace dependency and one-line lock update.
• Follow-up is 8 insertions/12 deletions across three files.
• No proto, provider, caller identity, compatibility decoder, generalized codec, or unrelated changes.

Validation:

• Focused bridge tests: 7 passed.
• mise run docs, mise run pre-commit, and mise run test: passed.
• Formatting and diff checks: passed.
• mise run ci reaches only the known unrelated Go converter coverage gap for pre-existing ProviderProfileCredential.delivery; no Go/proto file changed.

[johnnygreco]

Phase 4 Review Record

Reviewed head: 1e2b1649a42db6dfa1ad688a57f9ec2d9071d6b0

Scope remained POC-bounded: a private per-exec token registry, inherited-FD delivery through the existing SSH exec paths, bridge bearer validation, a default-on supervisor debug flag, focused tests, and two documentation bullets. No gateway, protobuf, middleware-schema, identity-service, TTL, audit, or generalized-auth changes were added.

Independent security and maintainability reviews found and verified fixes for:

• process-wide FD inheritance during concurrent spawn: token descriptors now start atomically CLOEXEC, and only the intended post-fork child clears/installs its descriptor;
• delayed revocation: registrations are dropped immediately after child.wait();
• macOS build compatibility: Apple reserves a CLOEXEC descriptor and installs the pipe only inside the intended child.

Final independent verdict: clean; no remaining blocker/high/medium findings.

Validation:

• focused token lifecycle: 3/3
• focused bridge/config: 9/9
• full modified crates: sandbox 127 + 10 main + 1 integration; supervisor-process 241 passed / 2 ignored
• cargo check, formatting, strict clippy, mise run pre-commit, mise run test, and mise run e2e:docker: pass
• mise run ci: only the known unrelated Go converter coverage failure for pre-existing ProviderProfileCredential.delivery; no Go/protobuf files changed
• macOS execution is delegated to the repository's native macOS CI; local cross-check was blocked by the missing Apple SDK before this crate

[johnnygreco]

I have read the DCO document and I hereby sign off on the commits contained in this PR.

[johnnygreco]

Final Review Record

Reviewed head: abf1a6253009c78196d8fe4fb560590453216f04
Upstream/fork base: a6b757d35f983fe4415427484ad06533d32e9e4b

Independent security, lifecycle, upstream-merge, SDK, and integration reviews are clean: no remaining blocker, high, or medium findings. Accepted findings were fixed narrowly: atomic close-on-exec capability delivery, immediate post-exit revocation, macOS-safe child-only descriptor installation, and complete Go SDK round-tripping for proxy credential delivery.

Validation:

• focused bridge/token/config and provider-profile suites: pass
• full modified-crate suites: pass
• mise run pre-commit: pass
• mise run test: pass
• mise run go:ci: pass, including race tests, lint, build, docs, and generated-proto checks
• mise run e2e:docker: pass at the Phase 4 parent integration head
• active fork checks (E2E/GPU E2E/security/actionlint/preview/dependency): pass; delegated Branch Checks and Helm Lint remain pending

The standard non-rewrite DCO declaration is posted on this PR for the two older unsigned commits. The PR remains draft; no merge/readiness change was made.

[johnnygreco]

Proxy credential delivery integration

Updated head: 57cbc0dc9305e657bb6177d2d6dd63baa2f5ccfc
Merged source: johnny/proxy-delivered-provider-auth at bd5d278fdfc5d8c0c43c1759916868eb61be8f12

The merge adopts the branch’s binding-driven proxy credential delivery and preserves this PR’s agent-admission bridge changes. Generated Go protobuf code was regenerated from the combined schema.

Validation:

• focused provider/server/supervisor-network suites: passed
• mise run go:ci: passed
• mise run pre-commit: passed
• mise run test: passed
• mise run ci: passed
• Docker E2E: the new provider_proxy_delivery case passed; the broader lane later failed the separate policy_reload_updates_both_adapters_and_closes_existing_http_tunnel case because its sandbox emitted no JSON result
• diff/conflict-marker checks: passed

The PR remains draft.