fix(inbox): an unplaced inbox follows its registered agent's group
Problem
relaygate placed relaycast:inbox/<name> streams only by streamDefaults prefixes (local-, pit-, slack-). Agent Relay Desktop agents enrol with a device token (keyId device:<uid>, gid from controlPrincipals) and are named by their harness (cursor-…, claude-…, codex-…), so their inboxes matched no prefix and every DM to them was denied at stage mode, reason unknown_stream. Local agents could not DM each other.
Fix
resolveStream order is now: override → registered stream → longest prefix default → registered agent's inbox (only for relaycast:inbox/<name>):
- owner = the agent, gid = the agent's gid
- mode / acl / classify from the new optional policy field
inboxDefaults: [{gid, mode, acl?, classify?}]for that gid; otherwise660, no ACL (same group may message it, no one else) - a name no agent has stays
unknown_stream(deny) - audit reason suffix
:agent-inbox
Explicit overrides and streamDefaults keep precedence. The pit (gid 22) never gets w on a gid-11 inbox unless policy grants it (built-in default has other = 0; inboxDefaults mirroring local- gives 22 only r).
Visibility unchanged: GET /v1/agents still uses operator rules only (resolveStream(..., { agentInboxes: false })), so a derived inbox does not show an agent in the directory. If we want local Desktop agents to list each other too, that's a one-line flip — called out deliberately.
Policy validator: inboxDefaults gids/ACL gids must be defined groups, at most one entry per gid, mode validated as elsewhere. Also: an agent can now read its own inbox (owner digit), which previously failed for these agents the same way.
Docs: docs/contract.md (Resources → DMs; pit deployment section). examples/policy.pit.json declares inboxDefaults for gid 11.
Deployer policy addition
"inboxDefaults": [{"gid": 11, "mode": "660", "acl": [{"gid": 22, "perm": "r"}, {"gid": 44, "perm": "r"}]}]
(mirror whatever ACL your relaycast:inbox/local- rule has). Without it, Desktop agents still DM each other with built-in 660/no ACL. Chart default: separate infra PR.
Tests
test/agent-inbox.test.ts: device-enrolled cursor-x and claude-y DM each other; pit agent can't DM them (also with inboxDefaults mirroring local-: r yes, w no); explicit streamDefaults/overrides win; unregistered name → unknown_stream; only inbox ids derived; directory visibility unchanged; explain reports agent-inbox; validator rules. npm run typecheck + npm test (167) green.
🤖 Generated with Claude Code
![Autofix with [code]smith](https://pr-comments-assets.blacksmith.sh/codesmith/autofix-with-codesmith-dark-3x.png)
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.
Summary by cubic
Desktop agents register with device tokens and are named by their harness (cursor-…, claude-…, codex-…), so no streamDefaults prefix covered their inboxes and every DM to them was denied as unknown_stream. Resolution for an inbox is now override → registered stream → prefix default → the registered agent's inbox, owned by that agent, in its group, with mode/ACL/classify from the new inboxDefaults policy entry (default 660, no ACL); a name no agent has still stays unknown_stream.
- Explicit overrides and
streamDefaultskeep precedence; audit reasons end in:agent-inbox. - A relay-control user's synthetic
ctl:identity holds no token, so it is never a DM recipient through this rule and those names stayunknown_stream. - Directory visibility is unchanged:
GET /v1/agentsstill uses operator rules only, so a derived inbox doesn't list the agent.
Migration
- Operators may add
"inboxDefaults": [{"gid": 11, "mode": "660", "acl": [...]}]mirroring theirrelaycast:inbox/local-rule; without it, desktop agents still DM each other with the built-in660/no ACL.