> 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-session11-release-evidence-and-event-privacy/spec.md).

# Session Specification

**Session ID**: `phase20-session11-release-evidence-and-event-privacy` **Phase**: 20 - Orchestration Actionability Execution **Status**: Not Started **Created**: 2026-06-29 **Package**: null **Package Stack**: mixed TypeScript across `packages/protocol`, `apps/server`, and `apps/web`

***

## 1. Session Overview

This session closes Phase 20 by proving the shipped orchestration paths end to end and aligning release claims with the behavior already implemented in Sessions 01-10. It is next because the analyzer reports all earlier Phase 20 sessions complete and the only remaining candidate is the release evidence and event privacy closeout.

The session does not introduce a new executor family. It consolidates evidence for terminal, Git, campaign DAG, file mutation, guarded action, managed hero lifecycle, container, template, and channel intake paths, then strengthens privacy regressions for broad events, rows, exports, diagnostics, examples, and docs.

The implementation is cross-cutting. Protocol tests confirm safe public contracts, server tests confirm state and event semantics, web tests confirm truthful labels and broad-row privacy, Playwright confirms visible product execution/recovery, and stable docs record exactly which execution claims are shipped, unavailable, proposal-only, or approved-not-executing.

***

## 2. Objectives

1. Record a release evidence matrix that maps every Phase 20 shipped path to protocol, server, web, browser, and documentation evidence.
2. Verify queue and campaign state semantics for queued, in progress, completed, blocked, failed, and unavailable outcomes.
3. Add or tighten regressions that prevent raw commands, terminal output, Git output, diffs, file contents, patches, tokens, secrets, absolute paths, provider payloads, and webhook bodies from broad surfaces.
4. Update stable docs and release wording so action verbs appear only for proved local execution paths and remaining families stay unavailable, proposal-only, or approved-not-executing.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase20-session01-truthful-capability-baseline` - Provides truthful capability labels and non-executing state vocabulary.
* [x] `phase20-session02-queue-terminal-execution` - Provides terminal queue dispatch and scoped terminal evidence.
* [x] `phase20-session03-queue-git-execution` - Provides bounded Git queue dispatch and policy-blocked unavailable behavior.
* [x] `phase20-session04-campaign-executable-dispatch` - Provides campaign-to-queue executable dispatch.
* [x] `phase20-session05-campaign-dag-recovery` - Provides dependency ordering, blocked states, partial failure, and retry behavior.
* [x] `phase20-session06-file-mutation-core` - Provides file mutation preview, apply, audit, backup, and rollback manager behavior.
* [x] `phase20-session07-file-executor-integration` - Provides guarded, queue, and campaign file execution integration.
* [x] `phase20-session08-managed-agent-lifecycle-control` - Provides supported owned-session lifecycle control and observed-only unavailable behavior.
* [x] `phase20-session09-container-dispatch-decision` - Provides bounded container dispatch posture and unavailable states.
* [x] `phase20-session10-templates-and-channel-intake` - Provides source-owned template and proposal-first channel intake conversion.

### Required Tools Or Knowledge

* Node 26.2.0+ and npm 11.16.0 workspace commands.
* Vitest coverage for `packages/protocol`, `apps/server`, and `apps/web`.
* Playwright command-center browser coverage in `tests/e2e/orchestration-command-center.e2e.ts`.
* Current command-center privacy boundaries in `CONSIDERATIONS.md`, `SECURITY-COMPLIANCE.md`, `docs/api/README_api.md`, and `docs/privacy-and-security.md`.

### Environment Requirements

* Local repository checkout with npm dependencies installed.
* No hosted credentials, Cloudflare dashboard access, production hosted app shell, remote execution, or external provider access required.
* Optional PTY, Docker, and Apple Containers availability may be absent; absent runtime dependencies must produce truthful unavailable evidence, not failed release claims.

***

## 4. Scope

### In Scope (MVP)

* Operator can trace release evidence for terminal, Git, campaign DAG, file mutation, guarded action, hero lifecycle, container, template, and channel intake paths - Implement with a session-owned release evidence matrix and focused test references.
* Queue and campaign state semantics match real execution outcomes - Verify completed only from executed results, blocked for validation/dependency/approval stops, failed for failed execution, and unavailable for unavailable capability.
* Broad REST rows, WebSocket events, exports, diagnostics, examples, docs, and web rows stay privacy-safe - Add tests and docs checks for blocked raw field categories.
* Browser Command Center e2e proves create or approve, dispatch or execute, observe, and recover flows for shipped paths where local runtime gates allow, and truthful unavailable evidence where gates are absent.
* Stable docs and release wording separate shipped local execution from unsupported, proposal-only, approved-not-executing, no-claim, and unavailable behavior.

### Out Of Scope (Deferred)

* Shipping any new executor family or expanding remote, hosted, Worker-bridged, or production-channel execution - Reason: Session 11 is evidence and privacy closeout, not a new capability slice.
* Closing hosted identity, trusted unified erasure, production-hosted validation, authorized Cloudflare deploy evidence, or formal legal/privacy approval - Reason: those cumulative findings remain no-claim until separate scoped evidence exists.
* Adding GitHub signature verification, hosted channel trust, public collaboration safety, push delivery, or remote tunnel behavior - Reason: current channel intake remains local and proposal-first.
* Making PTY, Docker, Apple Containers, provider credentials, or Cloudflare credentials mandatory for core release gates - Reason: optional dependencies must fail closed with unavailable states.

***

## 5. Technical Approach

### Architecture

Keep this session evidence-led. The release matrix should reference existing contract, manager, component, and e2e tests instead of adding a parallel release framework. Where evidence is weak, add focused regressions to the package that owns the behavior: protocol for public shape and redaction parsers, server for state transitions and event emissions, web for broad-row labels and action availability, and Playwright for visible product flows.

Server state checks should stay manager-owned and route-level. Queue dispatch, campaign dispatch, guarded approvals, file rollback, hero lifecycle controls, container runs, and channel/template conversion should continue to flow through existing managers and `TaskExecutionCoordinator`. No task should bypass idempotency, expected revisions, capability gates, or scoped-detail privacy boundaries for test convenience.

Docs updates should narrow claims rather than broaden them. Release docs may claim Phase 20 local orchestration execution only for families with validated local executor paths and evidence. Unsupported, proposal-only, approved-not-executing, no-claim, hosted, remote, Worker command bridge, and production-channel behaviors must remain explicit.

### Design Patterns

* Evidence matrix: One session-owned Markdown ledger maps paths to commands, tests, docs, and unsupported boundaries.
* Protocol-first privacy: Public event and DTO parser tests reject or redact blocked raw field categories before server/web code consumes them.
* Manager-owned state semantics: Queue and campaign completion derive from execution result state, not metadata or preview records.
* Broad-summary and scoped-detail split: Broad rows and events expose ids, safe labels, counts, summaries, and scoped links; sensitive details stay request-scoped or local detail-only.
* Product-facing UI labels: Web action verbs reflect dispatchable or executable state only; unavailable and proposal paths keep explicit non-executing copy.

***

## 6. Deliverables

### Files To Create

| File                                                                                          | Purpose                                                                                                             | Est. Lines |
| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ---------- |
| `.spec_system/specs/phase20-session11-release-evidence-and-event-privacy/release-evidence.md` | Release evidence matrix, unsupported-path register, command results, and privacy audit notes for Phase 20 closeout. | \~180      |

### Files To Modify

| File                                                           | Changes                                                                                                                 | Est. Lines |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------- |
| `packages/protocol/tests/orchestration.test.ts`                | Tighten executable queue contract coverage for blocked raw fields and family-safe public summaries.                     | \~60       |
| `packages/protocol/tests/orchestrationCommandCenter.test.ts`   | Tighten command-center event/update privacy coverage for execution, channel, template, and capability summaries.        | \~90       |
| `packages/protocol/README_protocol.md`                         | Update Phase 20 command-center ownership, shipped executor family boundaries, and no-claim language.                    | \~80       |
| `apps/server/tests/taskExecutionCoordinator.test.ts`           | Verify terminal, Git, file, guarded, and unavailable coordinator outcomes map to safe queue/execution evidence.         | \~90       |
| `apps/server/tests/taskExecutionCoordinator.container.test.ts` | Verify container dispatch unavailable/failure/success evidence stays compact and privacy-safe.                          | \~70       |
| `apps/server/tests/planCampaignExecutableDispatch.test.ts`     | Verify campaign completion cannot come from metadata-only work and broad responses exclude private executable payloads. | \~80       |
| `apps/server/tests/planCampaignDagRecovery.test.ts`            | Verify dependency blocking, failed/unavailable retry, and campaign state semantics across recovery paths.               | \~90       |
| `apps/server/tests/fileMutationManager.test.ts`                | Verify apply, rollback, stale hash, conflict, and privacy evidence for file mutation closeout.                          | \~70       |
| `apps/server/tests/managedAgentSessionManager.test.ts`         | Verify owned-session stop/restart/message evidence and observed-only unavailable boundaries.                            | \~60       |
| `apps/server/tests/channelCommandRoutes.test.ts`               | Verify proposal-first intake, no auto-execution, replay idempotency, and blocked raw webhook fields.                    | \~80       |
| `apps/server/tests/commandCenterRoutes.test.ts`                | Add broad event/row privacy assertions for execution, diagnostics, evidence, and unsupported capability paths.          | \~100      |
| `apps/server/tests/exportRoute.test.ts`                        | Verify release-relevant exports redact command, terminal, diff, path, token, and transcript-sensitive values.           | \~60       |
| `apps/web/tests/QueueWorkbench.test.tsx`                       | Verify queue row state labels, retry/unavailable copy, scoped links, and no raw execution detail in broad rows.         | \~80       |
| `apps/web/tests/CampaignWorkbench.test.tsx`                    | Verify campaign graph execution states, blocked/retry labels, and product-facing action verbs.                          | \~80       |
| `apps/web/tests/FileGitWorkbench.test.tsx`                     | Verify Git/file visible results, rollback/unavailable labels, and broad-row redaction.                                  | \~70       |
| `apps/web/tests/HeroLineageWorkbench.test.tsx`                 | Verify managed lifecycle button verbs for owned sessions and record-only/unavailable copy for observed sessions.        | \~60       |
| `apps/web/tests/ChannelCommandPanel.test.tsx`                  | Verify channel/template intake labels remain proposal-first until local queue creation and dispatch.                    | \~60       |
| `apps/web/tests/wsClientPrivacy.test.ts`                       | Verify WebSocket normalization drops or redacts broad sensitive command-center event fields.                            | \~80       |
| `tests/e2e/orchestration-command-center.e2e.ts`                | Add release matrix browser scenarios or tags for supported execution, recovery, and unavailable evidence.               | \~140      |
| `docs/api/README_api.md`                                       | Update shipped Phase 20 local execution semantics and blocked broad payload categories.                                 | \~100      |
| `apps/server/README_server.md`                                 | Align server route inventory and command-center execution/no-claim wording with Phase 20 evidence.                      | \~80       |
| `docs/privacy-and-security.md`                                 | Add Phase 20 command-center execution privacy boundary and local-only evidence wording.                                 | \~90       |
| `docs/release.md`                                              | Add Phase 20 focused release evidence commands, unsupported-path register, and no-overclaim release language.           | \~120      |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Terminal, Git, file mutation, container, and supported managed-agent control each have create or approve -> dispatch or execute -> observe -> recover evidence or truthful unavailable evidence.
* [ ] Campaign and queue states never complete from metadata-only, proposal-only, preview-only, approved-not-executing, or unavailable work.
* [ ] Guarded actions execute only through proved executor families and return unavailable or approved-not-executing for non-ready families.
* [ ] Template and channel intake remain local-approval and proposal-first until a local executable queue entry exists.
* [ ] Release docs and UI labels use action verbs only for working actions.

### Testing Requirements

* [ ] Protocol tests cover blocked raw fields and compact command-center public event shapes.
* [ ] Server tests cover queue, campaign, file, guarded, hero, container, channel, export, and diagnostics privacy semantics.
* [ ] Web tests cover broad-row state labels, product-facing verbs, unavailable/retry copy, duplicate in-flight guards, and no raw execution detail.
* [ ] Browser e2e covers the Command Center release evidence path in `tests/e2e/orchestration-command-center.e2e.ts`.
* [ ] Release evidence matrix records command results and remaining unsupported paths.

### Non-Functional Requirements

* [ ] Broad rows, events, exports, diagnostics, examples, and docs do not include terminal command text, terminal output, raw Git output, diffs, file contents, patch bodies, tokens, secrets, broad absolute paths, provider payloads, or webhook raw bodies.
* [ ] Optional runtime dependencies fail closed with unavailable states and product-facing recovery guidance.
* [ ] Idempotency and duplicate-trigger prevention remain active for dispatch, approval, conversion, rollback, and lifecycle controls.
* [ ] Hosted identity, trusted unified erasure, production-hosted validation, authorized Cloudflare deploy evidence, and legal/privacy approval remain no-claim.

### 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.
* [ ] `npm test` passes.
* [ ] `npm run test:e2e -- --project=app-desktop tests/e2e/orchestration-command-center.e2e.ts` passes.
* [ ] `git diff --check` passes.

***

## 8. Implementation Notes

### Working Assumptions

* Cross-package package context: The selected session stub has `package: null`, the analyzer has no active package, and the deliverables span `packages/protocol`, `apps/server`, `apps/web`, `tests/e2e`, and `docs`. Planning proceeds as cross-cutting with `Package: null`.
* Earlier Phase 20 feature slices are ready to cite: The analyzer reports Sessions 01-10 complete, and `.spec_system/PRD/phase_20/PRD_phase_20.md` records validation dates for each. Session 11 may consolidate evidence rather than reimplement feature slices.
* Browser evidence should extend the existing command-center e2e file: `CONSIDERATIONS.md` warns that orphan Playwright files can pass without running, and the current configured evidence path is `tests/e2e/orchestration-command-center.e2e.ts`.
* Optional local runtimes may be unavailable: Phase 20 requires truthful unavailable evidence for PTY, Docker, Apple Containers, or policy-blocked operations when the local shell lacks runtime support. Planning can proceed because unavailable is an accepted product state.
* Stable docs are current product contracts: `CONSIDERATIONS.md` identifies stable README and `docs/` files as the current contract, so implementation must update those docs alongside tests.

### Conflict Resolutions

* Candidate status versus master PRD wording: The master PRD says remaining work includes managed lifecycle, container, template/channel, and release evidence, while the analyzer and Phase 20 PRD show Sessions 08-10 already completed. The analyzer and Phase 20 PRD validation rows win, so Session 11 is selected.
* Release closeout versus cumulative no-claim findings: Session 11 asks for release evidence, while `SECURITY-COMPLIANCE.md` keeps hosted identity, trusted unified erasure, production-hosted validation, authorized Cloudflare deploy evidence, and legal/privacy approval open. The chosen interpretation is to close only Phase 20 local orchestration evidence and preserve those cumulative no-claims.
* Existing release guide versus Phase 20 gate needs: `docs/release.md` contains broad historical release gates and Phase 08 public website wording. Session 11 should add Phase 20 focused command-center gates without weakening existing no-claim language.

### Key Considerations

* \[P19] **Executor claims are family-scoped**: Do not claim any family ready unless its local execution, permission, audit, redaction, unavailable states, tests, docs, and evidence are present.
* \[P19] **Scoped detail stays separate from broad rows**: Commands, output, diffs, file contents, transcripts, provider payloads, and absolute paths stay out of broad rows and events.
* \[P19] **Channel intake is proposal-first**: Webhook and channel records are reviewable local metadata until a local operator creates and dispatches a queue entry.
* \[P03-packages/protocol] **Protocol leads cross-package work**: Public command-center event and DTO semantics stay owned by `packages/protocol`.
* \[P19] **Command-center state is manager-owned**: State transitions, idempotency, revisions, event emission, and bounded snapshots stay in managers.

### Potential Challenges

* Evidence sprawl: Use one release evidence ledger and link to focused tests/commands instead of duplicating validation prose across docs.
* Runtime-dependent browser tests: Design scenarios so supported runtime paths assert execution when available and assert truthful unavailable states when optional dependencies fail closed.
* Privacy regressions through docs examples: Search and update examples alongside source/tests so raw commands, diffs, outputs, webhook bodies, and broad paths do not appear as release examples.
* UI overclaim drift: Keep labels centralized in existing UI helpers where possible and assert product-facing copy in tests.

### Relevant Considerations

* \[P19] **Protocol-first command-center contracts**: Shared DTOs, parser helpers, and REST/WebSocket aliases keep package behavior aligned.
* \[P19] **Capability-first product rows**: Unavailable, observe-only, proposal-only, executor-ready, executing, executed, and failed states should remain visible and specific.
* \[P19] **Broad-summary plus scoped-detail split**: Cards and events stay compact while drawers own bounded detail for execution runs and terminal/file artifacts.
* \[P19] **Parser-level redaction plus store normalization**: Reject blocked raw fields before manager/store mutation, then normalize safe labels before UI display.
* \[P19] **E2E files need project discovery checks**: Add or tag browser coverage inside the existing included e2e file.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* Release evidence could accidentally bless metadata-only or unavailable paths as shipped execution.
* Broad rows, WebSocket updates, exports, diagnostics, docs, or e2e assertions could leak scoped execution details.
* Optional dependency absence could be treated as a failure instead of a truthful unavailable product state.
* Duplicate dispatch, approval, rollback, conversion, or lifecycle actions could create conflicting evidence.

***

## 9. Testing Strategy

### Unit Tests

* Protocol tests for blocked raw fields, compact event/update shapes, capability state vocabulary, and executable payload public summaries.
* Server manager and route tests for queue states, campaign states, file rollback, guarded approvals, hero lifecycle control, container unavailable/failure states, channel no-auto-execute, export redaction, and broad event privacy.
* Web helper, store, and component tests for state labels, action availability, unavailable/retry copy, scoped links, and WebSocket normalization.

### Integration Tests

* Route-level tests for `/task-queue/:id/dispatch`, `/task-queue/:id/rollback`, `/command-center/campaigns/:id/dispatch`, `/guarded-actions/:id/approve`, `/command-center/heroes/commands`, `/webhooks/*`, `/channel-commands`, `/export/session`, and command-center diagnostics routes.
* Web component tests for QueueWorkbench, CampaignWorkbench, FileGitWorkbench, HeroLineageWorkbench, ChannelCommandPanel, and WebSocket privacy helpers.

### Runtime Verification

* Run the minimum focused command set from the session stub:
  * `npm --workspace packages/protocol run typecheck`
  * `npm --workspace apps/server run typecheck`
  * `npm --workspace apps/web run typecheck`
  * `npm test`
  * `npm run test:e2e -- --project=app-desktop tests/e2e/orchestration-command-center.e2e.ts`
  * `git diff --check`

### Edge Cases

* PTY unavailable, Docker unavailable, image unavailable, policy-blocked Git push, stale queue revision, duplicate dispatch idempotency key, killed terminal, failed command, failed campaign prerequisite, unavailable campaign prerequisite, file stale hash, file conflict, missing rollback backup, observed-only hero session, duplicate channel delivery, rejected raw webhook executable claim, and malformed WebSocket command-center event.

***

## 10. Dependencies

### Other Sessions

* Depends on: Phase 20 Sessions 01-10.
* Depended by: Phase 20 `updateprd`, then Phase Transition `audit`.

***

## 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-session11-release-evidence-and-event-privacy/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.