> 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-session03-queue-git-execution/spec.md).

# Session Specification

**Session ID**: `phase20-session03-queue-git-execution` **Phase**: 20 - Orchestration Actionability Execution **Status**: Not Started **Created**: 2026-06-28 **Package**: null **Package Stack**: TypeScript across `packages/protocol`, `apps/server`, and `apps/web`; JavaScript for compact CLI diagnostics

***

## 1. Session Overview

This session delivers the next executable queue slice: a local queue task can carry a Git executable payload, dispatch through the server coordinator, run the existing bounded Git workbench path, record a command-center execution run, and show a compact result with recovery guidance in the Command Center.

It is next because Session 01 corrected metadata-only action labels and Session 02 created the shared queue execution contract, private executable payload storage, safe queue execution summaries, coordinator pattern, route dispatch behavior, event privacy checks, and web queue result surface. The Phase 20 PRD names Queue Git Execution as the next unfinished executable slice.

The session keeps Git policy narrow. Status, stage, unstage, and supported local recovery operations may run through the allowlisted workbench. Push stays unavailable unless a separate policy change explicitly enables it. Raw Git output, diffs, commit messages, broad absolute paths, and patch bodies must not appear in broad queue rows, WebSocket snapshots, diagnostics, exports, notifications, or docs examples.

***

## 2. Objectives

1. Extend the protocol-owned executable queue contract so Git queue entries reuse `CommandCenterGitWorkbenchRequest` while exposing only safe public execution summaries.
2. Extend `TaskExecutionCoordinator` so Git queue dispatch calls `GitWorkbenchManager.preview()` and `execute()`, records command-center execution runs, and updates queue state with idempotent duplicate handling.
3. Update web queue and File/Git workbench surfaces so operators can create, dispatch, inspect, retry, and follow recovery guidance for Git queue tasks.
4. Add focused protocol, server, web, CLI, browser, docs, privacy, and whitespace evidence for allowed Git execution, policy-blocked push, failed Git commands, and compact result rendering.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase20-session01-truthful-capability-baseline` - Provides truthful copy and capability state boundaries for metadata-only actions.
* [x] `phase20-session02-queue-terminal-execution` - Provides executable queue payload contracts, `TaskExecutionCoordinator`, safe queue execution summaries, dual queue/execution events, route dispatch integration, web queue links, and diagnostics privacy patterns.
* [x] `phase19-session08-file-and-git` - Provides the bounded Git workbench manager, request contract, direct preview/execute routes, and web File/Git workbench.
* [x] `phase19-session06-executor-registry` - Provides command-center execution run vocabulary and executor-family boundaries.

### Required Tools Or Knowledge

* Node 26.2.0+ and npm 11.16.0 from `.spec_system/CONVENTIONS.md`.
* Vitest for protocol, server, web, and CLI tests.
* Playwright for browser coverage under `tests/e2e/orchestration-command-center.e2e.ts`.
* Existing Git workbench contracts in `packages/protocol/src/orchestrationCommandCenter.ts` and `apps/server/src/managers/gitWorkbenchManager.ts`.

### Environment Requirements

* No external credentials, hosted services, provider transfer, Docker, remote execution, or Worker command bridge is required.
* Server tests should use injected fake `GitCommandRunner` behavior; product runtime may use the existing local `git` child-process runner.
* Work stays local to the monorepo and all edited files must remain ASCII with Unix LF line endings.

***

## 4. Scope

### In Scope (MVP)

* Operators can create a queue task with a Git executable payload based on `CommandCenterGitWorkbenchRequest` - store the private payload while exposing only operation, safe label, execution ids, result state, compact result summary, and recovery note.
* Operators can dispatch status, stage, and unstage queue Git tasks - run the bounded Git workbench path with duplicate-trigger prevention while in-flight.
* Operators see execution run ids and compact Git summaries on queue rows - include safe dirty/staged/conflict counts and rollback or inverse guidance without raw Git output, diffs, commit messages, patch content, or broad paths.
* Operators see policy-blocked push as unavailable - do not run Git push and do not show a retry that implies policy has changed.
* Operators can create a queue task from the File/Git workbench - copy the reviewed Git draft into a local queue entry so orchestration can dispatch the same real Git action.
* Maintainers get protocol, server, web, CLI, browser, docs, and privacy tests proving real argv construction, policy blocking, queue state updates, event privacy, visible results, and recovery guidance.

### Out Of Scope (Deferred)

* Campaign Git DAG execution - Reason: owned by Phase 20 Sessions 04 and 05 after queue Git dispatch is proven.
* Broad push enablement or remote Git execution - Reason: push remains policy-blocked until a future threat model, authorization, audit, redaction, tests, docs, and release evidence exist.
* Replacing the existing bounded child-process Git workbench with Git library behavior - Reason: the Phase 20 stub requires reuse of the current bounded workbench unless a later session proves a safer replacement.
* File mutation beyond Git stage/unstage/revert semantics - Reason: workspace file mutation and rollback are owned by Phase 20 Sessions 06 and 07.
* Commit, stash, branch switch, and revert queue execution beyond safe summary and recovery planning if not needed for status/stage/unstage acceptance - Reason: this session must stay focused on the queue Git slice.

***

## 5. Technical Approach

### Architecture

Start in `packages/protocol/src/taskQueue.ts` by expanding executable payloads from terminal-only to terminal or Git. The Git payload should carry a `CommandCenterGitWorkbenchRequest`-compatible request and optional execution run id, command label, owner/idempotency metadata, and recovery metadata. Public queue entries and events should expose `family: "git"`, the specific Git executor kind, a safe command label, state, result status, result summary, execution run id, failure/unavailable codes, recovery note, and compact counts. They must not expose raw Git stdout, stderr, diffs, commit messages, or patch bodies.

Extend `apps/server/src/managers/taskExecutionCoordinator.ts` rather than adding a parallel coordinator. Inject `GitWorkbenchManager` in `apps/server/src/server.ts`, add `dispatchGit()`, and let route dispatch choose Git or terminal by executable kind. `dispatchGit()` should create a queued command-center execution run targeted to the queue item, call preview for policy/validation planning, mark the run executing only for executable plans, call execute, translate result status into queue state, attach compact Git result metadata, and return idempotent duplicate responses.

On the web, extend API parsing, queue view models, queue action labels, store reconciliation, and `QueueWorkbench` creation controls for Git entries. The File/Git workbench can offer `Create queue task` from the current reviewed draft, so operators can preview or configure the Git action before queueing it. Git execution detail remains a compact queue and run result; raw output stays server scoped and redacted by the Git workbench.

### Design Patterns

* Protocol-first executable contract: add shared Git executable shapes before server and web consumers.
* Manager-owned runtime boundary: queue dispatch belongs in `TaskExecutionCoordinator`, not route-local state patches.
* Reuse existing bounded execution island: call `GitWorkbenchManager` instead of shelling out from queue code.
* Broad-summary/scoped-detail split: queue rows, events, diagnostics, and docs show compact labels and summaries only.
* Idempotent mutation keys: duplicate dispatches return the existing queue and execution state instead of starting a second Git command.
* Product-facing UI states: normal cockpit controls show Git status, dispatch, retry, unavailable, and recovery guidance without debug copy.

***

## 6. Deliverables

### Files To Create

| File | Purpose                                                                     | Est. Lines |
| ---- | --------------------------------------------------------------------------- | ---------- |
| none | Existing coordinator, test, UI, and docs files are extended for this slice. | 0          |

### Files To Modify

| File                                                           | Changes                                                                                                                                               | Est. Lines |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `packages/protocol/src/taskQueue.ts`                           | Add Git executable payloads, Git execution summary fields, parser support, safe blocked-field rejection, and execution link behavior.                 | \~180      |
| `packages/protocol/tests/orchestration.test.ts`                | Cover Git executable payload parsing, safe queue event shape, blocked raw Git fields, and policy unavailable summaries.                               | \~120      |
| `packages/protocol/tests/orchestrationCommandCenter.test.ts`   | Cover queue-targeted Git execution runs and compact Git result metadata.                                                                              | \~60       |
| `apps/server/src/lib/orchestrationValidation.ts`               | Validate Git executable create, preview, update, and dispatch inputs with schema-validated input and explicit error mapping.                          | \~80       |
| `apps/server/src/managers/taskQueue.ts`                        | Store private Git executable payloads and create safe Git execution summaries with deterministic ordering.                                            | \~120      |
| `apps/server/src/managers/taskExecutionCoordinator.ts`         | Add Git dispatch, preview/execute integration, queue state mapping, policy unavailable handling, recovery notes, idempotency, and dual event changes. | \~260      |
| `apps/server/src/managers/gitWorkbenchManager.ts`              | Expose compact result/recovery fields needed by queue dispatch without broad raw output.                                                              | \~60       |
| `apps/server/src/routes/orchestration.ts`                      | Route `/task-queue/:id/dispatch` to Git or terminal coordinator paths and emit queue plus execution events.                                           | \~80       |
| `apps/server/src/server.ts`                                    | Inject `GitWorkbenchManager` into `TaskExecutionCoordinator`.                                                                                         | \~20       |
| `apps/server/tests/taskExecutionCoordinator.test.ts`           | Cover Git status, stage, unstage, validation failure, policy-blocked push, failed command, duplicate dispatch, and queue/execution state updates.     | \~220      |
| `apps/server/tests/orchestration.test.ts`                      | Cover route-level Git queue dispatch, dual event emission, privacy, stale revision, and start-tracking compatibility.                                 | \~160      |
| `apps/server/tests/gitWorkbenchManager.test.ts`                | Cover queue-reused Git result and rollback metadata if existing assertions need expansion.                                                            | \~80       |
| `apps/server/tests/orchestrationDiagnostics.test.ts`           | Cover compact Git queue/execution diagnostics and privacy redaction.                                                                                  | \~60       |
| `apps/web/src/lib/orchestrationApi.ts`                         | Add Git executable create/dispatch payload support, response parsing, and File/Git-to-queue request shaping.                                          | \~120      |
| `apps/web/src/lib/orchestrationUi.ts`                          | Build safe Git queue execution view models, state copy, result summaries, recovery labels, and no-output fallbacks.                                   | \~100      |
| `apps/web/src/lib/commandCenterUi.ts`                          | Add Git queue action labels, enabled states, retry/unavailable wording, and broad text redaction checks.                                              | \~80       |
| `apps/web/src/components/orchestration/QueueWorkbench.tsx`     | Add Git task creation controls, dispatch/retry labels, result summary, recovery note, and accessible duplicate-disabled states.                       | \~160      |
| `apps/web/src/components/orchestration/FileGitWorkbench.tsx`   | Add `Create queue task` from a reviewed Git draft with accessible controls and product-facing feedback.                                               | \~90       |
| `apps/web/src/components/orchestration/CommandCenterPanes.tsx` | Pass File/Git queue creation handlers and keep queue/result links wired.                                                                              | \~40       |
| `apps/web/src/store/useGameStore.ts`                           | Merge Git queue execution summaries from command-center events and clear Git queue in-flight keys safely.                                             | \~90       |
| `apps/web/tests/orchestrationApi.test.ts`                      | Cover Git executable request/response parsing and raw Git privacy in broad responses.                                                                 | \~90       |
| `apps/web/tests/orchestrationUi.test.ts`                       | Cover Git queue result labels, policy-blocked push copy, rollback guidance, and fallback summaries.                                                   | \~90       |
| `apps/web/tests/CommandCenterPanes.test.tsx`                   | Cover integrated Git queue controls, File/Git create queue task, result summary, and recovery rendering.                                              | \~130      |
| `apps/web/tests/commandCenterStore.test.ts`                    | Cover Git execution run reconciliation and in-flight cleanup for queue-targeted Git runs.                                                             | \~80       |
| `apps/cli/src/lib/orchestrationDiagnostics.js`                 | Add compact Git queue/execution readiness summary while preserving redaction.                                                                         | \~60       |
| `apps/cli/tests/orchestrationDiagnostics.test.js`              | Cover compact Git diagnostics and privacy redaction for Git output, diffs, commit messages, and paths.                                                | \~70       |
| `tests/e2e/orchestration-command-center.e2e.ts`                | Add visible queue-to-Git dispatch flow with mocked local routes and browser guard assertions.                                                         | \~120      |
| `docs/api/README_api.md`                                       | Document Git executable queue routes, response fields, policy-blocked push, recovery states, and privacy boundaries.                                  | \~60       |
| `docs/api/event-api-hook-contracts.md`                         | Document queue Git dispatch event contract and raw-field exclusions.                                                                                  | \~50       |
| `apps/web/README_web.md`                                       | Update Command Center queue and File/Git UX contract for Git queue execution and recovery guidance.                                                   | \~40       |
| `apps/cli/README_cli.md`                                       | Update diagnostics notes for Git queue readiness and privacy.                                                                                         | \~30       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Creating a Git queue task stores a scoped Git executable request while broad queue rows and `task_queue_update` events expose only safe summary metadata.
* [ ] Dispatching Git status, stage, and unstage queue tasks creates or reuses a queue-targeted `CommandCenterExecutionRun`, invokes the expected allowlisted Git argv through `GitWorkbenchManager`, updates the queue row, and emits both `task_queue_update` and `command_center_execution_update`.
* [ ] Policy-blocked push returns unavailable and does not run Git.
* [ ] Validation failure, failed Git command, stale revision, and duplicate dispatch produce truthful queue and execution states with recovery or existing-run responses.
* [ ] The Command Center queue UI shows Git family, execution state, compact result summary, recovery note, retry where valid, and File/Git queue creation without broad raw output.

### Testing Requirements

* [ ] Protocol tests cover Git executable queue contracts, queue-targeted Git execution runs, safe event shape, and raw-field rejection.
* [ ] Server tests cover coordinator success, unavailable push, validation failure, failed command, stale revision, duplicate dispatch, route behavior, exact safe argv construction, and dual event emission.
* [ ] Web tests cover API parsing, store reconciliation, queue/File-Git UI labels, recovery guidance, result summaries, and no raw Git output in broad views.
* [ ] Browser e2e proves the visible queue-to-Git dispatch flow.
* [ ] CLI diagnostics tests prove compact Git queue summaries and redaction.

### Non-Functional Requirements

* [ ] Raw Git stdout, stderr, diffs, patch bodies, commit messages, tokens, secrets, and broad absolute paths stay out of queue rows, WebSocket snapshots, diagnostics, exports, notifications, and docs examples.
* [ ] Git dispatch enforces idempotency, duplicate-trigger prevention, validation before execution, timeout/failure mapping, and no retry for policy-blocked push.
* [ ] Queue and execution updates use deterministic ordering, bounded payloads, and explicit error mapping.
* [ ] Product UI preserves keyboard, pointer, and screen-reader access for Git queue creation, dispatch, result inspection, and recovery guidance.

### Quality Gates

* [ ] All files ASCII-encoded
* [ ] Unix LF line endings
* [ ] Code follows project conventions
* [ ] UI surfaces contain product-facing copy only
* [ ] `git diff --check` passes

***

## 8. Implementation Notes

### Working Assumptions

* Cross-package session scope: The analyzer returned `package: null`, while the Session 03 stub explicitly names `packages/protocol`, `apps/server`, and `apps/web`; CLI diagnostics, docs, and browser evidence are directly affected by the same queue Git product outcome. Planning can proceed as `Package: null` because the work is intentionally cross-cutting and every task uses repo-root-relative paths.
* Existing Git workbench is the execution engine: `GitWorkbenchManager` already validates `CommandCenterGitWorkbenchRequest`, builds allowlisted argv for status, stage, unstage, commit, stash, revert, branch switch, and push, blocks push unless policy is enabled, bounds output, redacts diff-like data, and returns rollback notes. Queue dispatch can connect to those APIs instead of adding a new Git runner.
* Session 02 queue execution patterns are authoritative for this slice: private executable payload storage, public execution summaries, event privacy, duplicate dispatch behavior, route validation, store reconciliation, and queue result rendering should be extended for Git rather than replaced.

### Conflict Resolutions

* Direct Git workbench execution is already real, while queue entries are not yet connected to Git. The chosen interpretation is that direct File/Git execution remains shipped evidence, and this session only claims the new queue-to-Git orchestration path after it reuses the same bounded manager and passes queue acceptance tests.
* `GitWorkbenchManager` supports commit, stash, revert, branch switch, and push, while the Session 03 acceptance checks require status, stage, unstage, and policy-blocked push. The chosen interpretation is to keep protocol and dispatch support compatible with the existing request shape, but validate the session on status, stage, unstage, failed command, and blocked push so scope remains 2-4 hours.

### Key Considerations

* Add shared Git queue contracts before server and web behavior.
* Reuse `GitWorkbenchManager.preview()` and `execute()` exactly so policy, validation, argv construction, timeouts, and redaction do not drift.
* Keep raw Git data scoped to server execution internals and existing bounded workbench responses; broad queue and event surfaces should carry compact summaries only.
* Preserve terminal queue behavior from Session 02 while adding Git branching in shared code.

### Potential Challenges

* `TaskQueueExecutionSummary` is currently terminal-specific; mitigate by generalizing family/kind/link fields while keeping terminal session ids optional and Git-specific recovery fields explicit.
* Store reconciliation currently maps queue-targeted execution runs only for terminal; mitigate by mapping Git runs without inventing terminal drawer links.
* File/Git workbench create-queue controls could duplicate direct execute controls; mitigate with product copy that distinguishes `Create queue task` from direct `Execute`.
* Failed Git output can contain sensitive paths or diff-like content; mitigate with existing workbench redaction plus protocol/web blocked-field tests.

### Relevant Considerations

* \[P19] **Executor claims are family-scoped**: Git queue execution may be marked executable only for allowlisted Git operations with tests and policy states.
* \[P19] **Scoped detail stays separate from broad rows**: Raw prompts, diffs, command bodies, terminal output, transcripts, provider payloads, and absolute paths must stay out of queue/event summaries.
* \[P03-packages/protocol] **Protocol leads cross-package work**: Shared queue executable and execution summary shapes must land before server and web wiring.
* \[P19] **Command-center state is manager-owned**: Idempotency, revisions, cleanup, event emission, and bounded snapshots should stay in managers.
* \[P19] **Do not mark a family executor-ready without gates**: Git queue readiness requires permission/audit posture, redaction, timeout/failure behavior, tests, docs, and release evidence.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* Git queue dispatch could run twice from duplicate clicks or repeated events.
* Policy-blocked push could appear retryable or executable without a policy change.
* Broad queue rows, WebSocket events, diagnostics, or docs could leak raw Git output, diffs, commit messages, patch bodies, or broad paths.

***

## 9. Testing Strategy

### Unit Tests

* Update `packages/protocol/tests/orchestration.test.ts` for Git executable payload parsing, event shape, and blocked raw fields.
* Update `apps/server/tests/taskExecutionCoordinator.test.ts` for Git status, stage, unstage, blocked push, failed command, validation failure, stale revision, and duplicate dispatch with fake Git runners.
* Update `apps/web/tests/orchestrationUi.test.ts` and `apps/web/tests/orchestrationApi.test.ts` for Git queue labels, result summaries, recovery notes, and parser privacy.

### Integration Tests

* Update `apps/server/tests/orchestration.test.ts` for route-level Git queue dispatch, exact event emission, and start-tracking compatibility.
* Update `apps/web/tests/CommandCenterPanes.test.tsx` for integrated queue and File/Git controls.
* Update `apps/web/tests/commandCenterStore.test.ts` for queue-targeted Git execution reconciliation.
* Update `apps/cli/tests/orchestrationDiagnostics.test.js` for compact Git diagnostics.

### Runtime Verification

* Run focused protocol, server, web, CLI, and browser tests for the touched files.
* Run `npm run format:check`, `npm run lint`, `npm run typecheck`, `npm test`, focused Playwright desktop/mobile coverage, `git diff --check`, and ASCII/LF verification over changed files.

### Edge Cases

* Missing executable payload returns a conflict without changing queue state.
* Non-Git payload still routes to the terminal path from Session 02.
* Policy-blocked push returns unavailable and does not call the Git runner.
* Stage, unstage, and revert show inverse or rollback guidance where one exists.
* Failed Git command surfaces bounded failure detail without raw output.
* Duplicate dispatch returns the existing execution run and does not run Git a second time.

***

## 10. Dependencies

### Other Sessions

* Depends on: `phase20-session01-truthful-capability-baseline`, `phase20-session02-queue-terminal-execution`, and `phase19-session08-file-and-git`.
* Depended by: `phase20-session04-campaign-executable-dispatch`, `phase20-session05-campaign-dag-recovery`, `phase20-session06-file-mutation-core`, `phase20-session07-file-executor-integration`, and `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-session03-queue-git-execution/spec.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.