> 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/sessions/phase19-session07-provider-diagnostics/implementation_summary.md). # Implementation Summary **Session ID**: `phase19-session07-provider-diagnostics` **Package**: null **Completed**: 2026-06-26 **Duration**: 1.5 hours *** ## Overview Completed the cross-cutting provider diagnostics session for Phase 19. The work adds shared provider/setup/runtime diagnostics contracts, a server-owned probe and narrow recovery boundary, CLI readiness output, and a product-facing web Diagnostics tab with capability, setup, runtime, recovery, and setup-task states. *** ## Deliverables ### Files Created | File | Purpose | Lines | | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ----- | | `packages/protocol/src/providerDiagnostics.ts` | Shared diagnostics contracts, parsers, recovery shapes, and blocked payload guards | 1094 | | `packages/protocol/tests/providerDiagnostics.test.ts` | Protocol parser, recovery, compact error, redaction, and blocked payload tests | 227 | | `apps/server/src/managers/diagnosticsManager.ts` | Server diagnostics probes, provider/setup/runtime aggregation, and narrow recovery actions | 1026 | | `apps/server/tests/providerDiagnostics.test.ts` | Server manager and route coverage for readiness, recovery, idempotency, and redaction | 377 | | `apps/cli/src/lib/providerDiagnostics.js` | CLI provider diagnostics formatting helpers | 73 | | `apps/cli/tests/providerDiagnostics.test.js` | CLI loopback, auth, malformed response, timeout, recovery, and redaction tests | 222 | | `apps/web/src/components/orchestration/ProviderCapabilityMatrix.tsx` | Provider readiness matrix for the Diagnostics tab | 68 | | `apps/web/src/components/orchestration/DiagnosticsRecoveryPanel.tsx` | Setup/runtime/recovery panel with loading, error, offline, and duplicate-guard states | 231 | | `apps/web/tests/DiagnosticsRecoveryPanel.test.tsx` | Diagnostics panel render, interaction, redaction, and focus tests | 315 | ### Files Modified | File | Changes | | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `packages/protocol/src/index.ts` | Exported provider diagnostics contracts. | | `apps/server/src/routes/diagnostics.ts` | Added provider-readiness and orchestration-recover routes with aliases, validation, auth inheritance, duplicate guards, and compact errors. | | `apps/server/src/lib/orchestrationDiagnostics.ts` | Added provider/setup counts and recovery availability to compact diagnostics. | | `apps/server/src/managers/orchestrationCommandCenter.ts` | Added deterministic diagnostics-manager refresh helpers. | | `apps/server/src/server.ts` | Injected the diagnostics manager into server construction. | | `apps/cli/src/lib/orchestrationDiagnostics.js` | Reused loopback-only diagnostics fetch plumbing for provider readiness. | | `apps/cli/src/commands/doctor.js` | Added provider/setup readiness, disabled reasons, recovery output, and operator commands. | | `apps/cli/src/commands/status.js` | Added compact provider/setup posture output. | | `apps/web/src/lib/orchestrationApi.ts` | Added provider diagnostics fetch, recovery POST, setup task helper, and error mapping. | | `apps/web/src/lib/commandCenterUi.ts` | Added diagnostics summary, provider matrix, setup/runtime/recovery view helpers, and blocked payload filtering. | | `apps/web/src/components/orchestration/CommandCenterPanes.tsx` | Replaced the generic Diagnostics tab with the diagnostics recovery panel. | | `apps/web/src/components/orchestration/OrchestrationHeader.tsx` | Added compact provider/setup readiness summary. | | `apps/web/src/components/orchestration/OrchestrationShell.tsx` | Added diagnostics fetch, refresh, recovery, setup-task, and stale-state handling. | | `apps/web/src/components/orchestration/OrchestrationTabs.tsx` | Threaded diagnostics state and callbacks into the shell panes. | | `apps/web/src/components/orchestration/OrchestrationDrawer.tsx` | Reset stale selected records on re-entry. | | `apps/web/src/components/orchestration/index.ts` | Exported diagnostics components. | | `apps/web/tests/OrchestrationPanel.test.tsx` | Added Diagnostics tab integration, header summary, focus, and stale-state coverage. | | `apps/web/tests/commandCenterStore.test.ts` | Added provider diagnostics mutation-key coverage. | | `apps/web/tests/commandCenterUi.test.ts` | Added provider diagnostics UI helper and redaction coverage. | | `apps/web/tests/orchestrationApi.test.ts` | Added provider diagnostics API helper and duplicate guard coverage. | | `docs/api/README_api.md` | Documented provider-readiness and orchestration-recover APIs. | | `docs/api/event-api-hook-contracts.md` | Documented provider diagnostic updates, recovery event boundaries, and blocked payload categories. | | `apps/server/README_server.md` | Documented diagnostics manager policy and safe recovery limits. | | `apps/cli/README_cli.md` | Documented provider readiness output and operator recovery commands. | | `apps/web/README_web.md` | Documented the Diagnostics tab, capability matrix, setup task action, and redaction boundary. | *** ## Technical Decisions 1. **Protocol-first diagnostics**: Provider/setup/runtime and recovery shapes live in `packages/protocol` so server, CLI, and web clients share one validation boundary. 2. **Server-owned recovery limit**: Automatic recovery only removes stale listener PID files and malformed spool entries; provider setup, environment edits, IDE work, hosted work, and service startup remain exact operator commands. 3. **Redacted readiness output**: Snapshots report provider labels, counts, env variable names, docs paths, and bounded command labels without raw env values, provider payloads, absolute paths, command bodies, logs, prompts, transcripts, or file contents. 4. **Product-facing diagnostics UI**: The web surface renders normalized readiness rows, status labels, and action controls rather than raw diagnostics dumps. *** ## Test Results | Metric | Value | | -------- | -------------------------------------------------------------------- | | Tests | 2784 | | Passed | 2783 | | Skipped | 1 | | Coverage | N/A - coverage was not emitted by the configured validation commands | Focused provider diagnostics and orchestration tests passed across 12 files and 107 tests. Validation also passed protocol/server/web typecheck, lint, format check, diff whitespace, ASCII/LF validation, and `npm run security:secrets`. *** ## Lessons Learned 1. Env-derived model labels must be converted to generic configured-model labels before leaving the server diagnostics boundary. 2. Duplicate recovery requests should return the compact `duplicate_trigger` error envelope so CLI and web clients classify conflicts consistently. 3. Diagnostics stay easier to audit when snapshots, command-center records, CLI output, and UI rows each have separate redaction checks. *** ## Future Considerations Items for future sessions: 1. Session 08 file and Git execution should consume provider readiness as capability context without enabling external transfer or hidden executor behavior. 2. Later executor families should keep unsupported repairs as exact operator commands until each family has threat, permission, audit, output cap, tests, and docs coverage. 3. Continue using protocol parser fixtures to prevent CLI, server, and web diagnostic vocabulary drift. *** ## Session Statistics * **Tasks**: 22 completed * **Files Created**: 9 application/test deliverables plus 6 session reports * **Files Modified**: 26 implementation/documentation files before updateprd bookkeeping * **Tests Added**: 107 focused provider diagnostics and orchestration tests * **Blockers**: 0 resolved --- # 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/sessions/phase19-session07-provider-diagnostics/implementation_summary.md?ask=&goal= ``` `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.