> 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-session10-templates-and-channel-intake/spec.md).

# Session Specification

**Session ID**: `phase20-session10-templates-and-channel-intake` **Phase**: 20 - Orchestration Actionability Execution **Status**: Not Started **Created**: 2026-06-28 **Package**: null **Package Stack**: mixed TypeScript across `packages/protocol`, `apps/server`, and `apps/web`

***

## 1. Session Overview

This session makes source-owned templates and inbound channel commands create reviewable executable local queue tasks without turning remote input into trusted execution. It follows Phase 20 sessions 01-09, which validated the terminal, Git, campaign, file, managed-agent, and container executor slices that this session can now reference through the shared queue executable contract.

The work is next because session 10 is the first incomplete Phase 20 candidate and it is the last feature slice before release-wide evidence and event privacy closeout. The implementation must keep webhook arrival proposal-first, preserve replay idempotency, and let local operator approval be the point where an executable queue task is created or dispatched.

The planned changes are cross-package: protocol extends bounded template/channel metadata, the server owns validation, idempotency, queue creation, and guarded proposal behavior, and the web app exposes truthful product labels for record, review task, executable local task, and execute states.

***

## 2. Objectives

1. Let local templates preview and create executable queue tasks only when the template declares a known local executor with bounded inputs.
2. Keep inbound webhook and remote channel deliveries proposal-first on arrival, with no automatic dispatch or remote-trust claim.
3. Add a local operator-approved path from a stored channel command or guarded proposal to an executable queue task that still dispatches through the existing coordinator and capability checks.
4. Update web labels, disabled states, duplicate-trigger guards, and tests so template/channel actions do not overclaim execution.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase20-session02-queue-terminal-execution` - Provides terminal queue dispatch through `TaskExecutionCoordinator`.
* [x] `phase20-session03-queue-git-execution` - Provides bounded Git queue dispatch.
* [x] `phase20-session04-campaign-executable-dispatch` - Provides shared campaign-to-queue executable semantics.
* [x] `phase20-session06-file-mutation-core` - Provides bounded file mutation request/result contracts.
* [x] `phase20-session07-file-executor-integration` - Provides queue and guarded file executor integration.
* [x] `phase20-session08-managed-agent-lifecycle-control` - Provides truthful local managed-agent lifecycle control boundaries.
* [x] `phase20-session09-container-dispatch-decision` - Provides bounded container queue and campaign dispatch posture.

### Required Tools Or Knowledge

* Node 26.2.0+ and npm 11.16.0 workspace commands.
* Vitest coverage for protocol, server, and web packages.
* Existing command-center executable payload, queue dispatch, guarded action, and channel command contracts.

### Environment Requirements

* Local repository checkout with npm dependencies installed.
* No hosted credentials, GitHub webhook signatures, remote execution, or external provider access required.

***

## 4. Scope

### In Scope (MVP)

* Local operator can preview and create a template-derived executable queue task - Implement by adding bounded executable defaults to source-owned local templates and preserving the payload from preview through queue create.
* Local operator can convert a stored channel command into a review task or executable local queue task - Implement through server-owned local mutation routes, not untrusted webhook body flags.
* Webhook and remote channel deliveries stay proposal-first by default - Reject or downgrade unsafe executable payload attempts into proposal or attention state without dispatch.
* Guarded channel proposals can reference executable drafts - Execution still flows through existing coordinator or truthful unavailable/proposal-only states after local approval.
* Web Command Center separates product labels - Use distinct copy for `Record inbound command`, `Create review task`, `Create executable local task`, and `Execute`, with accessibility labels and in-flight guards.
* Duplicate delivery and duplicate mutation attempts are idempotent - Existing replay records and mutation keys must return prior records without re-execution.

### Out Of Scope (Deferred)

* Automatic execution of webhook, GitHub, Telegram, Discord, Worker, remote, or hosted channel content - Reason: Phase 20 explicitly requires local approval before execution.
* GitHub signature verification, hosted channel trust, production identity, or remote authorization claims - Reason: Session 10 is local proposal-first intake, not hosted trust.
* New executor families beyond existing local queue executable payload families - Reason: Session 10 converges existing terminal, Git, file, container, and supported local lifecycle behavior.
* Release-wide event privacy and docs claim audit - Reason: Session 11 owns release evidence and event privacy closeout.

***

## 5. Technical Approach

### Architecture

Protocol remains first. Add bounded template executable metadata and any channel/guarded executable draft references in shared types and parsers before server or web consumers rely on them. Reuse `TaskQueueExecutablePayload` instead of introducing a second executable shape.

Server behavior should keep untrusted intake separated from local operator mutation. Webhook parsing must not trust request fields that claim approval or submit runnable executables. Stored channel records may later be converted by an explicit local route into a queue entry, using manager-owned idempotency keys, safe source attribution, existing queue payload parsers, and broadcaster updates.

Web behavior should make the execution boundary visible. Template preview/create controls may show executable-local-task copy only when the preview contains a safe executable payload. Channel controls must distinguish recording, review-task creation, executable-task creation, and queue dispatch, and disabled states must explain unavailable, proposal-only, offline, and in-flight conditions.

### Design Patterns

* Protocol-first contracts: Shared executable payload and channel metadata changes land in `packages/protocol` before server and web wiring.
* Manager-owned mutation: Channel conversion, idempotency, replay, and queue creation stay in `ChannelCommandManager` and `TaskQueueManager`, not in UI-only state.
* Broad-summary and scoped-detail split: Broad rows and WebSocket frames show labels and ids only, not webhook raw bodies, commands, output, diffs, file contents, or provider payloads.
* Capability-aware verbs: UI action labels use `Execute` only for ready executable tasks; proposal and review paths keep proposal/review wording.

***

## 6. Deliverables

### Files To Create

No new source files are expected. Extend existing protocol, server, web, and test files.

### Files To Modify

| File                                                            | Changes                                                                                                 | Est. Lines |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ---------- |
| `packages/protocol/src/agentTemplates.ts`                       | Add bounded optional executable defaults for local templates.                                           | \~60       |
| `packages/protocol/src/orchestrationCommandCenter.ts`           | Add safe channel executable draft/local approval metadata where needed.                                 | \~90       |
| `packages/protocol/src/taskQueue.ts`                            | Reuse or tighten queue executable parser/source attribution for template and channel sources.           | \~40       |
| `packages/protocol/src/index.ts`                                | Export any new shared protocol symbols.                                                                 | \~10       |
| `packages/protocol/tests/orchestration.test.ts`                 | Cover executable template defaults and blocked raw fields.                                              | \~80       |
| `packages/protocol/tests/orchestrationCommandCenter.test.ts`    | Cover channel executable draft metadata and blocked webhook fields.                                     | \~80       |
| `apps/server/src/managers/agentTemplates.ts`                    | Seed source-owned executable defaults only for bounded local executors.                                 | \~70       |
| `apps/server/src/lib/templatePlanningContext.ts`                | Preserve executable defaults in template preview and source attribution.                                | \~90       |
| `apps/server/src/lib/orchestrationValidation.ts`                | Parse template queue create/preview intent without accepting unsafe executable input.                   | \~60       |
| `apps/server/src/routes/orchestration.ts`                       | Preserve template executable payloads through preview and create.                                       | \~60       |
| `apps/server/src/lib/channelCommandValidation.ts`               | Reject remote executable claims and normalize proposal-first channel input.                             | \~80       |
| `apps/server/src/managers/channelCommandManager.ts`             | Add operator-approved queue/executable conversion and guarded executable references with idempotency.   | \~150      |
| `apps/server/src/routes/channelCommands.ts`                     | Wire local conversion routes, broadcasts, and duplicate-trigger handling.                               | \~100      |
| `apps/server/tests/templatePlanningContext.test.ts`             | Prove template preview/create executable preservation.                                                  | \~90       |
| `apps/server/tests/channelCommandManager.test.ts`               | Prove no auto-execution, local executable conversion, and replay idempotency.                           | \~120      |
| `apps/server/tests/channelCommandRoutes.test.ts`                | Prove route behavior, broadcasts, and raw payload rejection.                                            | \~140      |
| `apps/web/src/lib/orchestrationApi.ts`                          | Add typed client calls and response validation for channel conversion and executable template previews. | \~120      |
| `apps/web/src/lib/commandCenterUi.ts`                           | Add safe labels and action availability for template/channel executable states.                         | \~90       |
| `apps/web/src/store/useGameStore.ts`                            | Store executable preview/conversion state and in-flight keys without stale detail leaks.                | \~70       |
| `apps/web/src/components/orchestration/TemplateWorkbench.tsx`   | Show executable preview/create labels, disabled states, and accessible controls.                        | \~100      |
| `apps/web/src/components/orchestration/ChannelCommandPanel.tsx` | Show record/review/executable/execute labels and conversion controls.                                   | \~120      |
| `apps/web/tests/OrchestrationPanel.test.tsx`                    | Cover user-facing template/channel labels and duplicate guards.                                         | \~120      |
| `apps/web/tests/ChannelCommandPanel.test.tsx`                   | Cover channel action labels, disabled states, and safe details.                                         | \~100      |
| `tests/e2e/orchestration-command-center.e2e.ts`                 | Cover generated executable task dispatch result for template/channel intake.                            | \~100      |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Template preview -> create -> dispatch preserves a bounded executable default and produces a real local execution result or truthful unavailable result.
* [ ] Webhook conversion cannot execute on arrival.
* [ ] Channel-to-queue executable payload remains queued until a local operator dispatches it.
* [ ] Invalid or unsafe executable payloads become proposal, attention, validation, or unavailable state, not runnable tasks.
* [ ] Duplicate delivery and duplicate conversion return prior records without duplicate execution.

### Testing Requirements

* [ ] Protocol tests cover template executable defaults, channel executable metadata, and blocked raw fields.
* [ ] Server tests cover template preview/create/dispatch, channel no-auto-execute, local conversion, guarded proposal, and replay idempotency.
* [ ] Web tests cover truthful labels, disabled states, accessibility labels, and duplicate in-flight prevention.
* [ ] Browser e2e covers generated template or channel task dispatch result.

### Non-Functional Requirements

* [ ] Broad REST rows and WebSocket frames do not include raw webhook bodies, command bodies, terminal output, Git output, diffs, file contents, patches, tokens, secrets, provider payloads, or broad absolute paths.
* [ ] Mutation paths use idempotency keys and in-flight guards for preview, create, conversion, guarded approval, and dispatch.
* [ ] Local-first and no-claim boundaries remain visible for remote, hosted, and untrusted channel content.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] Primary user-facing surfaces contain product-facing copy only.
* [ ] `npm --workspace packages/protocol run typecheck` passes.
* [ ] `npm --workspace apps/server run typecheck` passes.
* [ ] `npm --workspace apps/web run typecheck` passes.
* [ ] Focused Vitest and Playwright coverage for this slice passes.
* [ ] `git diff --check` passes.

***

## 8. Implementation Notes

### Working Assumptions

* Cross-package package context: The session stub names `packages/protocol`, `apps/server`, and `apps/web`, and the analyzer has no active package. Planning proceeds as cross-cutting with `Package: null`.
* Executor prerequisites are satisfied: The analyzer reports Phase 20 sessions 02-09 complete, and the phase PRD records validated terminal, Git, campaign, file, managed-agent, and container slices. Session 10 can safely reference the existing queue executable payload families.
* Local approval cannot be represented by untrusted webhook body fields: `channelCommandValidation.ts` currently parses webhook bodies directly from remote requests, so local operator approval must be a separate local mutation against a stored command record.

### Key Considerations

* \[P19] **Channel intake is proposal-first**: Webhook and remote channel input can create reviewable records, attention, or guarded proposals, but not trusted automatic execution.
* \[P03-packages/protocol] **Protocol leads cross-package work**: Shared executable and channel metadata must be protocol-owned before server and web code consume it.
* \[P19] **Command-center state is manager-owned**: Idempotency, revisions, event emission, and bounded snapshots belong in managers.
* \[P19] **Scoped detail stays separate from broad rows**: Raw webhook bodies, command bodies, terminal output, diffs, file contents, provider payloads, secrets, tokens, and broad paths must stay out of summaries and events.

### Potential Challenges

* Distinguishing local approval from remote claims: Add an explicit local route/mutation and ignore or reject remote approval/executable fields.
* Avoiding hidden execution on replay: Reuse replay maps and idempotency keys so duplicate deliveries update the stored command record only.
* Keeping template defaults bounded: Store executable defaults only on source-owned local templates and parse them through `parseTaskQueueExecutablePayload`.
* Web label drift: Centralize action availability and labels in existing UI helpers where possible, then assert product-facing copy in tests.

### Relevant Considerations

* \[P19] **Executor claims are family-scoped**: Do not mark channel/template paths executor-ready unless they dispatch through a proved local family.
* \[P19] **Shared idempotency keys reduce drift**: Use stable keys for server mutations and web in-flight state.
* \[P19] **Proposal-first channel intake**: Preserve this pattern while adding local conversion.
* \[P19] **Parser-level redaction plus store normalization**: Reject blocked raw fields before manager/store mutation and normalize labels before UI display.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* Untrusted webhook input could smuggle an executable payload or fake local approval.
* Duplicate delivery or duplicate clicks could create multiple queue entries or execution runs.
* UI copy could imply execution before the task is locally approved, queued, and dispatchable.
* Broad rows or events could leak webhook raw bodies, command text, diffs, output, tokens, or broad paths.

***

## 9. Testing Strategy

### Unit Tests

* Protocol parser tests for template executable defaults, channel executable draft references, source attribution, and blocked raw payload fields.
* Server manager tests for template preview executable preservation, channel local conversion, guarded proposal references, idempotency, and replay behavior.
* Web helper/store tests for action labels, in-flight keys, preview state, and safe label normalization.

### Integration Tests

* Server route tests for `/webhooks/generic`, `/webhooks/github`, `/channel-commands`, local conversion routes, `/agent-templates/queue-preview`, `/agent-templates/queue`, and `/task-queue/:id/dispatch`.
* Web component tests for TemplateWorkbench and ChannelCommandPanel product labels, disabled states, and duplicate-trigger prevention.

### Runtime Verification

* Use a bounded local template executable default to create a queue task, dispatch it, and observe the execution result in queue/execution state.
* Ingest the same webhook delivery twice and verify only the channel replay count changes while queue/execution counts do not duplicate.
* Try unsafe executable or raw payload fields through webhook intake and verify bounded errors or proposal/attention state without runnable queue creation.

### Edge Cases

* Offline web state disables template/channel mutations and keeps visible empty/error copy.
* Stale revisions and duplicate idempotency keys return conflict or duplicate results without extra execution.
* Unknown executor family, unsafe payload, malformed scope label, or remote approval claim fails closed.
* Guarded channel approval with unavailable capability records unavailable/proposal-only state instead of success.

***

## 10. Dependencies

### Other Sessions

* Depends on: `phase20-session02-queue-terminal-execution`, `phase20-session03-queue-git-execution`, `phase20-session04-campaign-executable-dispatch`, `phase20-session06-file-mutation-core`, `phase20-session07-file-executor-integration`, `phase20-session08-managed-agent-lifecycle-control`, `phase20-session09-container-dispatch-decision`.
* Depended by: `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-session10-templates-and-channel-intake/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.