> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/phases/phase_19/session_07_provider_diagnostics.md).

# Session 07: Provider Diagnostics

**Session ID**: `phase19-session07-provider-diagnostics` **Packages**: apps/server, apps/cli, apps/web **Status**: Not Started **Estimated Tasks**: \~12-25 **Estimated Duration**: 2-4 hours

***

## Objective

Surface provider, model, IDE, setup, and runtime readiness as actionable orchestration capability.

***

## Scope

### In Scope (MVP)

* Probes for Claude Code, OpenCode, Cursor, Bedrock, Vertex, hooks, model discovery, permission mode, plan mode, fork/handoff support, IDE/open-file readiness, setup docs, package manager, commands, env examples, scan roots, and running services
* Diagnostics for server connection, listener PID health, spool health, queue capacity, template availability, graph degradation, guarded-action expiry, provider readiness, and isolation posture
* Recovery actions for server-owned safe repairs and exact CLI commands for repairs that must remain operator-run
* Redacted env reporting and disabled reason rendering

### Out of Scope

* Implementing missing providers or hosted credentials
* Enabling external transfer by default

***

## Prerequisites

* [ ] Sessions 01 through 03 complete
* [ ] Existing CLI doctor, hook install, provider, and setup docs inspected

***

## Deliverables

1. Diagnostics manager and provider/setup capability snapshot
2. Header capability matrix and diagnostics recovery panel
3. CLI or server recovery path integration where already supported
4. Tests for probe normalization, redaction, recovery guards, and disabled reasons

***

## Source Coverage And Evidence

Source coverage:

* Session Split Plan Session 07: Provider Diagnostics
* Implementation Targets 14, 19, and 20 for provider/model/IDE readiness, app setup, diagnostics, listener/spool health, and recovery
* Balls-To-The-Wall Track B `diagnosticsManager` routes
* Execution Family Order item 2 for provider/model/hook/listener diagnostics

Key EXAMPLES links:

* [Provider support guide](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md#L147-L158)
* [Model handling guide](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md#L160-L220)
* [Provider/model routes](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L61-L116)
* [App setup skill](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/app-setup/SKILL.md#L1-L15)
* [Troubleshooting guide](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/references/troubleshooting.md#L23-L260)
* [Spawn listeners](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/spawn-listeners.sh#L1-L46)

***

## Success Criteria

* [ ] The panel explains why provider, hook, IDE, setup, or runtime capability is disabled
* [ ] Recovery actions are either tested safe repairs or exact operator commands
* [ ] Secret values never return to the browser
* [ ] Setup readiness can create or link a "needs setup" task source


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/phases/phase_19/session_07_provider_diagnostics.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.