Implement secure host interface broker for Agent Machine

[mdheller]

Context

Agent Machine needs a local host-side broker that safely connects user surfaces to the internal Podman-backed workspace.

Surfaces:

• terminal / PTY attach
• browser automation and browser extension/native-messaging bridge
• VS Code or editor integration
• OpenCLAW/OpenClaw and Hermes agent tool surfaces

sourceos-devtools owns the workstation/operator CLI and is the correct home for the local broker implementation behind sourceosctl.

Scope

Add a sourceosctl host-interface or sourceosctl agent-machine interface command group:

sourceosctl agent-machine interface doctor
sourceosctl agent-machine interface grant --kind terminal --workspace <id>
sourceosctl agent-machine interface attach-terminal --workspace <id>
sourceosctl agent-machine interface browser broker --workspace <id>
sourceosctl agent-machine interface editor broker --workspace <id>
sourceosctl agent-machine interface tool run --tool openclaw --workspace <id>
sourceosctl agent-machine interface tool run --tool hermes --workspace <id>
sourceosctl agent-machine interface evidence inspect <path>

Required behavior v0

• Read SecureHostInterfaceProfile and HostInterfaceGrant once schemas land.
• Deny by default when no grant exists.
• Support dry-run for every mutating or attach command.
• Emit interface evidence JSON for every launch/attach/run.
• Terminal attach must be logged separately from agent execution.
• Browser broker must default to isolated browser profile and deny host browser profile sharing.
• Editor broker must allow only explicit repo roots and declared tasks.
• Tool run must resolve OpenCLAW/OpenClaw and Hermes through Agent Registry grants when available.

Security constraints

• Never expose Podman socket broadly to browser/editor processes.
• Never pass host credentials by environment variable unless an explicit Secrets Door grant exists.
• Never mount ~/.ssh, browser profile dirs, keychains, cloud credential dirs, or token stores by default.
• Redact known secret-looking values from transcripts and evidence previews.

Acceptance criteria

• CLI help and stubs or implementation added.
• Unit tests cover deny-by-default, dry-run, and evidence emission.
• README documents secure interface broker design.
• No host secrets or local device-specific paths are committed.

Non-goals

• Do not implement the VS Code extension in this repo.
• Do not implement a browser extension in this repo.
• Do not bypass AgentPlane for governed agent execution.