Spec: maintainer/owner conversational surface — grounding catalog, action catalog, authz matrix, placement, transport

[JSONbored]

Context

Part of the ORB maintainer chat platform epic. Before any backend or UI work, every interpretive question must be closed here, exactly as #6230 did for the contributor side. The contributor-side artifacts to mirror (and diverge from deliberately, with reasons): #6230 (spec), #6517 (read-only grounding contract), #6521 (confirmed action-dispatch), #6303 (SSE audit).

Requirements — every numbered item gets an explicit recorded decision

1. Grounding-tool catalog (read-only). Decide the v1 tool list. Candidate minimum, to confirm/trim/extend: queue snapshot (open PRs + dispositions + holds with reasons), per-PR status (gate verdict, blockers, CI state, decision-record digest), decision-record fetch by digest, ledger-verify status proxy, calibration/fairness summary (accuracy with coverage and interval — never a bare scalar), effective-config resolution (resolved .loopover.yml + settings precedence), audit-event tail per repo, repo-settings snapshot. For each: exact data source (existing service/module), redaction treatment, response token budget.
2. Action catalog. Decide the v1 dispatchable actions and their authz tier. Candidates: per-repo agent pause/resume; dry-run toggle; force re-gate (reuse the feat(queue): wire an admin trigger for agent-regate-pr force re-gates #8958 admin trigger); approval-queue release; human-attributed manual-review release (this would be the missing human-provenance removal path). Explicitly decide: global freeze is display-only in chat (ratchet semantics), yes/no.
3. Authz matrix. Session actor → installation → repo. Which existing helpers gate reads vs dispatches (requireRepoMaintainer / requireSessionRepoAccess / verifyInstallationAdmin), what operators (ADMIN_GITHUB_LOGINS) may additionally do, and what happens for affiliation-tier (data-read) maintainers — read-only chat, no dispatch?
4. Placement. New app.* route vs a chat rail embedded in app.maintainer.tsx/app.owner.tsx — decide, with the mobile/narrow-viewport behavior.
5. Transport. SSE per research: audit streaming/SSE support in loopover's API layer for chat-interface response streaming #6303's findings; confirm it holds for both the hosted Worker path and the self-host container path, or record the split.
6. Model/provider path. Which provider plan executes chat completions (existing AI_PROVIDER chain vs a dedicated chat slot), its budget controls, and its failure behavior (degrade to deterministic tool results, never fabricate).
7. Tenant model. Alignment with Decouple "admin of a GitHub install" from "has a running container" #4927 (admin-of-install ≠ has-a-container): what the chat shows a maintainer whose repo has no running deployment.
8. Parity contract. The same surface against self-host and hosted; name any deliberate divergences.

Deliverables

• Every numbered item above answered in a decision-record comment on this issue.
• The epic's other sub-issues re-checked against the decisions (scope adjustments applied to them before implementation starts).

Expected outcome

Implementation issues in this epic can be executed with zero interpretive latitude.

[linear-code]

JSO-6347

[JSONbored]

Proposed candidate answers from the 2026-07-28 frontend planning pass

Non-binding input for this spec's decision record — the UX-facing items below will be validated in a clickable frontend prototype (synthetic data only, the #5963 pattern) before being recorded as decisions here. Planning detail lives in the comments on #9183/#9184.

Item 4 — Placement (proposed): persistent, collapsible ~380px chat rail mounted in the app-shell root so it survives route navigation; Sheet slide-over on narrow viewports; routed dashboard pages remain primary content (hybrid dashboard-first — the shipped #6504 layout, whose primitives are already in @loopover/ui-kit via #9188). Chat context follows the active repo/route. An expandable full-page conversation view is a candidate later addition, not v1. Rather than embedding in app.maintainer.tsx alone, the rail belongs to the shared app shell so it serves every app.* surface the session may ground on.

Items 4/7/8 adjacent — workspace/domain shape (proposed, cross-epic): one app area with entitlement-gated workspace trees (/maintain/… ORB, /build/… AMS); orb./ams. subdomains as redirects only; single-product sessions render zero chrome from the other product. A both-entitled repo additionally gets the Loop view (#9566). Full mechanics in the #9183 comment.

Additional decisions this spec should record explicitly (surfaced by the planning pass, currently unowned):

1. Conversation persistence. Both shipped chat surfaces are stateless (caller resends full history; no transcript store). A hosted product plausibly wants persistent, device-spanning conversations eventually — decide v1 scope here rather than letting it emerge (a transcript store is a new data surface with tenancy/privacy/retention implications; miner-ui(hosted): GitHub OAuth tenant auth and server-side tenant scoping of every dashboard surface #9196 already names chat transcripts as tenant-scoped state on the AMS side).
2. Workspace naming — user-facing words for the two workspaces (Maintain/Build vs ORB/AMS vs Review/Develop). Affects routes, nav, docs.
3. Suggested-prompt catalog as part of the action catalog (item 2). Each dispatchable action should have at least one seeded prompt reachable in the UI — feature discovery, and a structural guard against the fix(miner-ui): governor pause/resume chat actions are registered and rendered but never dispatched from the chat conversation #8670 registered-but-unreachable class (pairs with the per-action end-to-end path test).
4. Interim deploy topology for the AMS client while it remains a second codebase (miner-ui: implement the hosted-mode flag (#5229's decided follow-up, now unblocked) #9195): shared-shell design now, convergence decision recorded here (detail in the Epic: hosted AMS chat platform — sign up, connect GitHub, converse with your miner #9184 comment).

Item 5 — Transport: nothing new; the planning pass re-confirms #6303's conclusion that the hosted/self-host-parity answer is hono/streamSSE on the protected API (#9191) and that the local miner SSE stack is not liftable.