> 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/phase20-session07-file-executor-integration/spec.md). # Session Specification **Session ID**: `phase20-session07-file-executor-integration` **Phase**: 20 - Orchestration Actionability Execution **Status**: Not Started **Created**: 2026-06-28 **Package**: null **Package Stack**: mixed TypeScript across `packages/protocol`, `apps/server`, and `apps/web` *** ## 1. Session Overview This session wires the validated `FileMutationManager` from Session 06 into the executable orchestration surfaces that still treat file work as metadata-only. It promotes file capabilities only when a real manager-backed adapter is available, lets guarded file approvals run safe file mutations, and adds file executable dispatch to queue and campaign execution through `TaskExecutionCoordinator`. It is next because Phase 20 sessions 02-05 already proved terminal, Git, queue, campaign, and DAG execution behavior, while Session 06 proved safe file mutation and rollback at the manager layer. The remaining gap is product integration: an operator must be able to preview or dispatch a file task, see a real workspace mutation, observe compact result metadata, stop on conflict or stale hash, and roll back where a backup exists. The session is cross-package by design. Protocol owns the new file executable payload and guarded-action request shape; the server owns adapter, queue, campaign, route, WebSocket, and rollback behavior; the web app owns product-facing preview, apply, conflict, result, and rollback states without exposing file contents or patch bodies in broad rows. *** ## 2. Objectives 1. Add protocol support for file executable payloads and guarded file mutation requests using the Session 06 file mutation contracts. 2. Replace metadata-only file executor registry behavior with `FileMutationManager` adapters for guarded file approvals and truthful capability probes. 3. Dispatch queue and campaign file executable tasks through `TaskExecutionCoordinator` with real mutation, execution-run evidence, conflict handling, and rollback metadata. 4. Render file preview, apply, conflict, result, and rollback states in the web cockpit with product-facing copy and compact metadata only. *** ## 3. Prerequisites ### Required Sessions * [x] `phase20-session01-truthful-capability-baseline` - Keeps capability labels truthful until real execution proof exists. * [x] `phase20-session04-campaign-executable-dispatch` - Provides campaign-to-queue executable dispatch through the coordinator. * [x] `phase20-session05-campaign-dag-recovery` - Provides dependency-aware campaign execution and retry behavior. * [x] `phase20-session06-file-mutation-core` - Provides `FileMutationManager`, file mutation protocol types, backups, rollback, conflict checks, and compact execution metadata. ### Required Tools Or Knowledge * Node 26.2.0 and npm 11.16.0 from `.spec_system/CONVENTIONS.md`. * Existing `CommandCenterFileMutationRequest`, `CommandCenterFileMutationResult`, `FileMutationManager`, `TaskExecutionCoordinator`, `ExecutorRegistry`, `GuardedActionManager`, `TaskQueueManager`, `PlanCampaignManager`, and command-center UI helpers. * Current redaction rules for broad command-center rows, WebSocket events, diagnostics, and documentation. ### Environment Requirements * Local repo checkout with npm workspaces installed. * Writable temp directories for server tests and Playwright fixtures. * No hosted credentials, provider transfer, analytics, Worker proxying, remote execution, Docker runtime, database, or new native dependency is required. *** ## 4. Scope ### In Scope (MVP) * Operators can approve guarded file work that changes a real workspace file - Add a bounded file mutation request to guarded file proposals and execute it through `FileMutationManager`. * Operators can dispatch file queue tasks that mutate real files - Add a `file` task executable payload and coordinator dispatch path with duplicate-trigger prevention while in-flight. * Operators can dispatch approved campaign file tasks - Extend campaign executable dispatch to route file payloads through the same coordinator and preserve DAG retry semantics. * Operators can see recovery states - Surface conflict, stale hash, backup failure, mutation failure, result, and rollback availability in route responses, queue summaries, campaign rows, and scoped execution detail. * Operators can roll back supported file mutations - Expose a local rollback path for file execution results backed by Session 06 backup ids. * Capability probes are truthful - File entries become `executor_ready` only when a manager-backed adapter can execute the requested operation; otherwise they remain unavailable or approved-not-executing. * Broad product surfaces remain compact - Show path labels, operation labels, hashes/counts, backup id labels, result status, and rollback state only, never raw file contents or patch bodies. ### Out Of Scope (Deferred) * Rich code editor or Monaco editing workflow - Reason: the MVP needs proven preview/apply/result/rollback states, not a full editor. * Remote, hosted, Worker, container, or cloud-backed file mutation - Reason: Phase 20 remains local-first and no-claim for remote or hosted execution. * Arbitrary automatic execution of channel or webhook file commands - Reason: Session 10 owns template/channel intake and channel intake remains proposal-first. * New file mutation core semantics beyond Session 06 contracts - Reason: this session integrates the existing manager instead of redefining path, backup, or rollback rules. * Trusted unified erasure for file backups - Reason: security posture keeps trusted unified erasure as no-claim. * Database, persistence schema, or migration work - Reason: current command-center and queue state remain manager-owned local runtime state. *** ## 5. Technical Approach ### Architecture Protocol changes should stay small and centered on existing contracts. Add a `file` `TaskQueueExecutablePayload` variant that wraps `CommandCenterFileMutationRequest`, extend task queue execution summaries with file operation, path label, changed byte count, backup id, rollback state, and recovery note fields, and add a bounded guarded-action file mutation reference so a guarded file approval can execute real mutation data instead of deriving writes from display copy. Server integration should reuse the manager boundaries already proven in Session 06. Instantiate `FileMutationManager` in `apps/server/src/server.ts` with the local workspace root, FactionOS state root, `FileIntentManager`, and `OrchestrationCommandCenterManager`. Inject it into `TaskExecutionCoordinator` and `createDefaultExecutorRegistry`, then add a file dispatch path that creates or updates execution runs, calls `FileMutationManager.execute` or `rollback`, records queue summaries, emits compact queue/execution updates, and maps validation, conflict, stale hash, backup failure, mutation failure, and rollback failure to explicit product states. Web integration should normalize the compact file execution summary and reuse existing queue, campaign, File/Git, and execution drawer surfaces. File preview/apply and rollback controls should use stable mutation keys, idempotency keys where accepted, explicit loading, empty, error, offline, conflict, stale, result, and rollback states, and product-facing copy only. Broad rows should never render file content, patch bodies, raw absolute paths, tokens, secrets, provider payloads, raw diagnostics, or implementation labels. ### Design Patterns * Protocol-first contracts: shared file executable and guarded file request shapes land before server and web consumers. * Manager-owned execution: path safety, backups, rollback, idempotency, execution evidence, and compact metadata remain in `FileMutationManager` and command-center managers. * Coordinator-owned queue/campaign dispatch: queue and campaign routes call `TaskExecutionCoordinator` instead of duplicating file execution in route handlers. * Broad-summary plus scoped-detail split: broad queue, campaign, WebSocket, and capability rows show compact metadata only; scoped execution detail may show safe result metadata but not raw file content or patch bodies. * Fail closed before mutation: conflict, stale hash, invalid request, missing backup, backup failure, and unavailable manager states stop before unsafe changes. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | ------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ---------- | | `packages/protocol/tests/taskQueue.test.ts` | Protocol coverage for file executable payload parsing, summary parsing, and blocked raw-field rejection. | \~180 | ### Files To Modify | File | Changes | Est. Lines | | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `packages/protocol/src/taskQueue.ts` | Add `file` executable payload, file execution summary fields, parser validation, and safe clone support. | \~180 | | `packages/protocol/src/guardedActions.ts` | Add bounded guarded file mutation request/reference fields for file guarded actions. | \~80 | | `packages/protocol/src/rest.ts` | Keep REST request/response types aligned with task queue and guarded action file mutation payloads. | \~40 | | `packages/protocol/tests/guardedActions.test.ts` | Cover guarded file mutation request typing and safe payload expectations. | \~80 | | `apps/server/src/lib/guardedActionValidation.ts` | Parse and validate guarded file mutation payloads with schema-validated input and explicit error mapping. | \~120 | | `apps/server/src/managers/executorRegistry.ts` | Replace file metadata-only entries with manager-backed adapters and truthful file capability probes. | \~220 | | `apps/server/src/managers/taskExecutionCoordinator.ts` | Add file dispatch and rollback support with duplicate-trigger prevention, execution runs, queue summaries, and compact error mapping. | \~280 | | `apps/server/src/managers/taskQueue.ts` | Clone and summarize file executable payloads without file content leakage. | \~100 | | `apps/server/src/managers/planCampaignManager.ts` | Route campaign file executable payloads through coordinator dispatch and preserve DAG recovery semantics. | \~80 | | `apps/server/src/routes/orchestration.ts` | Select file dispatch for `/task-queue/:id/dispatch` and emit queue/execution updates. | \~50 | | `apps/server/src/routes/guardedActions.ts` | Complete approved file actions through the manager-backed registry and emit compact execution updates. | \~40 | | `apps/server/src/server.ts` | Instantiate and inject `FileMutationManager` into coordinator and executor registry. | \~60 | | `apps/server/tests/taskExecutionCoordinator.test.ts` | Prove queue file dispatch mutates a real temp file, records execution, handles stale/conflict paths, and exposes rollback metadata. | \~220 | | `apps/server/tests/executorRegistry.test.ts` | Prove file capabilities are ready only with a manager-backed adapter and unavailable without it. | \~160 | | `apps/server/tests/guardedActions.test.ts` | Prove guarded file approval changes a real workspace file and records an executed run. | \~180 | | `apps/server/tests/orchestration.test.ts` | Prove `/task-queue/:id/dispatch` selects file dispatch and returns compact file execution results. | \~160 | | `apps/server/tests/planCampaignManager.test.ts` | Prove campaign file executable dispatch mutates files and preserves retry/recovery state. | \~180 | | `apps/server/tests/commandCenterRoutes.test.ts` | Cover route-level compact command-center response and event privacy for file execution results. | \~120 | | `apps/web/src/lib/orchestrationApi.ts` | Add file task helpers, request serialization, response validation, and rollback mutation helper. | \~160 | | `apps/web/src/lib/orchestrationUi.ts` | Normalize file execution summaries, labels, counts, rollback state, and recovery copy with redaction. | \~120 | | `apps/web/src/lib/commandCenterUi.ts` | Update file capability/action labels so ready, unavailable, conflict, result, and rollback states are product-facing. | \~80 | | `apps/web/src/components/orchestration/FileGitWorkbench.tsx` | Add preview/apply/conflict/result/rollback states for file mutation tasks without rich editor scope. | \~220 | | `apps/web/src/components/orchestration/QueueWorkbench.tsx` | Show compact file execution state and rollback action affordance from queue summaries. | \~80 | | `apps/web/src/components/orchestration/CampaignWorkbench.tsx` | Show compact file execution result and recovery state for campaign file rows. | \~80 | | `apps/web/src/components/orchestration/ExecutorRunHistoryDrawer.tsx` | Render file execution metadata and rollback state without raw content or patch bodies. | \~80 | | `apps/web/tests/orchestrationApi.test.ts` | Cover file task create/dispatch/rollback serialization and response validation. | \~180 | | `apps/web/tests/orchestrationUi.test.ts` | Cover safe file execution labels, counts, recovery text, and redaction. | \~120 | | `apps/web/tests/FileGitWorkbench.test.tsx` | Cover file preview/apply/conflict/result/rollback UI states and duplicate in-flight guards. | \~220 | | `apps/web/tests/CommandCenterPanes.test.tsx` | Cover file task creation and product-surface integration from the File/Git pane. | \~140 | | `apps/web/tests/ExecutorFamiliesPanel.test.tsx` | Cover file capability readiness and unavailable copy. | \~80 | | `tests/e2e/orchestration-command-center.e2e.ts` | Add browser proof for visible file task apply and rollback. | \~180 | | `apps/server/README_server.md` | Document file executor integration, backup/rollback boundary, and compact event behavior. | \~50 | | `apps/web/README_web.md` | Document web file execution product states and content leakage boundary. | \~50 | | `docs/api/README_api.md` | Document shipped local file queue/guarded/campaign execution and rollback routes or payloads. | \~70 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Guarded file approval changes a real workspace file and records an executed command-center run. * [ ] Queue file task dispatch mutates a real file, surfaces compact result metadata, and offers rollback when the manager returns a backup id with rollback available. * [ ] Campaign file executable dispatch mutates a real file through the coordinator and preserves DAG retry or recovery state on failed/unavailable execution. * [ ] Conflict, stale hash, invalid request, backup failure, mutation failure, and rollback failure paths stop safely and show the required recovery action. * [ ] Capability probes mark file entries `executor_ready` only when the manager-backed adapter is available and the requested operation can execute. * [ ] Broad REST responses, WebSocket events, queue rows, campaign rows, capability rows, execution drawers, docs, and tests include compact metadata only, not file contents or patch bodies. ### Testing Requirements * [ ] Protocol tests cover file executable payloads, guarded file mutation request fields, summary parsing, and blocked raw-field rejection. * [ ] Server tests cover guarded file approval, queue file dispatch, campaign file dispatch, stale/conflict/backup failure, rollback metadata, route selection, capability probes, and event privacy. * [ ] Web tests cover preview/apply/conflict/result/rollback states, duplicate in-flight prevention, offline/error handling, capability labels, and redaction. * [ ] Browser e2e proves visible apply and rollback for a file task. ### Non-Functional Requirements * [ ] No file operation runs outside the approved local workspace root and local FactionOS backup root. * [ ] File execution, rollback, and UI mutation controls are duplicate-trigger protected while in flight. * [ ] Sensitive developer data remains local and scoped; no hosted, Worker, provider, analytics, or remote execution behavior is introduced. * [ ] Existing terminal and Git queue/campaign dispatch behavior remains compatible. ### Quality Gates * [ ] All files ASCII-encoded * [ ] Unix LF line endings * [ ] Code follows project conventions * [ ] Primary user-facing surfaces contain product-facing copy only * [ ] Focused protocol, server, web, browser, root quality, and `git diff --check` commands pass *** ## 8. Implementation Notes ### Working Assumptions * Cross-package scope is intentional: the analyzer reports `package: null`, the selected stub lists `packages/protocol`, `apps/server`, and `apps/web`, and the required outcome spans shared contracts, local runtime behavior, and cockpit UI. Planning can proceed with `Package: null` because all task paths are repo-root-relative and the affected packages are explicit. * A guarded file action needs a structured file mutation request: current guarded-action proposals contain display preview fields and references only, while real file mutation requires operation, path, expected hash, and bounded request data from Session 06 contracts. Planning can proceed by adding a bounded protocol field instead of deriving executable writes from preview text. * A lightweight file mutation UI is sufficient: `apps/web` already has a File/Git workbench and queue/campaign result surfaces. Planning can proceed without Monaco or rich editor workflows by adding safe preview/apply/result/rollback states to existing surfaces. * Rollback is local recovery, not trusted erasure: Session 06 creates backups under local FactionOS state, and security posture keeps trusted unified erasure as no-claim. Planning can proceed with rollback metadata while preserving no-claim erasure wording. ### Conflict Resolutions * The Session 06 validation reports `FileMutationManager` execution metadata exists, but Session 07 requires queue/campaign/guarded/web product integration. The chosen interpretation is that Session 07 must wire the existing manager into orchestration surfaces, not reimplement file mutation safety. * `TaskQueueExecutableKind` currently supports only `terminal` and `git`, while Phase 20 Session 07 requires queue and campaign file dispatch. The chosen interpretation is to extend the task queue protocol with a `file` variant because queue and campaign dispatch already depend on executable payloads. * Existing file executor registry entries intentionally stay `approved_not_executing`. The chosen interpretation is to preserve that state when no manager-backed adapter is injected and promote to `executor_ready` only in the integrated runtime path. ### Key Considerations * \[P19] Executor claims are family-scoped: file executor readiness is allowed only after guarded, queue, campaign, redaction, tests, docs, and browser evidence exist. * \[P19] Scoped detail stays separate from broad rows: file content, patch bodies, raw diffs, absolute paths, tokens, secrets, provider payloads, and raw diagnostics stay out of broad surfaces. * \[P03-packages/protocol] Protocol leads cross-package work: file executable and guarded request contracts land before server and web consumers. * \[P19] Command-center state is manager-owned: execution runs, idempotency, event emission, and compact snapshots remain in managers. * \[P07] Redaction is boundary-specific: queue summaries, campaign rows, route responses, WebSocket events, execution drawers, docs, and tests each need explicit minimization. ### Potential Challenges * Guarded action request shape is currently display-only: add a bounded file mutation request field and validation rather than relying on preview copy. * File rollback needs a discoverable product path: expose rollback state and backup id labels in compact metadata, then route rollback through a stable helper with duplicate in-flight guards. * Queue and campaign dispatch can drift: keep all file executable execution in `TaskExecutionCoordinator` so direct queue and campaign dispatch share behavior. * Web UI could leak file content accidentally: render only operation, path label, hashes/counts, result state, backup id label, rollback state, and recovery copy. * Capability probes can overclaim: tests must prove missing manager remains unavailable or approved-not-executing and integrated manager becomes ready only for supported file operations. ### Relevant Considerations * \[P19] **Executor claims are family-scoped**: File readiness must be backed by end-to-end proof. * \[P19] **Scoped detail stays separate from broad rows**: File content and patch detail stay out of broad UI, events, docs, and tests. * \[P03-packages/protocol] **Protocol leads cross-package work**: Shared queue and guarded file payload contracts lead the implementation. * \[P19] **Command-center state is manager-owned**: Coordinator, registry, and managers own execution state and compact updates. * \[P06-S07-ERASURE] **Trusted unified erasure remains no-claim**: Rollback backups do not imply trusted deletion. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * State-mutating file operations or rollback actions running twice when users click repeatedly or WebSocket updates replay. * Conflict, stale hash, invalid request, backup failure, mutation failure, or rollback failure changing files or leaving rows in misleading executed states. * File contents, patch bodies, absolute paths, tokens, secrets, provider payloads, raw diagnostics, or implementation labels leaking into broad rows, events, docs, browser screenshots, or tests. *** ## 9. Testing Strategy ### Unit Tests * Protocol tests for file executable payload parsing, guarded file mutation request fields, file execution summaries, rollback metadata, and blocked raw-field rejection. * Server unit tests for executor registry readiness, file adapter execution, task coordinator file dispatch, stale/conflict/backup failure mapping, queue summary output, and rollback metadata. * Web unit tests for file execution UI labels, count summaries, recovery copy, rollback states, in-flight keys, API serialization, and redaction. ### Integration Tests * Guarded action route test that creates a file guarded action with a bounded file mutation request, approves it, verifies the temp workspace file changed, and verifies the execution run is executed. * Task queue route test that creates or dispatches a file executable payload, verifies the temp file changed, and confirms compact route response and WebSocket event metadata. * Campaign manager or route test that dispatches an approved campaign file task through the coordinator and preserves DAG recovery state when the file mutation fails or is unavailable. ### Runtime Verification * Playwright app test seeds a file queue task, dispatches it from the Command Center, observes product-facing result state, triggers rollback where supported, and verifies the visible rollback result without rendering raw file content. ### Edge Cases * Missing `FileMutationManager` injection leaves file capability unavailable or approved-not-executing. * Guarded file action lacks structured mutation request. * Queue file dispatch receives terminal or Git payload through the wrong route path. * Campaign file task has a stale dependency or failed prerequisite. * Active file intent conflict exists for the target path. * Expected hash is stale. * Backup creation fails before mutation. * Mutation fails after backup. * Rollback is requested with missing, invalid, or already-rolled-back backup id. * Server reconnect or WebSocket replay repeats an in-flight file mutation update. * Web is offline or the local server is disconnected during preview, apply, or rollback. *** ## 10. Dependencies ### Other Sessions * Depends on: `phase20-session06-file-mutation-core` * Depended by: `phase20-session08-managed-agent-lifecycle-control`, `phase20-session11-release-evidence-and-event-privacy` *** ## Next Steps Run the `implement` workflow step to begin 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/phase20-session07-file-executor-integration/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.