> 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_20/session_07_file_executor_integration.md). # Session 07: File Executor Integration **Session ID**: `phase20-session07-file-executor-integration` **Packages**: `packages/protocol`, `apps/server`, `apps/web` **Status**: Not Started **Estimated Tasks**: \~12-25 **Estimated Duration**: 2-4 hours *** ## Objective Make file capabilities executable only when guarded actions and queue or campaign tasks perform real file mutation. *** ## Scope ### In Scope (MVP) * Replace metadata-only file executor registry behavior with adapters backed by `FileMutationManager`. * Wire guarded file approval to preview/apply real file mutations and update execution runs. * Add queue and campaign file executable dispatch through `TaskExecutionCoordinator`. * Add web preview, apply, conflict, result, and rollback states without exposing raw content in broad UI. * Update capability probes so file entries become `executor_ready` only after the real adapter is available. ### Out of Scope * Rich code editor workflows unless required for the end-to-end file mutation path. * Unsupported remote or hosted file execution. *** ## Prerequisites * [ ] Session 06 completed and validated. * [ ] File executor integration acceptance tests defined before implementation starts. *** ## Deliverables 1. Guarded file, queue file, campaign file, registry, route, and UI integration backed by real filesystem mutation. 2. Server, web, and browser tests for apply, conflict, rollback, and redaction. *** ## Success Criteria * [ ] Guarded file approval changes a real workspace file and records an executed run. * [ ] Queue file task dispatch mutates a real file, surfaces the result, and offers rollback where supported. * [ ] Conflict and stale hash paths stop before mutation and show the required recovery action. * [ ] Broad rows and WebSocket events include compact metadata only, not content or patch bodies. * [ ] Browser e2e proves visible apply and rollback for a file task. *** ## Folded Source Detail ### User Outcome An operator previews and approves a file change, the workspace file actually changes, the UI shows the result, and rollback restores the prior content when rollback is supported. ### Required Changes * Replace metadata-only file executor registry behavior with adapters backed by `FileMutationManager`. * Wire guarded file approval to preview/apply real file mutations and update execution runs. * Add queue and campaign file executable dispatch through `TaskExecutionCoordinator`. * Add web preview, apply, conflict, result, and rollback states without exposing raw content in broad UI. * Update capability probes so file entries become `executor_ready` only after the real adapter is available. * Broad UI rows show path labels, operation, hashes/counts, and result status. File content or patch bodies stay out of broad views. ### Recovery Paths * Conflict or stale hash stops before mutation and shows the required recovery action. * Backup failure stops before mutation. * Mutation failure after backup records failure and offers rollback where possible. * Rollback failure keeps the run failed with manual recovery guidance. ### Acceptance Tests From Findings * Guarded file approval test proves approve -> file changes -> execution run executed. * Queue file task test proves queue dispatch mutates file and surfaces result. * Guarded file approval changes a real workspace file and records an executed run. * Queue file task dispatch mutates a real file, surfaces the result, and offers rollback where supported. * Broad rows and WebSocket events include compact metadata only, not content or patch bodies. * Web test proves preview, apply, conflict, and rollback states render without file content leakage. * Browser e2e proves visible apply and rollback for a file task. --- # 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_20/session_07_file_executor_integration.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.