Port lease protocol

Source candidate for advisory TCP port leases (maia.port-lease/v1). Maia supplies the tool; agents and Skills decide how to use the ports.

Operations

Exposure is Agent-definition eligibility, not a grant; worker eligibility belongs to S18. Mutations need a commandId, and a retry with the same command and input replays the first receipt.

Record

• owner is { kind: "session", sessionId } or, without sessionId in the request, the calling principal { kind: "principal", principalId }.
• ports holds 1 to 8 unique ports from 1024 to 65535, granted together.
• state is active, released or expired. An ended lease names its endReason: owner_released, session_ended, owner_missing (Node start found no such owner) or ttl_expired.
• revision starts at 1 and advances by one for every recorded change: renew, release, and each automatic ending.
• grantedAt, expiresAt and updatedAt are UTC timestamps; renew moves expiresAt forward by the Node's time to live.

Requests

• port.lease.acquire: commandId, purpose (^[a-z0-9][a-z0-9._-]{0,63}$), optional sessionId, count (1 to 8, default 1) and preferred port.
• port.lease.renew: commandId, leaseId, expectedRevision.
• port.lease.release: commandId, leaseId. Releasing an ended lease succeeds with a new receipt and leaves its state unchanged.
• port.lease.list: limit (1 to 100), optional afterCursor and sessionId. Items are active leases, each with one bind probes entry per port (inUse is true when something listens on it now), plus the Node's range.

Errors

port_pool_exhausted, port_lease_not_found, port_lease_expired and port_lease_conflict (PORT_LEASE_ERROR_CODES). Every object rejects excess properties, and results bind the receipt to the exact lease, command, method and revision.