> 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/implementation-notes.md). # Implementation Notes **Session ID**: `phase03-session06-cli-diagnostics-and-recovery-controls` **Package**: Cross-cutting (`apps/cli`, `apps/hooks`, `apps/server`) **Started**: 2026-05-29 14:06 **Last Updated**: 2026-05-29 14:21 *** ## Session Progress | Metric | Value | | ------------------- | ------- | | Tasks Completed | 24 / 24 | | Estimated Remaining | 0 hours | | Blockers | 0 | *** ### Task T024 - Run focused verification **Started**: 2026-05-29 14:20 **Completed**: 2026-05-29 14:21 **Duration**: 1 minute **Notes**: * Formatted touched source, tests, and docs with Biome; spec artifacts are ignored by the project Biome configuration. * Ran focused server, CLI, and hook/listener tests: 8 files passed, 30 tests passed. * Ran server typecheck successfully. * Ran focused Biome lint successfully. * Ran ASCII, LF, and `git diff --check` patch hygiene checks successfully. **Files Changed**: * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/tasks.md` - marked T024 complete and updated progress summary. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/implementation-notes.md` - recorded verification results. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/security-compliance.md` - updated final security verification status. *** ### Task T023 - Write hook and listener diagnostics tests **Started**: 2026-05-29 14:19 **Completed**: 2026-05-29 14:20 **Duration**: 1 minute **Notes**: * Added hook/listener tests for safe summary helpers, malformed spool handling, spool count logs, quiet handler behavior, POST diagnostic summaries, and sensitive-text redaction. **Files Changed**: * `apps/hooks/tests/orchestrationDiagnostics.test.js` - added focused hook/listener diagnostics coverage. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/tasks.md` - marked T023 complete and updated progress summary. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/implementation-notes.md` - recorded implementation details. *** ### Task T022 - Write CLI diagnostics and recovery tests **Started**: 2026-05-29 14:18 **Completed**: 2026-05-29 14:19 **Duration**: 1 minute **Notes**: * Added CLI helper tests for auth forwarding, invalid JSON, timeout, missing server, non-loopback rejection, response-field allowlisting, local diagnostics, explicit recovery, and recovery idempotency. * Updated the existing CLI runtime fake server with the diagnostics route so status and doctor fixtures remain representative. **Files Changed**: * `apps/cli/tests/orchestrationDiagnostics.test.js` - added focused CLI diagnostics and recovery coverage. * `apps/cli/tests/cliRuntime.test.js` - added fake diagnostics route fixture. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/tasks.md` - marked T022 complete and updated progress summary. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/implementation-notes.md` - recorded implementation details. *** ### Task T021 - Write server diagnostics tests **Started**: 2026-05-29 14:17 **Completed**: 2026-05-29 14:18 **Duration**: 1 minute **Notes**: * Added server tests for compact diagnostics counts, empty mission graph state, expired guarded actions, bearer auth inheritance, and sensitive-field non-echo. **Files Changed**: * `apps/server/tests/orchestrationDiagnostics.test.ts` - added focused diagnostics route coverage. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/tasks.md` - marked T021 complete and updated progress summary. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/implementation-notes.md` - recorded implementation details. *** ### Task T020 - Update API docs **Started**: 2026-05-29 14:16 **Completed**: 2026-05-29 14:17 **Duration**: 1 minute **Notes**: * Added `/diagnostics/orchestration` to the stable API reference. * Documented the Phase 03 CLI diagnostics and narrow recovery boundary without claiming hosted, remote, or unified erasure behavior. **Files Changed**: * `docs/api/README_api.md` - documented the local orchestration diagnostics route and CLI diagnostics boundary. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/tasks.md` - marked T020 complete and updated progress summary. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/implementation-notes.md` - recorded implementation details. *** ### Task T019 - Update server README **Started**: 2026-05-29 14:16 **Completed**: 2026-05-29 14:16 **Duration**: 1 minute **Notes**: * Documented the local diagnostics route, count-only manager scope, inherited auth/privacy middleware, and no-execution/no-recovery server boundary. **Files Changed**: * `apps/server/README_server.md` - documented `/diagnostics/orchestration`. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/tasks.md` - marked T019 complete and updated progress summary. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/implementation-notes.md` - recorded implementation details. *** ### Task T018 - Update hooks README **Started**: 2026-05-29 14:15 **Completed**: 2026-05-29 14:16 **Duration**: 1 minute **Notes**: * Documented safe hook/listener diagnostics, listener spool expectations, explicit CLI recovery limits, and quiet-failure guarantees. **Files Changed**: * `apps/hooks/README_hooks.md` - documented hook/listener diagnostics and recovery boundaries. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/tasks.md` - marked T018 complete and updated progress summary. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/implementation-notes.md` - recorded implementation details. *** ### Task T017 - Update CLI README **Started**: 2026-05-29 14:15 **Completed**: 2026-05-29 14:15 **Duration**: 1 minute **Notes**: * Documented orchestration status/doctor output, server-unavailable labels, hook/listener/spool posture, and the explicit recovery flag. * Preserved privacy boundaries and narrow recovery wording. **Files Changed**: * `apps/cli/README_cli.md` - documented CLI diagnostics and recovery behavior. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/tasks.md` - marked T017 complete and updated progress summary. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/implementation-notes.md` - recorded implementation details. *** ### Task T016 - Improve listener diagnostics **Started**: 2026-05-29 14:14 **Completed**: 2026-05-29 14:15 **Duration**: 1 minute **Notes**: * Added safe orchestration summaries to listener log entries. * Listener spool, reconnect, malformed frame, server-message, and shutdown diagnostics now report statuses, counts, durations, and sanitized IDs rather than raw spool payloads or frame contents. * WebSocket error logs record message length instead of raw error text. **Files Changed**: * `apps/hooks/src/ws-listener.js` - enriched listener JSON-line diagnostics with safe summaries and bounded fields. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/tasks.md` - marked T016 complete and updated progress summary. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/implementation-notes.md` - recorded implementation details. **BQC Fixes**: * Resource cleanup: listener timer and PID cleanup behavior remains unchanged while diagnostics were added (`apps/hooks/src/ws-listener.js`). * Error information boundaries: malformed frames and WebSocket errors record counts, bytes, statuses, and message lengths only (`apps/hooks/src/ws-listener.js`). *** ### Task T015 - Improve hook handler diagnostics **Started**: 2026-05-29 14:14 **Completed**: 2026-05-29 14:14 **Duration**: 1 minute **Notes**: * Added safe orchestration summaries to hook log lines and POST result logs. * POST diagnostics now include event family, event type, status, duration, and sanitized identifiers without changing stdout/stderr behavior. * ID-like log fields are sanitized before being written. **Files Changed**: * `apps/hooks/src/_lib.js` - enriched hook log summaries and POST success/failure diagnostics. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/tasks.md` - marked T015 complete and updated progress summary. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/implementation-notes.md` - recorded implementation details. **BQC Fixes**: * Error information boundaries: hook diagnostics now include safe summaries and sanitize identifier-like fields before JSON-line logging (`apps/hooks/src/_lib.js`). * Failure path completeness: POST failures continue to spool locally and now log compact status and duration metadata (`apps/hooks/src/_lib.js`). *** ### Task T014 - Document recovery flag in CLI help **Started**: 2026-05-29 14:13 **Completed**: 2026-05-29 14:14 **Duration**: 1 minute **Notes**: * Updated command help to mention orchestration diagnostics in `doctor`. * Added the explicit recovery example with wording limited to stale listener PIDs and malformed spool entries. **Files Changed**: * `apps/cli/src/index.js` - updated help text and examples. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/tasks.md` - marked T014 complete and updated progress summary. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/implementation-notes.md` - recorded implementation details. *** ### Task T013 - Add explicit doctor recovery flag **Started**: 2026-05-29 14:13 **Completed**: 2026-05-29 14:13 **Duration**: 1 minute **Notes**: * Added `factionos doctor --recover-orchestration` and `--recover-diagnostics` handling. * Recovery is protected by a local lock and removes only stale listener PID files and malformed spool JSON entries. * Recovery reports sanitized counts and remains idempotent when repeated. **Files Changed**: * `apps/cli/src/commands/doctor.js` - added explicit recovery flag, lock handling, and bounded recovery reporting. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/tasks.md` - marked T013 complete and updated progress summary. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/implementation-notes.md` - recorded implementation details. **BQC Fixes**: * Duplicate action prevention: recovery acquires `diagnostics-recovery.lock` before deleting approved diagnostic artifacts (`apps/cli/src/commands/doctor.js`). * Trust boundary enforcement: recovery stays confined to stale listener PID files and malformed spool JSON entries under the configured FactionOS home (`apps/cli/src/commands/doctor.js`). *** ### Task T012 - Update doctor diagnostics **Started**: 2026-05-29 14:12 **Completed**: 2026-05-29 14:13 **Duration**: 1 minute **Notes**: * Added orchestration diagnostics route checks to `factionos doctor`. * Added hook-log posture, spool readability, listener PID, and recovery-available reporting with bounded failure hints. * Missing server and unavailable diagnostics route states are reported without printing raw responses. **Files Changed**: * `apps/cli/src/commands/doctor.js` - wired orchestration, hook, spool, listener, and server diagnostics into doctor. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/tasks.md` - marked T012 complete and updated progress summary. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/implementation-notes.md` - recorded implementation details. **BQC Fixes**: * Failure path completeness: doctor reports server, route, hook-log, spool, and listener failures with actionable bounded hints (`apps/cli/src/commands/doctor.js`). * Error information boundaries: doctor prints compact diagnostics labels and counts rather than raw server responses or spool payloads (`apps/cli/src/commands/doctor.js`). *** ### Task T011 - Update status orchestration posture **Started**: 2026-05-29 14:12 **Completed**: 2026-05-29 14:12 **Duration**: 1 minute **Notes**: * Added server orchestration diagnostics to `factionos status` with compact queue, template, mission graph, and guarded-action summaries. * Added explicit offline, unavailable, timeout, auth-required, route-missing, and malformed diagnostics labels. * Added local hook, listener, and spool posture summaries without printing raw local state contents. **Files Changed**: * `apps/cli/src/commands/status.js` - wired orchestration server and local diagnostics into status output. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/tasks.md` - marked T011 complete and updated progress summary. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/implementation-notes.md` - recorded implementation details. **BQC Fixes**: * Failure path completeness: server diagnostics failures degrade to explicit status labels instead of crashing status output (`apps/cli/src/commands/status.js`). * Error information boundaries: status displays compact counts and sanitized reason labels only (`apps/cli/src/commands/status.js`). *** ### Task T010 - Populate diagnostics response **Started**: 2026-05-29 14:11 **Completed**: 2026-05-29 14:12 **Duration**: 1 minute **Notes**: * Confirmed the server helper returns queue counts, template availability, mission graph counts, guarded-action counts, server availability, and generated-at metadata. * Status labels are deterministic and counts are bounded before being returned. **Files Changed**: * `apps/server/src/lib/orchestrationDiagnostics.ts` - populated the compact response model. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/tasks.md` - marked T010 complete and updated progress summary. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/implementation-notes.md` - recorded implementation details. **BQC Fixes**: * Contract alignment: the route receives a fixed snapshot shape with explicit status labels and count maps (`apps/server/src/lib/orchestrationDiagnostics.ts`). * Error information boundaries: no raw manager entries, prompts, paths, proposals, queue titles, or terminal output are represented in the snapshot (`apps/server/src/lib/orchestrationDiagnostics.ts`). *** ### Task T009 - Wire diagnostics route into server creation **Started**: 2026-05-29 14:11 **Completed**: 2026-05-29 14:11 **Duration**: 1 minute **Notes**: * Mounted the diagnostics route after existing local middleware and current orchestration/guarded-action routes, before the unsupported-route catch-all. * Passed queue, template, mission graph, and guarded-action manager instances into the diagnostics route. **Files Changed**: * `apps/server/src/server.ts` - imported and mounted the diagnostics route with manager dependencies. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/tasks.md` - marked T009 complete and updated progress summary. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/implementation-notes.md` - recorded implementation details. *** ### Task T008 - Extend hook diagnostic summary helpers **Started**: 2026-05-29 14:10 **Completed**: 2026-05-29 14:11 **Duration**: 1 minute **Notes**: * Added hook-side orchestration diagnostic summary helpers for safe event families, statuses, durations, counts, and identifiers. * Helpers sanitize IDs and bound numeric values so later hook and listener logs can add orchestration context without raw payloads. **Files Changed**: * `apps/hooks/src/_lib.js` - added safe orchestration diagnostic summary helpers. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/tasks.md` - marked T008 complete and updated progress summary. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/implementation-notes.md` - recorded implementation details. **BQC Fixes**: * Error information boundaries: diagnostic summaries reduce event details to allowlisted families, status labels, bounded counts, durations, and sanitized IDs (`apps/hooks/src/_lib.js`). *** ### Task T007 - Add local diagnostic recovery primitives **Started**: 2026-05-29 14:10 **Completed**: 2026-05-29 14:10 **Duration**: 1 minute **Notes**: * Added malformed spool file inspection that reads only `.json` entries under the configured spool directory. * Added recovery inspection for stale listener PID files and malformed spool entries. * Added explicit recovery execution that removes only those two approved diagnostic artifact categories and is safe to repeat. **Files Changed**: * `apps/cli/src/lib/localFiles.js` - added stale listener and malformed spool recovery primitives. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/tasks.md` - marked T007 complete and updated progress summary. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/implementation-notes.md` - recorded implementation details. **BQC Fixes**: * Duplicate action prevention: recovery helpers require explicit caller intent before deleting any diagnostic artifacts (`apps/cli/src/lib/localFiles.js`). * Error information boundaries: recovery summaries expose file categories and counts instead of raw malformed spool contents (`apps/cli/src/lib/localFiles.js`). *** ### Task T006 - Create CLI orchestration diagnostics helper **Started**: 2026-05-29 14:08 **Completed**: 2026-05-29 14:10 **Duration**: 2 minutes **Notes**: * Added loopback-only server diagnostics fetching with bearer auth forwarding and bounded timeout handling. * Added compact response normalization that keeps only allowlisted counts and status labels from the server response. * Added local listener, spool, and hook-log posture summaries for CLI display and doctor checks. **Files Changed**: * `apps/cli/src/lib/orchestrationDiagnostics.js` - created CLI diagnostics fetch, local summary, recovery-availability, and display sanitization helpers. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/tasks.md` - marked T006 complete and updated progress summary. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/implementation-notes.md` - recorded implementation details. **BQC Fixes**: * Trust boundary enforcement: server responses are normalized through an allowlist before any caller can display them (`apps/cli/src/lib/orchestrationDiagnostics.js`). * Error information boundaries: request failures report compact reason labels and sanitized messages only (`apps/cli/src/lib/orchestrationDiagnostics.js`). *** ### Task T005 - Create diagnostics route shell **Started**: 2026-05-29 14:08 **Completed**: 2026-05-29 14:08 **Duration**: 1 minute **Notes**: * Added a read-only `/diagnostics/orchestration` route module. * The route returns only the compact snapshot and maps unexpected failures to a stable `diagnostics_unavailable` envelope without raw exception details. **Files Changed**: * `apps/server/src/routes/diagnostics.ts` - created diagnostics route shell. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/tasks.md` - marked T005 complete and updated progress summary. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/implementation-notes.md` - recorded implementation details. *** ### Task T004 - Create server diagnostics snapshot helper **Started**: 2026-05-29 14:07 **Completed**: 2026-05-29 14:08 **Duration**: 1 minute **Notes**: * Added a compact server-side orchestration diagnostics snapshot builder. * The helper reports server manager availability, generated metadata, template totals, and bounded counts for queue, mission graph, and guarded actions only. * Expired guarded actions are reconciled before counts are read so diagnostics do not leave stale pending posture. **Files Changed**: * `apps/server/src/lib/orchestrationDiagnostics.ts` - created counts-only snapshot helper and deterministic status labels. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/tasks.md` - marked T004 complete and updated progress summary. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/implementation-notes.md` - recorded implementation details. *** ### Task T003 - Confirm diagnostics baselines **Started**: 2026-05-29 14:06 **Completed**: 2026-05-29 14:07 **Duration**: 1 minute **Notes**: * Reviewed current CLI status/doctor behavior, local file helpers, hook shared logging helpers, listener spool handling, and server route/middleware wiring. * Confirmed existing docs already define local-first diagnostics, quiet hook behavior, and privacy boundaries but do not yet ship Phase 03 orchestration diagnostics or explicit recovery controls. **Files Changed**: * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/tasks.md` - marked T003 complete and updated progress summary. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/implementation-notes.md` - recorded baseline review. *** ### Task T002 - Create implementation and security artifacts **Started**: 2026-05-29 14:06 **Completed**: 2026-05-29 14:06 **Duration**: 1 minute **Notes**: * Created the session implementation notes with environment and progress tracking. * Created the session security/compliance placeholder with privacy and recovery boundaries for the diagnostics work. **Files Changed**: * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/implementation-notes.md` - initialized task log and progress summary. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/security-compliance.md` - initialized session security and privacy boundary notes. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/tasks.md` - marked T002 complete and updated progress summary. *** ### Task T001 - Verify prerequisites and owner rows **Started**: 2026-05-29 14:04 **Completed**: 2026-05-29 14:06 **Duration**: 2 minutes **Notes**: * Ran the spec analysis script and confirmed the active session is `phase03-session06-cli-diagnostics-and-recovery-controls`. * Ran environment and required tool prerequisite checks; both passed. * Confirmed Session 05 validation and implementation summary report PASS/complete artifacts. * Reviewed the Phase 03 gap matrix rows assigning CLI diagnostics, hook/listener diagnostics, and bounded recovery to Session 06. **Files Changed**: * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/tasks.md` - marked T001 complete and updated progress summary. * `.spec_system/specs/phase03-session06-cli-diagnostics-and-recovery-controls/implementation-notes.md` - created the session progress log and recorded prerequisite verification. *** ## Task Log ### 2026-05-29 - Session Start **Environment verified**: * [x] Prerequisites confirmed * [x] Tools available * [x] Directory structure ready * [x] Cross-package session scope 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/phase03-session06-cli-diagnostics-and-recovery-controls/implementation-notes.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.