> 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/phase19-session06-executor-registry/spec.md). # Session Specification **Session ID**: `phase19-session06-executor-registry` **Phase**: 19 - Orchestration Command Center Execution **Status**: Not Started **Created**: 2026-06-26 **Package**: null **Package Stack**: mixed TypeScript *** ## 1. Session Overview This session adds the executor registry layer that sits between guarded-action approvals, command-center executor capabilities, and execution run history. It turns the current approved-but-unavailable guarded-action path into a registry-driven decision: executor-ready entries can create bounded execution runs, while non-ready families return explicit capability guidance without claiming success. It is next because Sessions 01 through 05 completed the command-center contracts, server scaffolds, web shell, campaign workbench, and attention or permission approval state. Session 06 is the first point where an approval can be evaluated against family and kind capability before later file, git, provider, hero, terminal, container, collaboration, and channel sessions add concrete family behavior. The scope remains local-first and conservative. This session builds the registry, run lifecycle, product-facing executor cards, and result drawers, but default production entries for file, git, terminal, container, remote, Worker, hosted, channel, subagent, mission, and handoff stay unavailable, observe-only, proposal-only, or approved-not-executing until a later scoped session registers a real adapter with tests, audit, redaction, timeout, and docs. *** ## 2. Objectives 1. Add a server executor registry keyed by guarded-action family and kind with input validation, preview summaries, capability probes, timeout policy, bounded result summaries, cleanup notes, and rollback notes. 2. Route guarded-action approvals through the registry so executor-ready entries create command-center execution runs and non-ready entries return structured repair guidance. 3. Add executor family cards and scoped run-history details in the web command-center Executors tab without exposing raw command bodies, diffs, terminal output, file contents, provider payloads, tokens, or broad paths. 4. Cover ready and non-ready transitions, duplicate-trigger prevention, stale revisions, bounded outputs, event emission, and product-facing UI states with focused server and web tests. *** ## 3. Prerequisites ### Required Sessions * [x] `phase19-session01-protocol-and-events` - Provides command-center executor capability and execution run DTOs, validators, events, REST aliases, and capability states. * [x] `phase19-session02-server-backbone` - Provides command-center manager state, snapshot routes, mutation helpers, WebSocket hydration, diagnostics counts, and executor capability scaffolds. * [x] `phase19-session03-web-shell-and-store` - Provides command-center API helpers, Zustand slices, event reducers, tabs, drawers, and safe UI normalizers. * [x] `phase19-session04-campaign-workbench` - Provides campaign and queue mutation patterns, expected revision checks, idempotency, and workbench UI controls. * [x] `phase19-session05-attention-and-permissions` - Provides audited approval and permission decisions that this session consumes before executor evaluation. ### Required Tools Or Knowledge * Node 26.2.0+ and npm 11.16.0 workspace commands. * Existing guarded-action contracts in `packages/protocol/src/guardedActions.ts`. * Existing command-center executor and execution contracts in `packages/protocol/src/orchestrationCommandCenter.ts`. * Existing server behavior in `apps/server/src/managers/guardedActions.ts`, `apps/server/src/managers/orchestrationCommandCenter.ts`, `apps/server/src/routes/guardedActions.ts`, and `apps/server/src/routes/commandCenter.ts`. * Existing web command-center behavior in `apps/web/src/lib/orchestrationApi.ts`, `apps/web/src/lib/commandCenterUi.ts`, `apps/web/src/store/useGameStore.ts`, and `apps/web/src/components/orchestration/CommandCenterPanes.tsx`. ### Environment Requirements * Run from the repository root with dependencies installed. * No hosted credentials, provider credentials, Cloudflare access, terminal PTY runtime, Docker runtime, remote access, channel webhook secrets, or database service is required. *** ## 4. Scope ### In Scope (MVP) * Operators can see executor family readiness - add registry-backed capability probes and refresh behavior that update command-center executor records with unavailable, observe-only, proposal-only, approved-not-executing, executor-ready, executing, executed, or failed state. * Operators can approve guarded actions without silent overclaiming - approvals call the registry, create an execution run only when the registered entry is executor-ready, and otherwise return repair guidance plus an approved-not-executing or unavailable result. * Server consumers can inspect execution history - command-center execution runs capture family, kind, target, requester, permission request, queued/started/completed timestamps, state, result status, failure code, unavailable reason, and bounded result summaries. * Web users can review executor posture - the Executors tab renders family cards, capability state, requirements, non-ready reasons, and scoped run history with loading, empty, error, offline, and stale states. * Tests prove ready and non-ready behavior - include a safe test registry entry for executor-ready transitions without shipping real file, git, terminal, container, remote, Worker, hosted, or channel execution. ### Out Of Scope (Deferred) * File read/write/edit/delete execution - Reason: Session 08 owns file intent protection and file-family execution. * Git status, commit, push, stash, revert, branch, or conflict execution - Reason: Session 08 owns Git workbench execution and risk guards. * Terminal PTY, shell commands, container runtime, remote access, Worker relay, hosted sync, channel send, provider diagnostics, hero lifecycle execution, mission fork, or handoff execution - Reason: later Phase 19 sessions own those families with separate capability probes, permission gates, audit, redaction, output caps, tests, and docs. * Disk-backed execution-run persistence or database migrations - Reason: current command-center manager state is in-memory, and no database layer is configured in project conventions. * Importing, copying, transforming, or shipping `EXAMPLES/` artifacts - Reason: Phase 19 keeps historical material as traceability evidence only. *** ## 5. Technical Approach ### Architecture Create `apps/server/src/managers/executorRegistry.ts` as the registry boundary. Each entry describes a guarded-action family and kind, input schema behavior, preview summary, capability probe, timeout policy, result summary builder, cleanup note, rollback note, and execute function. The default production registry registers current guarded-action families as non-ready according to existing policy: file, git, terminal, container, remote, Worker, hosted, and channel are unavailable; provider-like checks are observe-only; mission and handoff stay proposal-only. Tests can register a deterministic executor-ready entry to prove the run lifecycle without adding a real product executor. Extend `GuardedActionManager` and `guardedActionsRouter` so approval uses the registry result instead of always returning `unavailableResult`. Approved non-ready actions should retain an approved decision and produce a compact `unavailable`, `failed`, or approved-not-executing result with repair guidance. Approved executor-ready actions should create a command-center execution run, transition through executing and executed or failed states, and emit both `guarded_action_update` and `command_center_execution_update` frames. The route remains responsible for pairing guarded-action changes with command-center run persistence and WebSocket emission. Use existing command-center DTOs for the MVP. `CommandCenterExecutorCapability` and `CommandCenterExecutionRun` already model capability status, requirements, timestamps, result status, failure code, unavailable reason, and bounded result summary. Add narrow helper methods to `OrchestrationCommandCenterManager` for registry probe updates and guarded-action execution runs rather than broad protocol churn. On the web side, add an `ExecutorFamiliesPanel` and run-history detail surface under `apps/web/src/components/orchestration/`. Keep `CommandCenterPanes` as the Executors tab owner, but replace the generic `PaneGrid` for executors with family cards, status copy, requirement lists, and execution history. The panel consumes existing command-center store slices and adds only bounded product-facing text. ### Design Patterns * Registry-owned capability: centralizes readiness, probe, timeout, cleanup, rollback, and result mapping instead of scattering per-route checks. * Manager-owned state: command-center run records stay behind `OrchestrationCommandCenterManager` so counts, snapshots, and broadcasts remain aligned. * Capability-first execution: approval can only execute when an explicit registry entry reports `executor_ready`. * Pure web normalization before rendering: command-center helpers continue filtering blocked payload fields before store or UI display. * Product surface only: executor cards show operator posture and next safe action, not debug dumps or raw developer payloads. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `apps/server/src/managers/executorRegistry.ts` | Registry entry types, default capability registry, probe helpers, execution runner, bounded result mapping, timeout cleanup, and non-ready repair guidance | \~420 | | `apps/server/tests/executorRegistry.test.ts` | Unit tests for ready entry execution, non-ready capability results, timeout/failure mapping, output bounding, cleanup notes, rollback notes, and family/kind mapping | \~260 | | `apps/web/src/components/orchestration/ExecutorFamiliesPanel.tsx` | Product-facing executor capability cards, requirements, run summaries, empty/loading/error/offline states, and selection callbacks | \~300 | | `apps/web/src/components/orchestration/ExecutorRunHistoryDrawer.tsx` | Scoped execution run details with bounded result summary, state metadata, and no raw output rendering | \~180 | | `apps/web/tests/ExecutorFamiliesPanel.test.tsx` | Component tests for executor-ready, unavailable, proposal-only, running, executed, failed, empty, offline, and redaction states | \~220 | ### Files To Modify | File | Changes | Est. Lines | | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `apps/server/src/managers/guardedActions.ts` | Route approval through registry results while preserving create, reject, expire, idempotency, stale revision, and compact guarded-action event behavior | \~180 | | `apps/server/src/managers/orchestrationCommandCenter.ts` | Add execution-run helper methods for guarded-action approvals, capability probe updates, event changes, and bounded history records | \~180 | | `apps/server/src/routes/guardedActions.ts` | Emit paired guarded-action and command-center execution events; prevent duplicate approval triggers while execution is in flight | \~120 | | `apps/server/src/routes/commandCenter.ts` | Add executor probe and execution detail routes with route-id validation, duplicate-trigger protection, and compact errors | \~110 | | `apps/server/src/lib/commandCenterValidation.ts` | Add executor capability route-id, probe, and execution detail validation helpers with explicit error mapping | \~80 | | `apps/server/src/lib/orchestrationDiagnostics.ts` | Report registry readiness, ready/non-ready counts, and recent execution count without raw run payloads | \~60 | | `apps/server/src/server.ts` | Instantiate the default executor registry and inject it into guarded-action and command-center route wiring | \~35 | | `apps/server/tests/guardedActions.test.ts` | Update approval tests for registry-ready execution, non-ready unavailable outcomes, stale revision, duplicate decision, and bounded output behavior | \~170 | | `apps/server/tests/commandCenterManager.test.ts` | Cover execution-run helper persistence, counts, deterministic ordering, and compact event entries | \~120 | | `apps/server/tests/commandCenterRoutes.test.ts` | Cover executor probe and execution detail routes, `/api` aliases, validation, conflicts, and event emission | \~130 | | `apps/server/tests/websocket.test.ts` | Verify paired guarded-action and command-center execution frames on ready and non-ready approval paths | \~90 | | `apps/server/tests/orchestrationDiagnostics.test.ts` | Cover registry readiness counts and compact diagnostics output | \~70 | | `apps/web/src/lib/orchestrationApi.ts` | Add executor probe, execution detail, and refresh helpers with stale/duplicate/offline mapping | \~140 | | `apps/web/src/lib/commandCenterUi.ts` | Add executor family summaries, run-history views, action availability, requirement copy, and redaction helpers | \~180 | | `apps/web/src/components/orchestration/CommandCenterPanes.tsx` | Replace generic executor `PaneGrid` with `ExecutorFamiliesPanel` and run-history selection | \~90 | | `apps/web/src/components/orchestration/OrchestrationDrawer.tsx` | Delegate execution-run selections to the scoped run-history drawer while preserving focus and Escape behavior | \~80 | | `apps/web/src/components/orchestration/index.ts` | Export the executor panel and run-history drawer components | \~10 | | `apps/web/tests/orchestrationApi.test.ts` | Cover executor probe/detail helpers, duplicate guard, stale mapping, bad response, and redacted errors | \~120 | | `apps/web/tests/commandCenterUi.test.ts` | Cover executor summary copy, run-history views, redaction, and action availability | \~130 | | `apps/web/tests/commandCenterStore.test.ts` | Cover execution and executor event reducers clearing in-flight keys and preserving existing state on malformed frames | \~100 | | `apps/web/tests/OrchestrationPanel.test.tsx` | Cover Executors tab integration, scoped detail opening, keyboard selection, loading, empty, error, and product-facing copy states | \~150 | | `docs/api/README_api.md` | Document registry-backed approval behavior, executor probe routes, run history, and non-ready family boundaries | \~100 | | `docs/api/event-api-hook-contracts.md` | Update route/event reconciliation for paired guarded-action and command-center execution updates | \~100 | | `apps/server/README_server.md` | Document default registry policy, local-only execution boundary, and test-only ready adapter posture | \~90 | | `apps/web/README_web.md` | Document Executors tab behavior, visible non-ready states, and no raw output rendering | \~90 | *** ## 7. Success Criteria ### Functional Requirements * [ ] The server has a default executor registry keyed by guarded-action family and kind with capability status, probe behavior, timeout policy, cleanup note, rollback note, and bounded result mapping. * [ ] Approved executor-ready guarded actions create a command-center execution run, emit final result state, update guarded-action state, and emit paired WebSocket events. * [ ] Approved non-ready guarded actions return structured repair guidance and do not claim executed success. * [ ] Execution history is visible from command-center executor family cards and scoped run-history details. * [ ] Broad rows and cards never expose raw command bodies, diffs, terminal output, file contents, provider payloads, tokens, secrets, broad absolute paths, replay buffers, exports, or hosted account data. ### Testing Requirements * [ ] Unit tests cover registry ready, non-ready, timeout, failure, output bounding, cleanup, rollback, and family/kind mapping behavior. * [ ] Server route tests cover guarded-action approval, executor probes, execution history, `/api` aliases, duplicate triggers, stale revisions, and compact errors. * [ ] Web API, store, UI helper, and component tests cover executor cards, run details, malformed frames, loading, empty, offline, stale, failed, and executed states. * [ ] `npm --workspace apps/server run typecheck` passes. * [ ] `npm --workspace apps/web run typecheck` passes. * [ ] Focused server and web Vitest targets pass for executor registry, guarded actions, command-center routes, WebSocket events, command-center UI, store, and panel behavior. ### Non-Functional Requirements * [ ] Registry and execution paths stay local-first and do not add hosted transfer, remote execution, Worker relay, terminal PTY, Docker runtime, database, file mutation, or Git mutation. * [ ] Execution runs are bounded, deterministic, redacted, and sorted for repeatable route, event, store, and UI behavior. * [ ] State-mutating approval and probe paths prevent duplicate triggers while in flight and preserve idempotency behavior. * [ ] Web executor controls are keyboard-accessible, screen-reader labeled, focus-safe, and product-facing. ### Quality Gates * [ ] All files ASCII-encoded * [ ] Unix LF line endings * [ ] Code follows project conventions * [ ] Primary user-facing surfaces contain product-facing copy only *** ## 8. Implementation Notes ### Working Assumptions * Package context is cross-cutting, so `Package: null` is intentional. The analysis script reports `package: null`, the stub names `apps/server` and `apps/web`, and the current implementation must coordinate server approval behavior, command-center run state, web executor surfaces, and docs. Planning can proceed because no single package owns the whole executor-registry contract. * Existing command-center DTOs are sufficient for the MVP. `CommandCenterExecutorCapability` and `CommandCenterExecutionRun` already carry status, requirements, timestamps, result status, bounded result summary, failure code, unavailable reason, and event shapes. Narrow server helper work is safer than broad protocol changes unless implementation proves a missing parser field. * Production registry entries should default to non-ready until a later scoped session registers a real adapter. The Session 06 objective is the registry and run lifecycle; Session 08 and later sessions own concrete file, git, terminal, container, remote, channel, provider, hero, and collaboration executors. * Executor-ready transition behavior can be validated through a safe test registry entry. This proves approval-to-run mechanics, idempotency, event emission, and result persistence without shipping a real product executor ahead of its family-specific session. ### Conflict Resolutions * Current docs say approved guarded actions do not execute, while Phase 19 Session 06 requires executor-ready approval to produce execution runs. This plan resolves the conflict by adding a registry-gated execution path: only entries that explicitly report `executor_ready` can run, and all current concrete families remain non-ready by default. * The session stub asks for execution run persistence, while project conventions say no database is configured and current command-center state is in-memory. This plan interprets persistence as manager-owned in-memory run history for this session, matching current command-center manager behavior. * Historical `EXAMPLES/` inventories show guarded executor routes and hooks, while the active PRD says `EXAMPLES/` is traceability evidence only. This plan uses current protocol, server, web, and docs as implementation truth and keeps historical code out of runtime files. ### Key Considerations * Approval is still not blanket execution. The registry must fail closed unless a family and kind are explicitly executor-ready. * Non-ready outcomes should help the operator repair or understand capability posture without claiming tool execution. * Bounded summaries are the only broad execution result payload allowed; raw command, diff, terminal, file, provider, transcript, and artifact content stays out of cards, events, logs, and broad routes. ### Potential Challenges * Guarded-action and command-center state can drift: Mitigate by generating guarded-action result and command-center execution run from one registry result and emitting paired events in one route path. * Registry infrastructure can accidentally become a concrete executor: Mitigate by defaulting production entries to non-ready and restricting ready behavior to explicit adapters. * UI run history can overexpose detail: Mitigate by building dedicated run-view helpers that only render bounded fields from `CommandCenterExecutionRun`. * Duplicate approvals can create duplicate runs: Mitigate with existing guarded-action idempotency keys plus registry/run idempotency and route-level in-flight keys. ### Relevant Considerations * \[P03] **Real executors remain unimplemented by design**: This session adds registry infrastructure and readiness gates without shipping concrete file, git, terminal, remote, or container execution. * \[P03-apps/server] **Local server boundary must stay conservative**: New approval and probe paths must preserve validation, local auth, rate limiting, body caps, CORS/origin checks, and explicit unavailable behavior. * \[P07] **Redaction is boundary-specific**: Registry results, guarded-action responses, execution runs, WebSocket frames, diagnostics, web cards, drawers, and docs each need separate minimization. * \[P18-apps/server] **Manager-owned persistence and snapshot emission**: Execution run history should stay behind command-center manager helpers so filtering, counts, and broadcasts stay aligned. * \[P18-apps/web] **Pure normalization before store mutation**: Executor and execution event payloads should be normalized before Zustand updates. * \[P18-apps/web] **Pointer and keyboard actions should share store methods**: Executor card controls and drawer actions should use shared in-flight state and cleanup paths. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Approving a non-ready guarded action could be misread as successful execution. * Ready approval could create duplicate execution runs under repeated clicks, repeated WebSocket messages, or reused idempotency keys. * Execution summaries could leak raw local developer payloads if registry results bypass command-center redaction. *** ## 9. Testing Strategy ### Unit Tests * Test registry entry lookup, family/kind mapping, capability probe results, ready execution, non-ready unavailable results, timeout failures, cleanup notes, rollback notes, output bounding, and redaction in `apps/server/tests/executorRegistry.test.ts`. * Test guarded-action manager approval states for ready, non-ready, rejected, expired, stale, duplicate, and failed execution paths in `apps/server/tests/guardedActions.test.ts`. * Test command-center manager execution run helpers, counts, sorting, compact event entries, and bounded summaries in `apps/server/tests/commandCenterManager.test.ts`. * Test web executor summary helpers, status copy, requirement copy, redaction, run-history views, and action availability in `apps/web/tests/commandCenterUi.test.ts`. ### Integration Tests * Test guarded-action routes create paired command-center execution events for executor-ready entries and compact unavailable results for non-ready entries. * Test command-center executor probe and execution detail routes at both root and `/api` prefixes with invalid ids, stale revisions, duplicate in-flight requests, and compact errors. * Test WebSocket hydration and mutation frames include executor and execution updates without raw payload fields. * Test `ExecutorFamiliesPanel`, `ExecutorRunHistoryDrawer`, and `OrchestrationPanel` Executors tab for loading, empty, offline, unavailable, proposal-only, executor-ready, executing, executed, failed, and keyboard/focus states. ### Runtime Verification * Run `npm --workspace apps/server run typecheck`. * Run `npm --workspace apps/web run typecheck`. * Run focused Vitest targets for server executor registry, guarded actions, command-center manager, command-center routes, WebSocket events, web command-center UI, command-center store, executor panel, and Orchestration panel. * Run `npm run lint`, `npm run format:check`, `git diff --check`, and ASCII/LF validation on touched files. ### Edge Cases * Unknown guarded-action family or kind reaches the registry. * Capability probe times out or throws. * Ready executor throws after creating a queued run. * Result summary contains tokens, absolute paths, URLs, terminal output, diffs, or file contents. * Approval expected revision is stale. * Approval idempotency key is reused for the same action or another action. * Route receives duplicate approval while run creation is in flight. * Execution history is empty, malformed, failed, unavailable, or partially hydrated. * Web drawer is reopened after the selected run disappears from store state. *** ## 10. Dependencies ### Other Sessions * Depends on: `phase19-session01-protocol-and-events`, `phase19-session02-server-backbone`, `phase19-session03-web-shell-and-store`, `phase19-session04-campaign-workbench`, `phase19-session05-attention-and-permissions` * Depended by: `phase19-session07-provider-diagnostics`, `phase19-session08-file-and-git`, `phase19-session09-heroes-and-lineage`, `phase19-session10-mission-artifacts`, `phase19-session12-terminal-and-containers`, `phase19-session13-collaboration-and-handoff`, `phase19-session14-channels-and-scope`, and `phase19-session15-metrics-and-notifications` *** ## 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/phase19-session06-executor-registry/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.