> 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/tasks.md).

# Task Checklist

**Session ID**: `phase20-session07-file-executor-integration` **Total Tasks**: 24 **Estimated Duration**: 3.5-4 hours **Created**: 2026-06-28

***

Legend: `[x]` completed; `[ ]` pending; `[P]` parallelizable; `[SNNMM]` session ref; `TNNN` task ID.

***

## Setup (3 tasks)

* [x] T001 \[S2007] Verify Session 06 validation evidence, current file executor posture, and file mutation manager APIs before integration (`.spec_system/specs/phase20-session06-file-mutation-core/validation.md`)
* [x] T002 \[S2007] Add protocol acceptance coverage for file task executable payloads, guarded file mutation request fields, file execution summaries, rollback metadata, and blocked raw-field rejection (`packages/protocol/tests/taskQueue.test.ts`, `packages/protocol/tests/guardedActions.test.ts`)
* [x] T003 \[S2007] Add server acceptance coverage for guarded file approval, queue file dispatch, campaign file dispatch, capability readiness, rollback metadata, stale/conflict paths, and compact event privacy before implementation (`apps/server/tests/taskExecutionCoordinator.test.ts`, `apps/server/tests/executorRegistry.test.ts`, `apps/server/tests/guardedActions.test.ts`, `apps/server/tests/orchestration.test.ts`, `apps/server/tests/planCampaignManager.test.ts`)

***

## Foundation (5 tasks)

* [x] T004 \[S2007] Extend task queue protocol with a `file` executable payload wrapping `CommandCenterFileMutationRequest` and safe file execution summary fields (`packages/protocol/src/taskQueue.ts`)
* [x] T005 \[S2007] Extend guarded action protocol and server validation with bounded file mutation request fields for file guarded actions with schema-validated input and explicit error mapping (`packages/protocol/src/guardedActions.ts`, `apps/server/src/lib/guardedActionValidation.ts`)
* [x] T006 \[S2007] Keep REST contract exports aligned for task queue and guarded action file mutation payloads (`packages/protocol/src/rest.ts`)
* [x] T007 \[S2007] Instantiate `FileMutationManager` with workspace root, FactionOS state root, file intents, and command-center manager, then inject it into coordinator and registry construction (`apps/server/src/server.ts`)
* [x] T008 \[S2007] Update task queue manager cloning and initial execution summaries for file executable payloads without file content or patch body leakage (`apps/server/src/managers/taskQueue.ts`)

***

## Server Implementation (6 tasks)

* [x] T009 \[S2007] Replace metadata-only file registry entries with manager-backed file adapters and truthful probes that stay unavailable when the manager is absent (`apps/server/src/managers/executorRegistry.ts`)
* [x] T010 \[S2007] Implement queue file dispatch through `TaskExecutionCoordinator` with duplicate-trigger prevention while in-flight, execution-run lifecycle updates, compact result summaries, and stale/conflict/error mapping (`apps/server/src/managers/taskExecutionCoordinator.ts`)
* [x] T011 \[S2007] Implement file rollback dispatch or helper support through the coordinator with idempotency protection, missing-backup handling, rollback failure mapping, and safe execution metadata (`apps/server/src/managers/taskExecutionCoordinator.ts`)
* [x] T012 \[S2007] Route `/task-queue/:id/dispatch` file payloads to coordinator file dispatch and emit queue/execution updates (`apps/server/src/routes/orchestration.ts`)
* [x] T013 \[S2007] Route approved guarded file actions through the manager-backed registry so approve changes a real file and records an executed run (`apps/server/src/routes/guardedActions.ts`, `apps/server/src/managers/executorRegistry.ts`)
* [x] T014 \[S2007] Extend campaign executable dispatch to send file payloads through the coordinator while preserving DAG ordering, retry, blocked, failed, and unavailable semantics (`apps/server/src/managers/planCampaignManager.ts`)

***

## Web Implementation (5 tasks)

* [x] T015 \[S2007] Add web API helpers and validators for file task creation, file dispatch, file rollback, and compact file execution responses (`apps/web/src/lib/orchestrationApi.ts`)
* [x] T016 \[S2007] Normalize file execution summaries, operation labels, path labels, changed-byte counts, rollback states, and recovery copy with redaction (`apps/web/src/lib/orchestrationUi.ts`, `apps/web/src/lib/commandCenterUi.ts`)
* [x] T017 \[S2007] Add File/Git workbench file preview, apply, conflict, result, and rollback states with explicit loading, empty, error, offline, and duplicate-in-flight handling (`apps/web/src/components/orchestration/FileGitWorkbench.tsx`)
* [x] T018 \[S2007] Render compact file execution and rollback affordances in queue, campaign, and execution-history surfaces with product-facing copy only (`apps/web/src/components/orchestration/QueueWorkbench.tsx`, `apps/web/src/components/orchestration/CampaignWorkbench.tsx`, `apps/web/src/components/orchestration/ExecutorRunHistoryDrawer.tsx`)
* [x] T019 \[S2007] Update web integration tests for file API serialization, file UI labels, capability readiness, File/Git pane states, queue/campaign result rows, redaction, offline/error states, and in-flight guards (`apps/web/tests/orchestrationApi.test.ts`, `apps/web/tests/orchestrationUi.test.ts`, `apps/web/tests/FileGitWorkbench.test.tsx`, `apps/web/tests/CommandCenterPanes.test.tsx`, `apps/web/tests/ExecutorFamiliesPanel.test.tsx`)

***

## Documentation And Browser Evidence (3 tasks)

* [x] T020 \[S2007] Document local file executor integration, backup/rollback boundary, compact event behavior, web product states, and no remote/hosted execution claim (`apps/server/README_server.md`, `apps/web/README_web.md`, `docs/api/README_api.md`)
* [x] T021 \[S2007] Add browser e2e coverage proving visible file task apply and rollback without raw file content leakage (`tests/e2e/orchestration-command-center.e2e.ts`)
* [x] T022 \[S2007] Verify broad REST responses, WebSocket fixtures, UI rows, docs, and tests do not expose file contents, patch bodies, broad absolute paths, tokens, secrets, provider payloads, or raw diagnostics (`apps/server/tests/commandCenterRoutes.test.ts`, `apps/web/tests/orchestrationUi.test.ts`, `tests/e2e/orchestration-command-center.e2e.ts`)

***

## Verification (2 tasks)

* [x] T023 \[S2007] Run focused protocol, server, web, and browser checks (`npx vitest run packages/protocol/tests/taskQueue.test.ts packages/protocol/tests/guardedActions.test.ts apps/server/tests/taskExecutionCoordinator.test.ts apps/server/tests/executorRegistry.test.ts apps/server/tests/guardedActions.test.ts apps/server/tests/orchestration.test.ts apps/server/tests/planCampaignManager.test.ts apps/server/tests/commandCenterRoutes.test.ts apps/web/tests/orchestrationApi.test.ts apps/web/tests/orchestrationUi.test.ts apps/web/tests/FileGitWorkbench.test.tsx apps/web/tests/CommandCenterPanes.test.tsx apps/web/tests/ExecutorFamiliesPanel.test.tsx`; `npm run test:e2e -- --project=app-desktop tests/e2e/orchestration-command-center.e2e.ts`)
* [x] T024 \[S2007] Run workspace quality and whitespace gates (`npm --workspace packages/protocol run typecheck`; `npm --workspace apps/server run typecheck`; `npm --workspace apps/web run typecheck`; `npm run format:check`; `npm run lint`; `npm run typecheck --workspaces --if-present`; `npm test`; `git diff --check`)

***

## Completion Checklist

* [x] All tasks marked `[x]`
* [x] All tests and checks passing
* [x] All files ASCII-encoded with LF line endings
* [x] implementation-notes.md updated
* [x] Ready for `implement` to start the implement -> creview -> validate sequence

***

## Next Steps

Run the `creview` workflow step.


---

# 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/tasks.md?ask=<question>&goal=<endgoal>
```

`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.