docs: define agent runtime bridge

[vincentkoc]

Summary

• Add an Agent runtime bridge contract for future harness-in-the-box Station support.
• Define loopback daemon binding, scoped bridge tickets, stop semantics, egress posture, evidence, unsupported-provider behavior, and modelAccess separation.
• Link the contract from Station profiles, feature index, source map, and changelog.

Related: #530
Related: #193

Verification

• git diff --check
• scripts/check-docs.sh

[clawsweeper]

Codex review: found issues before merge. Reviewed July 4, 2026, 8:56 AM ET / 12:56 UTC.

Summary
The branch adds an agent runtime bridge documentation contract, links it from Station/features/source-map docs, and adds an Unreleased changelog entry.

Reproducibility: not applicable. this is a docs/product contract PR, not a bug report. Source inspection confirms current main lacks this specific agent runtime bridge contract while the runtime remains future work.

Review metrics: 2 noteworthy metrics.

• Docs surface: 5 files changed; 222 additions, 0 deletions. The PR is a documentation contract and index/source-map update rather than runtime code.
• Release-owned file touch: 1 CHANGELOG.md entry added. Maintainers should notice the release-flow concern before merge.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🌊 off-meta tidepool
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• Remove or explicitly release-approve the CHANGELOG.md entry.
• Have maintainers/security owners confirm the agent bridge boundary before merging.

Risk before merge

• [P1] Merging this PR would make the agent-control, egress, bridge authorization, and modelAccess boundary accepted roadmap text, so maintainer/security signoff matters even though the diff is documentation-only.
• [P1] The branch still edits CHANGELOG.md directly, which conflicts with the release-owned changelog flow unless a release owner intentionally accepts it.

Maintainer options:

1. Land after contract signoff (recommended)
   Have maintainers/security owners accept the bridge boundary and move the release-note text out of the PR-owned changelog edit before merge.
2. Pause the contract
   Keep the draft open or close it if maintainers decide the agent bridge direction should stay only in the linked roadmap issues for now.

Next step before merge

• [P2] Manual review is appropriate because this draft member-authored docs contract needs maintainer product/security signoff and a release-flow decision for CHANGELOG.md.

Security
Cleared: The diff is documentation-only and adds security constraints for future work without introducing executable code, dependencies, secrets handling, or supply-chain changes.

Review findings

• [P3] Remove the release-owned changelog entry — CHANGELOG.md:3-7

Review details

Best possible solution:

Land the contract docs after maintainer/security signoff, with release-note text handled through the release-owned changelog flow.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is a docs/product contract PR, not a bug report. Source inspection confirms current main lacks this specific agent runtime bridge contract while the runtime remains future work.

Is this the best way to solve the issue?

Mostly yes: defining the contract before implementation is the maintainable path for security-sensitive Station bridge work. The changelog entry should be removed or explicitly release-approved before merge.

Full review comments:

• [P3] Remove the release-owned changelog entry — CHANGELOG.md:3-7
CHANGELOG.md is release-owned for normal PRs, but this branch adds an Unreleased section. Keep the release-note context in the PR body or have a release owner add it during release prep so this branch does not churn the release file.
  Confidence: 0.87

Overall correctness: patch is correct
Overall confidence: 0.86

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against c5bc10cc058e.

Label changes

Label changes:

• add merge-risk: 🚨 other: Merging establishes a product/security contract for a future agent bridge that CI cannot validate and maintainers must explicitly accept.

Label justifications:

• P3: This is low-risk documentation/product-contract work for a future capability, not a current runtime regression.
• merge-risk: 🚨 other: Merging establishes a product/security contract for a future agent bridge that CI cannot validate and maintainers must explicitly accept.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: Real behavior proof is not required for this member-authored documentation contract PR.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was read fully; its provider-neutral architecture and secret-handling guidance are relevant to this agent bridge contract review. (AGENTS.md:1, c5bc10cc058e)
• PR diff scope: The PR diff changes five files with documentation/index/source-map edits plus a CHANGELOG.md entry; the new contract is docs-only and contract-only. (docs/features/agent-runtime-bridge.md:1, 3166853ee9aa)
• Current main Station status: Current main documents that the Station skeleton has no crabbox station command, no top-level stationProfile wiring, and no live modelAccess delivery. (docs/features/station-profiles.md:6, c5bc10cc058e)
• Current main implementation boundary: internal/station is deliberately limited to config/profile/gating types and has no supervisor, lease, or credential delivery wired yet. (internal/station/station.go:1, c5bc10cc058e)
• Prior finding still applies: The previous ClawSweeper review asked to remove the release-owned changelog entry, and the current head still adds an Unreleased CHANGELOG.md section. (CHANGELOG.md:3, 3166853ee9aa)
• Related roadmap items remain open: The linked Station roadmap and harness-in-the-box issues are both open and already marked as product/security-review work rather than completed implementation.

Likely related people:

• zozo123: Introduced the Station profiles roadmap and initial internal Station profile primitive that this docs contract extends. (role: roadmap and station skeleton introducer; confidence: high; commits: 871ed6feee17, 322a972fe04b, 463e8d81f152; files: docs/features/station-profiles.md, internal/station/station.go, internal/station/config.go)
• vincentkoc: Committed modelAccess/env.allow hardening and recent contract-doc/release-flow work on current main; this connects them to the relevant docs and Station boundary beyond merely authoring this PR. (role: security-boundary hardening contributor; confidence: high; commits: 7347a2969d01, 974d5c6ca1b8, 38ce612d161e; files: internal/station/gate.go, internal/station/gate_test.go, docs/features/README.md)
• steipete: Current main blame for station/source-map/changelog release state points to the 0.35.0 release commit, and this PR also contains a hardening commit from this person. (role: recent release/docs and adjacent security contributor; confidence: medium; commits: 192e382e9044, 3166853ee9aa; files: CHANGELOG.md, docs/features/station-profiles.md, docs/source-map.md)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

Review history (1 earlier review cycle)

• reviewed 2026-07-04T10:03:38.606Z sha 322a923 :: found issues before merge. :: [P3] Remove the release-owned changelog entry