Repository navigation
Pair a gateway as an environment that serves and never reads (slice I of #252, part 1a) - #744
Conversation
… of #252, part 1a) The owner can now create an environment invitation with `pairing.create {"enrollee":"environment"}`. It runs the same one-use pairing on the same listener. What it issues names the peer gateway principal and holds `environment.serve` alone, so a machine paired to run agents can never read a conversation. - Auth: a new `environment.serve` action that only a gateway principal may hold. A third consent class, `PeerEnvironment`. `ConsentClass::grant` is the one owner of which grant a class hands out. Owner admission asks for the owner's own grant only when the class delegates it. `validate_grants` asks `may_hold` on every issuing path and on open. The Cedar policy allows it to active members. - Server: `pairing.create` maps the new enrollee. `conversation.share` refuses a credential that cannot read. - Protocol: `PairingEnrollee` gains `environment`; generated types are regenerated. - Docs: the "Environment peers" section and row I1 in peer-gateways.md, and read-grants.md. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EL5rzp9FLsixdtkMSbgffp
The socket fixture answers every share target with the caller's snapshot, which held no conversation.read, so the new check refused its device. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EL5rzp9FLsixdtkMSbgffp
|
@codex review Generated by Claude Code |
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 17b78d882f
ℹ️ 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".
There was a problem hiding this comment.
Your trial has ended. Reactivate Greptile to resume code reviews.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 17b78d882f
ℹ️ 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".
A registry answer whose conversation.read grant is on another resource of the same organization no longer counts: the share is refused share_target_not_paired, as Codex found on #744. Part of #706. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EL5rzp9FLsixdtkMSbgffp
|
Generated by Claude Code |
## Motivation The recovered October9–12 ADR audits are the remaining source evidence deferred by [#23](#23). Most of their lessons already live in the ADR reconciliation procedure added by [#22](#22): decision acceptance is separate from delivery, slices need their own evidence, inventories need lifecycle placement, and stale claims must be repaired wherever readers encounter them. One useful distinction can be clearer: a feature name is not proof that the shipped design satisfies the decided contract. A different mechanism may preserve the guarantee, leave a real implementation gap, or require an explicit decision revision. This draft makes that comparison explicit without prescribing the historical proposal as the correct design. ## Solution 1. `8a72865`: amend the existing ADR scope-reconciliation paragraph to compare promised guarantees and distinguish an implementation gap from a decision needing explicit revision. 2. `8a72865`: add one Core Rule2 example that links to that owner; keep all historical project detail here. Only two existing documentation files change. This is a narrow clarification, so package/plugin versions remain `0.6.0`; the repository requires bumps for broad changes. No new skill, duplicate audit checklist, workflow, implementation, ADR file or issue is introduced. **Leave this PR as a draft; do not merge without separate approval.** ### Baseline and source access - Based on the actual default `wip` at `572b154685a75892b54d939e1d2d9b0e6fb22477`, the merged #23 tree. Root `AGENTS.md`, the engineering ownership table, ADR, architecture, method and review owners were inspected. No additional applicable `.agents` instructions were present. - No competing open skills PR was found before editing. Earlier skills issues are older Rust research, not a new ADR integration. - Input is the recovered historical report-message evidence supplied with this task. Full thread text was not accessible in this executor; ZIP issue-body attachments remain unavailable. Neither original issue drafts nor publication receipts are claimed inspected. - Read-only public source checks inspected relevant PR metadata and excerpts of the ADR index, runtime ADR, Read-grants design and physical-persistence design at the October12 snapshot. These corroborate the bounded mechanism comparison; they are not a fresh audit of current Nessa. ### Source-to-owner dispositions | Recovered finding family | Disposition | Existing owner / reason | | --- | --- | --- | | 501 linked once with unique identity but absent from lifecycle table | Already covered | ADR inventory structure requires repository-consistent placement and says a stray link is not index coverage. Uniqueness and membership are separate checks already expressed. | | 252 acceptance versus implementation checklist and tracking state | Already covered | ADR scope reconciliation separates accepted decisions, shipped slices, evidence and remaining gates; reader-surface repair includes tracking issues. | | Partial replay, grants, artifacts, pairing and outbound delivery | Already covered | Per-slice evidence and gates; one merged implementation does not establish full scope. | | A proposed Cedar/semantic-record design versus the shipped metadata grant table and durable journal | **Small amendment** | ADR scope reconciliation now requires matching the promised guarantee instead of the feature name and distinguishing implementation gaps from explicit decision revisions. It does not decide which design is right. | | Stale 0008/0009/202/302/392 prose, index/body conflicts and 688/689 status | Already covered | ADR contradiction repair covers header, current prose, tables, checklists, index, README and tracking issue; placement follows the repository convention. | | Persistence mechanics and 27 ordering cases without decision rationale/rejected alternatives | Already covered | ADR template requires the binding constraint, alternatives and reasons; method's decision artifact also includes rejected options. Implementation instructions and reported tests are not newly relabeled as decision history. | | PR715 already addressed replay documentation; avoid filing it again | Already covered | ADR's existing issue/open-PR comparison checks the exact changed sections, not document overlap. No Nessa issue action is taken. | | Repeat-audit baseline/delta and outcome separation | Coverage practice; no additional skill rule | Pin historical revisions and report new/still-open/reconciled findings in this ledger under existing evidence-class rules. A publication failure is not proof inspection never completed. | | Reported publication failures and disabled ADR automation | Reported operational outcome only | No independent automation-state verification, schedule change or publication retry. Rust research state is outside this patch. | ### Recovered-report coverage ledger These are historical findings at the stated revisions, not claims that the defects remain in current Nessa. Repeated themes are counted once as transferable guidance. | Report message | Historical Nessa snapshot | Recovered coverage and disposition | | --- | --- | --- | | October9 · `2a086b87-e13b-43af-a099-4a2f577bcd82` | `4d1b7278cfe633a6c38094f0bcfb45d4d5043af0` | Reported 36 records:23 done/13 todo;326/344 moved done,252 accepted with implementation separately tracked. 0008,202/302,392,501 and persistence-rationale findings map to existing owners; no duplicate replay-doc work. | | October10 · `2d3f1bcd-f54a-4d96-b836-3caa1a19e0b9` | `88f34e4dabdeca46486dfbd5294e0a2a00a0a5fa` |501 membership,715 stale replay index and720 unchecked grants slice are already covered. The proposed-versus-shipped semantic-contract distinction supports the sole amendment; peer738 and persistence rationale remain historical case evidence. | | October11 · `e4ad69af-9798-4d6f-a666-3a3dbb8aad70` | `bae7a073b597285823b92f037d7079cf4522a716` | Reported 38 records:23 done/13 todo/2 root;688/689 still under review after739,744 pairing shipped while748 outbound was not yet merged at this snapshot. Existing lifecycle/slice/revision rules cover these distinctions. | | October12 · `a452f573-d4e0-4663-a720-3970e6313f15` | `07799e6405812a52297c02bac39525ec0315568e` | Reported37 further commits and38 records; grant/artifact/lease work advanced while checklists lagged;392,501 and rationale gaps persisted. Already-covered themes reinforce the narrow clarification. Reported ADR automation disabling is separate from audit completion and Rust research. | Provenance: recovered messages belong to conversation `6aba0796-656c-83e8-a735-49b9ed36b026`. The identifiers preserve source attribution without putting private conversation links into reusable skills. **Unavailable attachments:** issue-body ZIP attachments were not read, so exact unpublished drafts, their complete acceptance language and publication outcomes were not independently reconstructed. **October13–16:** no report messages were found by the recovery; these dates are not counted as inaccessible completed reports. There is no basis here to invent additional audit runs or claim a current Nessa audit. ### Public supporting evidence - At the [October12 runtime ADR, sliceG](https://github.com/nessalabs/nessa-agent/blob/07799e6405812a52297c02bac39525ec0315568e/docs/adr/todo/252-runtime-roles-and-execution-leases.md#implementation-plan), the wording names a Cedar grant. The [same-revision Read-grants design](https://github.com/nessalabs/nessa-agent/blob/07799e6405812a52297c02bac39525ec0315568e/docs/design/read-grants.md#what-this-slice-does-not-do) explicitly distinguishes its metadata table/journal from in-stream semantic records and policy-bundle changes. [#720](nessalabs/nessa-agent#720) is the delivered slice. This is evidence to compare contracts, not proof that every mechanism difference is a defect or that a chosen implementation must be reverted. - The [pinned ADR index](https://github.com/nessalabs/nessa-agent/blob/07799e6405812a52297c02bac39525ec0315568e/docs/adr/README.md) and [#715](nessalabs/nessa-agent#715), [#739](nessalabs/nessa-agent#739) support the historical projection/lifecycle examples; those rules already exist. - [#744](nessalabs/nessa-agent#744) merged at the October11 report's exact snapshot,15:43UTC. [#748](nessalabs/nessa-agent#748) merged later at16:37UTC. “Not yet merged” is a snapshot observation, not a current outbound-delivery defect. - [#652](nessalabs/nessa-agent#652) and its [pinned physical-persistence design](https://github.com/nessalabs/nessa-agent/blob/07799e6405812a52297c02bac39525ec0315568e/docs/design/bounded-physical-persistence.md) support the distinction between implementation mechanics/reported tests and a decision's rationale. This draft makes no new current missing-ADR claim. ### Validation and limits - **Run:** repository-wide local Markdown path and heading-anchor validation:182 links pass (fenced template examples excluded). - **Run:** all six declared skill paths, required frontmatter and agent descriptors checked; package/plugin versions both remain `0.6.0`. - **Run:** `git diff --check`; refreshed `origin/wip` remains at the stated base before publication. - **Run:** author diff review and independent source-to-owner triage, followed by independent review of the final diff and this description. No material blockers, duplicate owner or evidence/coverage overclaims found. - **Read-only source checks:** the public PRs and pinned documents linked above resolved; selected historical excerpts were inspected. This does not establish runtime behavior or an exhaustive current audit. - **Unavailable:** original full thread text in this executor and ZIP issue-body attachments. The supplied recovered-message evidence is distinguished from source excerpts inspected here. - **Not run:** runtime/native tests, historical ordering cases, benchmarks, installed-skill behavioral evaluation or production defect reproduction. No CI workflows or standard checked-in skill validator exist in this repository; the documentation checks above were run locally. No `nessa-agent` files, issues, PRs or schedules were changed; the separate #953 task was untouched. Prior denied issue publications were not retried. No native/runtime tests, ordering cases or historical audit checks were rerun. The change teaches a review distinction; it does not assert a runtime-validated result or repair historical Nessa defects.
Requested by Saurav · project thread
Part 1a of slice I (#706) of #252.
Before: an owner could pair a phone (it acts as the owner and reads) or a peer gateway (its own principal, reads only what it is shared). There was no way to say "this machine may run agents for me". Any credential that could reach the gateway as a peer could, if shared with, read.
After:
pairing.create {"enrollee":"environment"}creates a third kind of invitation. It uses the same one-use code, listener and PAKE. Approving it issues a credential that names the samegateway:<key hex>principal a reading peer would, and holdsenvironment.serveand nothing else. A machine paired this way can never read a conversation, and no person, agent or integration can ever holdenvironment.serve. Nothing accepts a connection as an environment yet. That is part 1b, which waits on slice D (#737) because both touch the SSH link and env-serve files.Why a credential and not a config entry
Whether a machine may serve this gateway is a fact about credentials, so the registry is its one authority. It is revoked like every other credential, and slice I's later parts re-check it at connect time and on every grant. A config map would be a second copy that could disagree with the registry.
How
environment.serve.PrincipalKind::may_holdlets only a gateway hold it. A gateway may hold the read and serve actions, and never the conversation authority's.ConsentClass::PeerEnvironment(peer-gateway-environment-serve).ConsentClass::grantis now the one place that decides which grant a class hands out. The intent, the disclosure check and the stored pairing all ask it.credential.manage. They need to hold the proposed grant only when the class delegates their own grant (delegates_owner_grant). No person can holdenvironment.serve, so for an environment invitation that check is skipped.validate_grantsnow takes the principal's kind and asksmay_hold. That one check covers every issuing path (credential.issue, bootstrap, owner recovery) and every open.credential.issueofenvironment.serveto anyone is refused withConflict, and nothing is written.class: "environment". The client's private file uses its own magics (NSEP/NSEA), so existing device and peer files stay byte-for-byte unchanged.environment.serveis allowed only to active members holding the exact grant.pairing.createmaps the new enrollee.conversation.sharerefuses a credential that does not holdconversation.readon this gateway's own resource (share_target_not_paired). Otherwise a share to an environment would record a reader that can never read.PairingEnrolleegainsenvironment, and the Rust and TS types are regenerated.sequenceDiagram participant Owner as Owner surface participant GW as Gateway (pairing runtime, Auth registry) participant Worker as Worker gateway (enrolling client) Owner->>GW: pairing.create {enrollee: "environment"} GW->>GW: owner holds credential.manage (not the serve grant: no person can) GW->>GW: ConsentIntent(class = PeerEnvironment, grant = ConsentClass::grant = environment.serve) GW-->>Owner: code (shown once), class peer-gateway-environment-serve Worker->>GW: Hello / Begin / Confirm (same listener, class bound in the PAKE) Owner->>GW: pairing.approve (exact key) GW->>GW: validate_grants: may_hold(Gateway, environment.serve) GW->>GW: credential gateway:<key hex>, grant environment.serve only, bound to the key GW-->>Worker: Active {credential, receiver, epoch} Owner->>GW: conversation.share {credentialId: the worker's} GW-->>Owner: share_target_not_paired (it holds no conversation.read), nothing granted Note over GW,Worker: Part 1b: the worker dials out and serves leases on this credentialDesign row I1 in
docs/design/auth/peer-gateways.mdlists the tests. These are the new ones:owner_route_creates_an_environment_invitationan_environment_enrollment_issues_the_peer_principal_holding_only_servean_environment_is_paired_but_never_shared_with, which runs a full native-listener enrollmentcedar_allows_serving_only_to_a_member_holding_the_granteach_class_discloses_only_its_own_grantThe member and admin refusal tests now run for every enrollee.
What this does not do
These are later parts of #706:
peer.grant;nessa env enroll(1c);E enforces no tool-policy ceiling. Today the dialing side accepts only a reading enrollment.
Known limit, accepted by the owner on 2026-10-11. The registry records an environment pairing's class only once. If something rewrites both the class and the credential's grant on disk in the same consistent way, open accepts the result. Open still refuses any change to only one of the two. A writer that can change both can already add a stronger credential.
Checks
-D warnings), the node check scripts, prettier, and the nessa-auth, nessa-protocol and nessa-client-core tests are all green. The nessa-server tests are green apart from the two below, and the nessa-local-storage tests apart from the first.main.nessa-local-storageunix::tests::*: also fails onmainhere.managed_runtimes::use_admission_and_release_acknowledgement…("an unwritable use journal admitted a generation").codex::status_cleanup_removes_descendants….CI is the check that counts for these.
pnpm frontend:checkhad two failures: both script tests needjust, which this sandbox does not have.smoke-authpassed.local-auth (windows-latest)passed on one re-run after an unrelated SDK timing test failed once.Scripted gateway checks
Not run. This change adds a pairing class, with no UI, ACP or MCP behaviour, and it is covered by the native-listener enrollment test above.
🤖 Generated with Claude Code
https://claude.ai/code/session_01EL5rzp9FLsixdtkMSbgffp
Generated by Claude Code