> 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_03_queue_git_execution.md).

# Session 03: Queue Git Execution

**Session ID**: `phase20-session03-queue-git-execution` **Packages**: `packages/protocol`, `apps/server`, `apps/web` **Status**: Not Started **Estimated Tasks**: \~12-25 **Estimated Duration**: 2-4 hours

***

## Objective

Let an operator dispatch a queued Git action and see the real allowlisted Git result with rollback guidance.

***

## Scope

### In Scope (MVP)

* Extend executable task payloads for Git using the existing `CommandCenterGitWorkbenchRequest`.
* Dispatch queue Git tasks through `TaskExecutionCoordinator` and `GitWorkbenchManager.preview()` / `execute()`.
* Attach execution run ids and compact Git result summaries to queue rows.
* Add recovery notes or inverse follow-up actions for supported stage, unstage, revert, and related operations.
* Keep policy-blocked push unavailable unless a deliberate policy change enables it.
* Optionally add `Create queue task` from the File/Git workbench when it helps the user orchestrate the same real Git action.

### Out of Scope

* Replacing the existing bounded Git workbench path just because Git libraries are installed.
* Campaign Git DAG execution, except where needed as shared groundwork.

***

## Prerequisites

* [ ] Sessions 01 and 02 completed and validated.
* [ ] Git execution acceptance test defined before implementation starts.

***

## Deliverables

1. Queue-to-Git protocol, server, and UI integration that reuses the bounded Git workbench execution path.
2. Tests proving real argv construction, policy blocking, queue state updates, and visible results.

***

## Success Criteria

* [ ] Queue dispatch for `status`, `stage`, and `unstage` creates execution runs and invokes expected safe Git operations.
* [ ] Policy-blocked push returns unavailable and does not run Git.
* [ ] Failed Git commands surface bounded failure detail and rollback guidance without leaking broad raw output.
* [ ] Web tests prove Git results are visible from queue rows.
* [ ] Focused protocol, server, web, e2e, and `git diff --check` commands for this slice pass.

***

## Folded Source Detail

### User Outcome

An operator queues a Git action, dispatches it, the allowlisted Git command runs, and the Command Center shows the real Git result with rollback guidance.

### Current Source Map

* Git executor: `apps/server/src/managers/gitWorkbenchManager.ts`, `apps/server/src/routes/commandCenter.ts`, and `apps/web/src/components/orchestration/FileGitWorkbench.tsx` already build bounded argv and run local `git` for status, stage, unstage, commit, stash, revert, and branch switch.
* Direct Git execution is real but isolated from higher-level flows; users must currently find the File/Git workbench manually.
* Queue entries do not yet carry normalized executable payloads or execution result links.
* Host `git` is installed. `apps/server` declares `simple-git` and `isomorphic-git`, but the production Git path should continue reusing the bounded child-process workbench unless a later implementation proves a safer library path.

### Required Changes

* Extend executable task payloads for Git using existing `CommandCenterGitWorkbenchRequest`.
* Dispatch queue Git tasks through `TaskExecutionCoordinator` and `GitWorkbenchManager.preview()` / `execute()`.
* Attach execution run ids and compact Git result summaries to queue rows.
* Add recovery notes or inverse follow-up actions for supported stage, unstage, revert, and related operations.
* Keep policy-blocked push unavailable unless a deliberate policy change enables it.
* Optionally add `Create queue task` from the File/Git workbench when it helps the user orchestrate the same real Git action.

### Recovery Paths

* Validation failure: no Git process runs; queue becomes blocked or unavailable with a safe validation reason.
* Policy-blocked push: execution run is unavailable with `policy_blocked`; UI offers no push retry unless policy is enabled.
* Failed Git command: execution run failed with bounded stderr/stdout summary; rollback or follow-up action is visible.
* Stage, unstage, and revert recovery should create the inverse Git executable where one exists.

### Acceptance Tests From Findings

* Server coordinator test with injected `GitCommandRunner` proves exact argv for `status`, `stage`, `unstage`, and blocked `push`.
* Queue dispatch for `status`, `stage`, and `unstage` creates execution runs and invokes expected safe Git operations.
* Policy-blocked push returns unavailable and does not run Git.
* Failed Git commands surface bounded failure detail and rollback guidance without leaking broad raw output.
* Web tests prove Git execution result is visible from queue rows.


---

# 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_03_queue_git_execution.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.