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

# Session 06: Executor Registry

**Session ID**: `phase19-session06-executor-registry` **Packages**: apps/server, apps/web **Status**: Not Started **Estimated Tasks**: \~12-25 **Estimated Duration**: 2-4 hours

***

## Objective

Make guarded actions executable through explicit family capabilities and execution runs.

***

## Scope

### In Scope (MVP)

* Executor registry keyed by family/kind with input schema, preview renderer, capability probes, timeout, result schema, cleanup notes, and rollback notes
* Capability states for unavailable, observe-only, proposal-only, approved-not-executing, executor-ready, executing, executed, and failed
* Approval-to-execution transition for executor-ready families
* Execution run persistence, event emission, run history, bounded output summaries, and scoped result drawers
* Tests for state transitions, unsupported family errors, bounded outputs, and event emission

### Out of Scope

* Full implementation of each concrete executor family
* Terminal PTY, container isolation, or remote access behavior

***

## Prerequisites

* [ ] Sessions 01, 02, 03, and 05 complete
* [ ] Current guarded action protocol and server decision flow inspected

***

## Deliverables

1. Executor registry and execution run routes
2. Capability probe and preview abstractions
3. Executor family cards and run-history drawers
4. Tests for ready and non-ready execution decisions

***

## Source Coverage And Evidence

Source coverage:

* Session Split Plan Session 06: Executor Registry
* Implementation Target 4: Evolve Guarded Actions Into Executable Families
* Balls-To-The-Wall Track B `executorRegistry` routes
* Execution Family Order items for file/git, subagent/mission/handoff, terminal, container, remote access, and channel-created command intake

Key EXAMPLES links:

* [Architecture executors](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/architecture.md#L140-L195)
* [Guarded route inventory](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L42-L115)
* [Bash command hook](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-bash-command.sh#L15-L38)
* [File access hook](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-file-access.sh#L27-L116)
* [Git guard hook](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-git-guard.sh#L1-L98)

***

## Success Criteria

* [ ] Executor-ready approval creates an execution run and final result state
* [ ] Non-ready families return visible repair guidance and do not claim success
* [ ] Execution history is visible from guarded actions and family cards
* [ ] Broad rows avoid raw command bodies, diffs, terminal output, and artifacts


---

# 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_19/session_06_executor_registry.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.