> 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/phase03-session06-cli-diagnostics-and-recovery-controls/tasks.md). # Task Checklist **Session ID**: `phase03-session06-cli-diagnostics-and-recovery-controls` **Total Tasks**: 24 **Estimated Duration**: 3-4 hours **Created**: 2026-05-29 *** ## Legend * `[x]` = Completed * `[ ]` = Pending * `[P]` = Parallelizable (can run with other \[P] tasks) * `[SNNMM]` = Session reference (NN=phase number, MM=session number) * `TNNN` = Task ID *** ## Progress Summary | Category | Total | Done | Remaining | | -------------- | ------ | ------ | --------- | | Setup | 3 | 3 | 0 | | Foundation | 5 | 5 | 0 | | Implementation | 12 | 12 | 0 | | Testing | 4 | 4 | 0 | | **Total** | **24** | **24** | **0** | *** ## Setup (3 tasks) Initial configuration and environment preparation. ### Cross-package * [x] T001 \[S0306] Verify Session 06 prerequisites, Session 05 completion artifacts, and diagnostics owner rows (`.spec_system/PRD/phase_03/orchestration_gap_matrix.md`) * [x] T002 \[S0306] Create implementation notes and security artifact placeholders (`.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/implementation-notes.md`) * [x] T003 \[S0306] Confirm current CLI, hook, listener, server, and privacy diagnostics baselines (`apps/cli/README_cli.md`) *** ## Foundation (5 tasks) Core structures and base implementations. ### apps/server * [x] T004 \[S0306] \[P] Create compact orchestration diagnostics snapshot helper with counts-only output and no raw manager payload echo (`apps/server/src/lib/orchestrationDiagnostics.ts`) * [x] T005 \[S0306] \[P] Create read-only diagnostics route shell with existing auth, CORS, rate-limit, and compact error behavior preserved at the server boundary (`apps/server/src/routes/diagnostics.ts`) ### apps/cli * [x] T006 \[S0306] \[P] Create CLI orchestration diagnostics helper with loopback-only HTTP calls, bearer auth forwarding, timeout handling, and compact failure mapping (`apps/cli/src/lib/orchestrationDiagnostics.js`) * [x] T007 \[S0306] \[P] Add local stale-listener and malformed-spool inspection/recovery primitives with explicit recovery mode and idempotent file handling (`apps/cli/src/lib/localFiles.js`) ### apps/hooks * [x] T008 \[S0306] \[P] Extend hook diagnostic summary helpers with safe event family, duration, status, count, and sanitized ID mapping (`apps/hooks/src/_lib.js`) *** ## Implementation (12 tasks) Main feature implementation. ### apps/server * [x] T009 \[S0306] Wire diagnostics route into server creation with queue, template, mission graph, and guarded-action managers while preserving existing middleware order (`apps/server/src/server.ts`) * [x] T010 \[S0306] Populate diagnostics response with queue, template, mission graph, guarded-action, server availability, and generated-at metadata using bounded counts and deterministic state labels (`apps/server/src/lib/orchestrationDiagnostics.ts`) ### apps/cli * [x] T011 \[S0306] Update `factionos status` to display compact orchestration posture with explicit loading, unavailable, malformed, and offline states (`apps/cli/src/commands/status.js`) * [x] T012 \[S0306] Update `factionos doctor` to check orchestration diagnostics, listener PIDs, hook logs, spool posture, and server availability with bounded failure copy (`apps/cli/src/commands/doctor.js`) * [x] T013 \[S0306] Add explicit doctor recovery flag handling for stale listener PIDs and malformed spool files with duplicate-trigger prevention while in-flight (`apps/cli/src/commands/doctor.js`) * [x] T014 \[S0306] Document the recovery flag and diagnostics command behavior in CLI help without implying unified erasure (`apps/cli/src/index.js`) ### apps/hooks * [x] T015 \[S0306] Improve hook handler log entries for orchestration-related events with safe summaries and no stdout/stderr drift (`apps/hooks/src/_lib.js`) * [x] T016 \[S0306] Improve listener spool, reconnect, malformed-frame, and server-message diagnostics with counts and sanitized identifiers only (`apps/hooks/src/ws-listener.js`) ### docs * [x] T017 \[S0306] Update CLI README with diagnostics output, server-unavailable behavior, recovery controls, and privacy boundaries (`apps/cli/README_cli.md`) * [x] T018 \[S0306] Update hooks README with safe diagnostics, listener recovery expectations, and quiet-failure guarantees (`apps/hooks/README_hooks.md`) * [x] T019 \[S0306] Update server README with local diagnostics snapshot route, manager-count scope, and auth/privacy inheritance (`apps/server/README_server.md`) * [x] T020 \[S0306] Update API docs with diagnostics route and Phase 03 CLI diagnostics boundary without overstating hosted or remote recovery (`docs/api/README_api.md`) *** ## Testing (4 tasks) Verification and quality assurance. ### apps/server * [x] T021 \[S0306] \[P] Write server diagnostics tests for compact counts, auth inheritance, unavailable/empty states, expired guarded actions, and sensitive-field non-echo (`apps/server/tests/orchestrationDiagnostics.test.ts`) ### apps/cli * [x] T022 \[S0306] \[P] Write CLI diagnostics and recovery tests for auth forwarding, timeout, invalid JSON, missing server, stale listener PIDs, malformed spool, and no raw payload output (`apps/cli/tests/orchestrationDiagnostics.test.js`) ### apps/hooks * [x] T023 \[S0306] \[P] Write hook and listener diagnostics tests for safe summaries, quiet handlers, malformed frames, spool counts, and sensitive text redaction (`apps/hooks/tests/orchestrationDiagnostics.test.js`) ### Cross-package * [x] T024 \[S0306] Run focused CLI/hooks/server tests, server typecheck, ASCII/LF checks, and patch hygiene checks and record results (`.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/implementation-notes.md`) *** ## Completion Checklist Before marking session complete: * [x] All tasks marked `[x]` * [x] Focused tests passing * [x] All touched files ASCII-encoded * [x] implementation-notes.md updated * [x] security-compliance.md updated * [x] Ready for the validate workflow step *** ## Next Steps Run the validate workflow step to verify session completeness. --- # 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/phase03-session06-cli-diagnostics-and-recovery-controls/tasks.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.