Brief 1b: PermissionGate sole enforcer + graded 2D scope envelope

[jlunder00]

Summary

Implements brief 1b (with 1c's distance-query consolidation folded in): PermissionGate becomes the sole scope enforcer with a graded, config-driven 2D envelope, per config-namespace-decision-2026-07-04.md and the design review (§5.1, §5.4, §4.5).

⚠️ MATCHED PAIR — must merge together with tether-premium#feature/brief-1b-scope-grants-consolidation. This PR deletes db.pg_queries.nodes.get_node_hop_distance; the premium PR updates scope_grants.make_hop_distance_fn to call the replacement. Merging this alone will break premium's scope-gating import.

1. interactive_agent_layer/envelope.py (new)

ScopeEnvelope frozen dataclass (radius, m_max, decay) with .m_allowed(d) graded-detail formula (None beyond radius, else max(1, m_max - decay*d)). load_permission_envelope() / load_injection_envelope() read the new scope.* config namespace with per-scenario partial-merge. validate_injection_subset() enforces injection ⊆ permission at load time (full per-distance loop — clamped-linear curves can cross mid-range, not just at endpoints), raising ScopeConfigError. Also rejects a configured permission.radius beyond MAX_HOP_DISTANCE_BOUND (20) — the distance query would never honor a larger radius.

2. config/app_config.yaml

New top-level scope: {permission, injection, scenarios} block, inert defaults reproducing today's behavior exactly. agent_layer.permission_timeout_seconds 60 → 120 (one truth with config.py's fallback).

3. Gate graded check

PermissionGate now takes a ScopeEnvelope instead of a raw scope_radius: int. read_context scope check: ask iff d > envelope.radius OR requested_M > envelope.m_allowed(d) (M arg, default 4). Fixes DD 3.2 gap: the scope-read path previously had no grant check/insert at all — both paths now check/insert grants uniformly.

4. Distance-query consolidation (full, no shim — Jason's call)

get_node_hop_distance (unbounded LCA-walk) is deleted. get_node_tree_distance (bounded BFS) moves from node_memory.py to nodes.py, generalized to multi-root (from_ids: list[str], min-distance-wins — DD §5.8's multi-root org-accounts model).

5. Unified _await_user_decision(kind, target, on_timeout)

Replaces two near-duplicate implementations. Reads → deny-and-continue on timeout; writes (user_section_edit/destructive) → raise PermissionTimeoutError → session_timeout (unchanged behavior). reason_from_bot plumbed from an optional tool-call reason arg on both paths (previously hardcoded None).

6. Deletions/renames

get_scope_radius() deleted (replaced by load_permission_envelope()). Session-options scope_radius: int|None → optional permission_envelope override — shipped as a plain dict, not a ScopeEnvelope instance, since ScopeEnvelope isn't JSON-serializable and session.options feeds the pool's options_hash via json.dumps. scope_mode param deleted (A8 — never branched on anything). auto_approve_user_actions untouched (Phase 4d).

7. Event schema (for brief 1e, frontend)

permission_request  {type, session_id, request_id, kind, target, reason_from_bot}
permission_resolved {type, request_id, resolution: approved|denied|timeout}   # NEW
session_timeout      {type, session_id, reason, request_id}                   # unchanged

permission_resolved is now emitted on every terminal resolution (approved/denied/timeout) on both the scope-read and user_action paths — previously emitted on neither.

Test plan

• tests/interactive_agent_layer/ — 226 passed (envelope: 21, permissions: 21, scope_gating: 26, session: 29, config: 3, plus unrelated suites unchanged)
• tests/db/test_node_tree_distance.py (new, replaces deleted test_node_hop_distance.py) — 7 passed
• tests/mcp/test_read_context_enforcement.py — patch target updated for the nodes.py move, 13 passed
• Full offline suite: 805 passed, 32 skipped (skips are DB-integration tests requiring live Postgres)
• Self-reviewed via pr-review-toolkit:code-reviewer