> 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/phase11-session03-end-to-end-validation-and-integration-fixes/spec.md). # Session Specification **Session ID**: `phase11-session03-end-to-end-validation-and-integration-fixes` **Phase**: 11 - Codex Hardening and Validation **Status**: Not Started **Created**: 2026-05-31 **Package**: Cross-cutting **Package Stack**: JavaScript CLI/hooks, TypeScript protocol/server/web, Node 20+, Vite/React, Playwright, Vitest 4.1.7, Biome 2.4.16 *** ## 1. Session Overview This session validates the Codex CLI integration through the local FactionOS path a user is expected to run: CLI install, Codex hook trust review or source-backed fixture replay, hook event ingest, WebSocket/web cockpit display, CLI status and doctor diagnostics, and uninstall. Phase 10 wired the feature, Phase 11 Session 01 aligned docs and privacy wording, and Phase 11 Session 02 added source-backed automated fixture coverage. Session 03 turns that groundwork into an end-to-end validation record. The session is cross-package by design. It touches `apps/cli` for install/status/doctor/uninstall posture, `apps/hooks` for Codex event emission, `apps/server` for `/event` ingest and lifecycle persistence, `apps/web` for visible cockpit behavior, and `tests/e2e` for fixture-replayed browser validation when live Codex execution is unavailable. Real Codex validation is preferred when the local environment can run Codex and complete `/hooks` trust review; otherwise the fixture replay path must be explicit, source-backed, and documented as an exception. The implementation should fix only integration blockers discovered during validation. It should not broaden Codex capabilities, add plugin packaging, redesign the cockpit, activate hosted services, or change privacy boundaries beyond the minimal fixes required to make the existing first-class local Codex support trustworthy. *** ## 2. Objectives 1. Validate isolated Codex hook install, hook trust or fixture exception, local runtime startup, event ingest, web display, status, doctor, and uninstall behavior. 2. Capture a concise closeout record with commands, evidence, pass/fail results, privacy review, and explicit exceptions for unavailable live steps. 3. Add a reproducible fixture-replayed browser validation path for the Codex lifecycle when live Codex execution cannot be completed. 4. Fix only blocker-level integration defects found during validation, preserving Claude behavior and local-first privacy boundaries. *** ## 3. Prerequisites ### Required Sessions * [x] `phase11-session01-documentation-and-privacy-sync` - provides current user-facing Codex setup, trust, and privacy wording. * [x] `phase11-session02-test-fixture-hardening` - provides redacted source-backed Codex fixtures and focused automated coverage. * [x] `phase10-session01-cli-provider-selection-and-installer-split` - provides `--cli claude|codex|all` routing. * [x] `phase10-session02-codex-hook-install-uninstall-and-diagnostics` - provides Codex install, uninstall, status, and doctor support. * [x] `phase10-session03-server-ingest-codex-lifecycle` - provides server ingest for Codex lifecycle events. * [x] `phase10-session04-web-codex-awareness` - provides Codex web labels, search, filters, replay, and export privacy coverage. ### Required Tools/Knowledge * npm workspace commands and package boundaries from `.spec_system/CONVENTIONS.md`. * Current CLI, hooks, server ingest, web cockpit, and e2e test structure. * Codex `/hooks` trust-review behavior from `apps/hooks/README_hooks.md` and `docs/api/event-api-hook-contracts.md`. * Session 02 fixture limitations and command evidence. * Playwright app desktop/mobile validation flow and browser guard helpers. ### Environment Requirements * Node 20+ and installed npm workspace dependencies. * Default local runtime ports available where possible: server `2468`, web `5193`. * Isolated `FACTIONOS_HOME` and `CODEX_HOME` for validation so real user config is not mutated. * Codex CLI available for the live path, or a documented fixture-replay fallback. * New or changed files must be ASCII-only with Unix LF line endings. *** ## 4. Scope ### In Scope (MVP) * Operators can validate `factionos init --cli codex --faction orc` in an isolated home - confirm managed hooks are written, existing user-owned hooks are preserved, and Claude settings are not mutated. * Operators can validate Codex `/hooks` trust review when a live Codex CLI run is available - otherwise record a source-backed exception and use fixture replay. * The local runtime can start and display Codex-shaped events in the cockpit - verify hero spawn, mission start, Bash, `apply_patch`, MCP, permission request, subagent, mission completion, and degraded event handling. * Diagnostics remain useful and privacy-safe - verify `factionos status --cli codex` and `factionos doctor --cli codex` report labels, counts, and guidance without raw prompts, command bodies, patch bodies, transcript paths, tokens, broad paths, or raw hook payloads. * Uninstall remains surgical - verify `factionos uninstall --cli codex` removes only FactionOS-managed Codex hooks and preserves user-owned hooks. * Validation evidence is captured in a closeout artifact under this session directory. * Integration blocker fixes are limited to the owning CLI, hook, server, or web modules that fail validation. ### Out of Scope (Deferred) * Codex plugin packaging or project-local trusted `.codex/` setup - *Reason: Phase 12 owns packaging decisions.* * New Codex features beyond the integration definition of done - *Reason: this session validates and hardens existing support only.* * Broad UI redesign or new cockpit product surfaces - *Reason: the target is validation and blocker fixes.* * Hosted auth, hosted storage, analytics, public replay hosting, push, remote access, tunnels, production-hosted validation, or external telemetry - *Reason: these remain disabled, unavailable, deferred, or no-claim.* * Real file, git, terminal, Docker, remote, Worker, or hosted executors - *Reason: existing guarded actions remain non-executing by design.* * Full trusted unified erasure - *Reason: current erasure remains scoped and no-claim where not proven.* *** ## 5. Technical Approach ### Architecture Use a validation-first path. Start with an isolated environment and a closeout artifact, then run the same CLI lifecycle a user would run. If live Codex is available, validate `/hooks` trust review and a small prompt that causes Bash and `apply_patch` activity. If live Codex is not available or cannot be automated safely, use the Session 02 source-backed fixtures to replay the lifecycle through the local server and cockpit, and state that limitation explicitly in the closeout record. The browser validation path should reuse the existing Playwright app projects and browser guards. A Codex fixture helper can seed redacted lifecycle events through `/event`, and the app e2e test can verify visible Codex hero, mission, tool, permission, subagent, replay, and privacy behavior on desktop and mobile. Any fixes should happen at the closest owner boundary: CLI/provider posture for install and diagnostics, hooks for payload normalization, server ingest for event mapping, and web helpers/components for display or redaction. ### Design Patterns * Isolated local homes: use temporary `FACTIONOS_HOME` and `CODEX_HOME` to avoid real user config changes. * Source-backed fixture replay: rely on Session 02 fixture shapes when live Codex trust or execution is unavailable. * Boundary-specific redaction: validate CLI, hook, server, web, replay, export, and evidence artifacts separately. * Blocker-only fixes: patch only the owner module responsible for a validation failure. * Browser evidence with guards: use Playwright app projects plus page error, console, request, text-fit, and privacy checks. ### Technology Stack * Node 20+ npm workspaces. * CLI and hooks: JavaScript under `apps/cli` and `apps/hooks`. * Server and web: TypeScript under `apps/server` and `apps/web`. * Shared contracts: TypeScript under `packages/protocol`. * Browser validation: Playwright 1.60.0 app desktop/mobile projects. * Unit/integration validation: Vitest 4.1.7. * Formatting and linting: Biome 2.4.16. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `.spec_system/specs/phase11-session03-end-to-end-validation-and-integration-fixes/codex-e2e-validation-record.md` | Closeout evidence for install, trust or fixture exception, ingest, web display, status, doctor, uninstall, privacy, and blockers. | \~180 | | `tests/e2e/support/codexFixtures.ts` | Redacted Codex lifecycle fixture helper for app browser validation. | \~140 | ### Files to Modify | File | Changes | Est. Lines | | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ---------- | | `tests/e2e/app.e2e.ts` | Add a Codex fixture-replayed cockpit validation path for desktop and mobile app projects. | \~140 | | `.spec_system/specs/phase11-session03-end-to-end-validation-and-integration-fixes/implementation-notes.md` | Record implementation commands, live-vs-fixture decision, blockers, and final verification. | \~160 | | `apps/cli/src/lib/providerPosture.js` | Minimal blocker fix if install/status/doctor/uninstall validation exposes provider posture drift. | \~40 | | `apps/cli/src/installers/codex.js` | Minimal blocker fix if isolated install or uninstall violates backup/user-owned hook behavior. | \~40 | | `apps/hooks/src/_lib.js` | Minimal blocker fix if live or fixture replay exposes unsafe Codex normalization or spool behavior. | \~40 | | `apps/server/src/lib/eventIngest.ts` | Minimal blocker fix if `/event` mapping fails the Codex lifecycle definition of done. | \~50 | | `apps/web/src/lib/heroCli.ts` | Minimal blocker fix if Codex labels or provider display drift from protocol-backed helpers. | \~30 | | `apps/web/src/lib/replayLink.ts` | Minimal blocker fix if browser replay redaction leaks Codex-shaped private fields. | \~30 | | `docs/api/event-api-hook-contracts.md` | Update only if validation records an API-contract exception that belongs in stable docs. | \~30 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Isolated `factionos init --cli codex --faction orc` writes managed Codex hooks and preserves user-owned hooks without touching Claude settings. * [ ] Codex `/hooks` trust review is validated live, or a fixture-replay exception is recorded with source-backed reason and scope. * [ ] Local runtime validation proves Codex hero spawn, mission start, Bash, `apply_patch`, MCP, permission request, subagent, and mission completion behavior. * [ ] Cockpit validation proves Codex labels, mission filters, hero detail, tool usage, replay, and export-adjacent privacy behavior. * [ ] `factionos status --cli codex` and `factionos doctor --cli codex` provide useful compact diagnostics after validation. * [ ] `factionos uninstall --cli codex` removes only FactionOS-managed hooks and preserves user-owned hooks. * [ ] Every unavailable live step has an explicit, source-backed exception in the closeout artifact. * [ ] Any source fixes are limited to integration blockers found during this validation. ### Testing Requirements * [ ] App desktop and mobile Playwright validation passes for the Codex replay path. * [ ] Focused Vitest suites pass for any touched CLI, hooks, server, web, or protocol modules. * [ ] Workspace typecheck passes for packages with typecheck scripts. * [ ] Manual command evidence is recorded for install, status, doctor, and uninstall flows. ### Non-Functional Requirements * [ ] Evidence artifacts contain only labels, counts, safe IDs, command names, booleans, and redacted summaries. * [ ] No raw prompts, patch bodies, command output, terminal output, transcript paths, MCP argument bodies, token-like values, credentials, or broad absolute paths appear in tracked files. * [ ] Claude Code defaults and compatibility behavior remain intact. * [ ] Hosted identity, trusted erasure, production-hosted validation, plugin packaging, real executors, and external telemetry remain no-claim. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] `npm run format:check` passes. * [ ] `npm run lint` passes. * [ ] `git diff --check` passes. *** ## 8. Implementation Notes ### Key Considerations * Prefer a real Codex run only when it can be performed without mutating real user config. Use isolated homes and seed a harmless user-owned hook to prove preservation. * If live `/hooks` trust review cannot be completed, document the exact blocker and use the source-backed fixture replay path. Do not describe fixture replay as live trust validation. * The web validation should test visible behavior and privacy boundaries, not just server responses. * `FACTIONOS_MOCK=false` is preferred for runtime validation so mock heroes do not obscure Codex-specific evidence. * Keep all evidence sanitized. Store pass/fail, command names, counts, safe status labels, and exception reasons only. ### Potential Challenges * Live Codex may be unavailable or interactive: use fixture replay and record the limitation instead of forcing trust bypasses. * Local ports may be occupied: document alternate ports only if the app can still connect to the selected server port. * CLI validation can touch user config if homes are not isolated: mitigate with explicit `FACTIONOS_HOME` and `CODEX_HOME`. * Fixture replay can overclaim live behavior: keep trust and live-execution claims separate from fixture-backed display and ingest evidence. * Blocker fixes can expand scope: require a validation failure before changing source outside e2e or evidence files. ### Relevant Considerations * \[P10-apps/cli+apps/hooks] **Backup-first Codex hook management worked**: install and uninstall validation should preserve user-owned hooks and avoid backup churn. * \[P10-packages/protocol+apps/web] **Codex display labels need one shared source of truth**: browser validation should assert protocol-backed labels rather than local fallback text. * \[P07] **Redaction is boundary-specific**: evidence should validate CLI, hook, server, web, replay, export, and artifact boundaries separately. * \[P03-apps/cli+apps/hooks] **Lifecycle state is local and file-based**: isolated temp homes should cover listener, hook, spool, and provider posture without touching real state. * \[P09-apps/hooks] **Do not forward raw Codex payloads**: patch bodies, terminal output, transcript paths, token-like values, and MCP arguments must remain summarized or redacted. * \[Security] **P06-S07-HOSTED-IDENTITY**: this session does not add hosted identity or account proof. * \[Security] **P06-S07-ERASURE**: uninstall and cleanup are not trusted unified erasure. * \[Security] **P06-S07-HOSTED-VALIDATION**: local browser validation is not production-hosted validation. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Validation commands accidentally mutate real `~/.codex`, `~/.claude`, or `~/.factionos` state. * Fixture replay is mistaken for live Codex `/hooks` trust validation. * Browser or evidence artifacts leak sensitive Codex-shaped fields while proving the integration. * A blocker fix in one package regresses Claude compatibility or broad local-first privacy defaults. *** ## 9. Testing Strategy ### Unit Tests * CLI: focused tests for provider posture, Codex installer, status, doctor, and uninstall when touched. * Hooks: focused tests for Codex normalization, handler runtime, spool fallback, and hook map when touched. * Server: `apps/server/tests/eventIngest.test.ts` when ingest behavior changes. * Web: Codex awareness, replay, export, hero, mission, and tool usage tests when display or redaction changes. ### Integration Tests * Playwright app desktop/mobile validation using `tests/e2e/app.e2e.ts` and `tests/e2e/support/codexFixtures.ts`. * Local server event replay through `/event` using redacted Codex lifecycle payloads. * CLI install/status/doctor/uninstall commands against isolated `FACTIONOS_HOME` and `CODEX_HOME`. ### Manual Testing * `npm --workspace apps/cli link` * `FACTIONOS_HOME= CODEX_HOME= factionos init --cli codex --faction orc` * If Codex is available: run `codex`, review `/hooks`, and perform a small prompt that triggers Bash and `apply_patch`. * If Codex is unavailable: record the exception and run the fixture-replayed Playwright validation. * `FACTIONOS_HOME= CODEX_HOME= factionos status --cli codex` * `FACTIONOS_HOME= CODEX_HOME= factionos doctor --cli codex` * `FACTIONOS_HOME= CODEX_HOME= factionos uninstall --cli codex` ### Edge Cases * `init --cli codex` must preserve an existing user-owned Codex hook. * `init --cli codex` must not mutate Claude settings. * Rerunning init must not duplicate managed hooks or create backup churn. * Uninstall must remove only FactionOS-managed Codex hooks and leave user-owned hooks intact. * Missing Codex CLI must produce a documented fixture exception, not a false pass. * Unknown, MCP, permission, subagent, and compaction-safe events must not crash ingest or leak raw payloads. * Browser validation must cover loading, empty, error, offline, and connected states where affected. * Status, doctor, evidence, replay, and export outputs must not show raw prompts, patches, command output, tokens, paths, transcripts, or MCP arguments. *** ## 10. Dependencies ### External Libraries * Playwright: `^1.60.0` * Vitest: `^4.1.7` * React testing libraries already present in the workspace. * No new runtime dependencies are planned. ### Other Sessions * **Depends on**: `phase11-session01-documentation-and-privacy-sync`, `phase11-session02-test-fixture-hardening`, `phase10-session01-cli-provider-selection-and-installer-split`, `phase10-session02-codex-hook-install-uninstall-and-diagnostics`, `phase10-session03-server-ingest-codex-lifecycle`, `phase10-session04-web-codex-awareness` * **Depended by**: `phase12-session01-codex-plugin-packaging`, `phase12-session02-release-closeout-and-rollout-readiness` *** ## Next Steps Run the implement workflow step to begin AI-led implementation. --- # 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/phase11-session03-end-to-end-validation-and-integration-fixes/spec.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.