Truthful Channel Awareness And Provisioning Diagnostics

Boundaries

flowchart LR
  Launch[launch/provision] --> Gate[channel readiness gate]
  Gate -->|Ready| Session[session_start registers session]
  Gate -->|Degraded| Degraded[explicit fabric unavailable state]
  Session --> Capture[hook-context capture]
  Capture --> Trellis[Trellis FabricView]
  Trellis --> Render[hook renderer]
  Render --> Agent[agent-visible context]
  Gate --> Receipt[readiness receipt/probe]
  Receipt --> Explain[explain/doctor output]

Very High Level

Track issues #259 through #262 as one ownership boundary: channel readiness must be confirmed before fabric state is rendered as real, and any failed/omitted side effect must be explainable. First, preserve session-start fail-closed behavior but make launch preflight stop presenting degraded panes as fabric-ready; when readiness degrades, the hook should get an explicit unavailable state rather than a desired channel name. Second, change hook-context capture/rendering so requested scope is not enough to produce a `<channel>` block. A channel block requires a materialized `relay_channels` row, and missing channel state becomes a warning or degraded marker. Third, split local invitable agent inventory from channel presence. Local config can be useful, but it must not render as the channel roster; confirmed channel membership remains under `<members>`/presence. Fourth, extend diagnostics around the provisioning side effect. Trellis already explains the hook-context `FabricView` from `channel-meta`, `members`, `presence`, and `messages`; it should also receive enough host-observed readiness facts or linked receipts for operators to explain why a channel was missing without guessing from logs. This plan is ready because the current logs and code show clear failure points and test seams.

Existing Rules Or ADRs

• AGENTS.md backlog rule is satisfied by issues #259, #260, #261, and #262 as the canonical queue; the generated plan PR is a transient review artifact and should not become durable documentation after implementation.
• The relay-sourced state rule is preserved: no local optimistic `relay_channels` fabrication should be introduced to make hook output look complete.
• The Trellis boundary in docs/trellis-mapping.md is preserved: Trellis explains derived hook output today, while the host/provider owns relay effects and feeds observed facts back in.
• File-size limits should be respected by keeping changes in domain-owned modules: launch/session readiness, fabric_context capture/rendering, and probe/diagnostics.

Rule Tension And Tightening

Possible loosening

• No production rule should be loosened. In particular, do not loosen the rule that kind:39000 materialization, not local intent, is the source of channel existence.
• There is process tension because gh-plan-pr writes docs/plans by design; treat that output as a planning PR artifact to retire rather than a durable repo planning file.

Possible tightening

• Add a repository rule or test expectation that hook `<channel>` blocks require confirmed channel metadata, not just requested scope or environment variables.
• Add a vocabulary rule that local invitable agents and channel-present members are separate concepts in hook output and CLI rendering.
• Require readiness degradation paths to expose a machine-readable reason through doctor/explain/probe before opening a local-only agent pane.

Alternatives Considered

• Optimistically create local channel rows when relay creation times out. Rejected because it reintroduces phantom fabric state and violates the current relay-sourced invariant.
• Let launch keep opening panes and rely only on a warning. This preserves local work but still risks false channel identity unless the hook receives a distinct degraded state.
• Move all channel provisioning decisions into Trellis immediately. Rejected for this fix because provider writes, signing, relay reads, and membership repair are still host-owned effects; a readiness receipt is the smaller correct step.