> 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-session05-attention-and-permissions/spec.md).

# Session Specification

**Session ID**: `phase19-session05-attention-and-permissions` **Phase**: 19 - Orchestration Command Center Execution **Status**: Not Started **Created**: 2026-06-26 **Package**: null **Package Stack**: mixed TypeScript/JavaScript

***

## 1. Session Overview

This session turns the command-center Attention tab from a generic record list into the operator queue for permission requests, plan approvals, blocked tasks, failed verification, and review gates. It connects current hook permission events, legacy permission response routes, command-center decision routes, and web reason-capture controls through one audited state path.

It is next because Phase 19 Sessions 01 through 04 established protocol contracts, server command-center state, web store hydration, and campaign/queue mutation flows. Session 06 depends on this approval and permission layer before guarded actions can move toward executor-ready families.

The work remains local-first and non-executing. Approvals resolve permission and attention state, unblock supported hook round trips where a pending resolver exists, and record audit metadata, but they do not run file, git, terminal, container, remote, Worker, or hosted executors.

***

## 2. Objectives

1. Promote permission request, plan approval, blocked task, failed verification, and review gate inputs into one manager-owned attention queue.
2. Record approve and reject decisions with actor, reason, expected revision, decided time, result state, idempotency, and stale-revision handling.
3. Bridge supported hook permission and plan response paths into command-center permission and attention state without enabling executor runs.
4. Ship a dedicated web attention queue with filters, counts, reason capture, duplicate-trigger guards, loading/empty/error/offline states, and product-facing copy.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase19-session01-protocol-and-events` - Provides command-center DTOs, validation helpers, REST aliases, compact events, and capability envelopes.
* [x] `phase19-session02-server-backbone` - Provides the command-center manager, REST routes, WebSocket hydration, and diagnostics base.
* [x] `phase19-session03-web-shell-and-store` - Provides web API helpers, Zustand slices, event reducers, shell tabs, drawers, and command-center UI helpers.
* [x] `phase19-session04-campaign-workbench` - Provides plan campaign and queue mutation flows, expected revision checks, idempotency, and workbench UI patterns.

### Required Tools Or Knowledge

* Node 26.2.0+ and npm 11.16.0.
* TypeScript, React, Zustand, Express, Vitest, and Biome conventions from `.spec_system/CONVENTIONS.md`.
* Existing permission hook, legacy permission routes, command-center manager, and web orchestration shell behavior.

### Environment Requirements

* Local workspace dependencies installed with `npm install`.
* No hosted credentials, provider transfer, Cloudflare credentials, or database are required.

***

## 4. Scope

### In Scope (MVP)

* Operators can review guarded actions, permission requests, plan approvals, blocked tasks, failed verification, and review gates in one attention queue - Implemented through command-center records, server synthesis helpers, and a dedicated web workbench.
* Operators can approve or reject permission and plan approval items with a reason - Decisions update permission and attention records with audit metadata and compact event emission.
* Hook permission requests can round trip through existing response routes - Supported requests update command-center state and pending resolver maps; unsupported providers return visible capability or unavailable states.
* Stale or duplicate decisions are visible and bounded - Expected revision, idempotency key, duplicate trigger, timeout, and stale-decision paths return compact errors and clear UI in-flight state.

### Out Of Scope (Deferred)

* Running executor families after approval - Reason: Session 06 owns executor registry and execution runs.
* Push, mobile, or browser notification delivery - Reason: Session 15 owns metrics and notifications.
* Hosted identity, hosted storage, remote execution, Worker transfer, or public collaboration claims - Reason: current security posture keeps these as disabled-default or no-claim boundaries.
* Model-backed plan decomposition changes - Reason: Session 04 shipped manual campaign workflows; provider-backed planning remains separate from attention decisions.

***

## 5. Technical Approach

### Architecture

Keep command-center contracts protocol-first. Extend `packages/protocol/src/orchestrationCommandCenter.ts` only where decision audit fields are missing, then consume those shapes from server and web. The server remains manager-owned: `OrchestrationCommandCenterManager` owns attention, permission, decision, expiration, idempotency, stale revision, and event emission behavior. Routes and WebSocket handlers call manager methods instead of duplicating state changes.

Hook ingest promotes bounded permission metadata from `apps/hooks/src/factionos-permission-request.js` into command-center permission and attention records through `apps/server/src/routes/event.ts`. Legacy `/permission-response` and `/plan/approve` routes, plus matching WebSocket client messages, become adapters into the same decision path. Web UI calls command-center decision helpers with expected revisions and idempotency keys, then refreshes attention and permission snapshots after accepted mutations.

### Design Patterns

* Protocol-first shared contracts: keeps server, web, and tests aligned on attention and permission decision shapes.
* Manager-owned state transitions: keeps idempotency, stale revision checks, expiration cleanup, redaction, and event emission centralized.
* Adapter routes: preserves legacy hook and web message compatibility while moving canonical state into command-center records.
* Pure web normalization before mutation: keeps malformed snapshots from corrupting Zustand state.
* Product-surface-only UI: keeps attention queue copy focused on operator decisions and confines diagnostics to tests and internal state.

***

## 6. Deliverables

### Files To Create

| File                                                           | Purpose                                                                                                           | Est. Lines |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ---------- |
| `apps/web/src/components/orchestration/AttentionWorkbench.tsx` | Dedicated attention queue with filters, counts, reason capture, approve/reject controls, and empty/offline states | \~260      |

### Files To Modify

| File                                                           | Changes                                                                                                                                   | Est. Lines |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `packages/protocol/src/orchestrationCommandCenter.ts`          | Add missing decision audit/result fields and parser/event validation for attention and permission records                                 | \~80       |
| `packages/protocol/tests/orchestrationCommandCenter.test.ts`   | Cover decision audit fields, stale metadata, and blocked payload rejection for attention and permission records                           | \~70       |
| `apps/server/src/managers/orchestrationCommandCenter.ts`       | Add attention synthesis, permission request creation, plan approval creation, decision resolution, timeout, stale, and duplicate handling | \~260      |
| `apps/server/src/lib/commandCenterValidation.ts`               | Add attention or permission decision body validation with compact errors                                                                  | \~90       |
| `apps/server/src/routes/commandCenter.ts`                      | Add attention decision route and emit paired attention/permission updates after decisions                                                 | \~90       |
| `apps/server/src/routes/event.ts`                              | Promote bounded hook permission request events into command-center permission and attention records                                       | \~80       |
| `apps/server/src/routes/permission.ts`                         | Route legacy permission and plan approval responses through command-center decision state                                                 | \~100      |
| `apps/server/src/ws/handlers.ts`                               | Route WebSocket permission and plan approval responses through the same decision state                                                    | \~80       |
| `apps/server/src/server.ts`                                    | Inject command-center dependencies into event, permission, and WebSocket handler wiring                                                   | \~40       |
| `apps/server/tests/commandCenterManager.test.ts`               | Cover attention synthesis, decisions, timeout expiration, stale revisions, duplicate decisions, and redaction                             | \~150      |
| `apps/server/tests/commandCenterRoutes.test.ts`                | Cover attention and permission routes, legacy adapters, event emission, `/api` aliases, and compact errors                                | \~150      |
| `apps/server/tests/permission.test.ts`                         | Cover legacy permission and plan response round trips against command-center state                                                        | \~90       |
| `apps/hooks/tests/hookPayloads.test.js`                        | Verify permission hook metadata remains bounded and does not claim enforcement                                                            | \~40       |
| `apps/web/src/lib/orchestrationApi.ts`                         | Add attention decision helper and refresh support for attention plus permission snapshots                                                 | \~90       |
| `apps/web/src/lib/commandCenterUi.ts`                          | Add attention filter, status, risk, count, and action-state helpers                                                                       | \~120      |
| `apps/web/src/store/useGameStore.ts`                           | Clear in-flight attention and permission mutation keys on events and normalize decision state                                             | \~70       |
| `apps/web/src/components/orchestration/CommandCenterPanes.tsx` | Replace generic attention PaneGrid with AttentionWorkbench integration                                                                    | \~80       |
| `apps/web/src/components/orchestration/OrchestrationShell.tsx` | Wire approve/reject handlers, reason capture callbacks, refreshes, toasts, and cleanup                                                    | \~140      |
| `apps/web/src/components/orchestration/index.ts`               | Export AttentionWorkbench                                                                                                                 | \~10       |
| `apps/web/tests/orchestrationApi.test.ts`                      | Cover attention and permission decision helper success, duplicate, stale, timeout, and invalid id paths                                   | \~110      |
| `apps/web/tests/commandCenterUi.test.ts`                       | Cover attention filters, status copy, action availability, and blocked payload handling                                                   | \~90       |
| `apps/web/tests/commandCenterStore.test.ts`                    | Cover attention and permission WebSocket reducers plus in-flight key cleanup                                                              | \~100      |
| `apps/web/tests/OrchestrationPanel.test.tsx`                   | Cover queue rendering, reason capture, approve/reject controls, offline/error states, and product-facing copy                             | \~170      |
| `docs/api/README_api.md`                                       | Document command-center attention and permission decision behavior without executor or hosted claims                                      | \~80       |
| `apps/server/README_server.md`                                 | Update server command-center notes for attention, permission adapters, and local-only decision audit                                      | \~80       |
| `apps/web/README_web.md`                                       | Update web command-center notes for attention queue states and non-executing approval boundary                                            | \~80       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Guarded actions, permission requests, plan approvals, blocked tasks, failed verification, and review gates appear as attention records with stable ids, requester, target, family or kind, risk, preview, expected result, timeout, revision, and state.
* [ ] Approve and reject decisions record actor, reason, expected revision, decided time, result state, idempotency key, and stale or duplicate metadata.
* [ ] Legacy `/permission-response`, `/plan/approve`, and matching WebSocket client messages update the same command-center permission and attention state as direct command-center decisions.
* [ ] Blocking permission requests unblock or time out through tested paths when a pending resolver exists, and unsupported providers surface visible capability or unavailable outcomes.
* [ ] Web controls prevent duplicate triggers while in flight, clear state on all success and failure paths, and refresh attention plus permission snapshots after accepted decisions.

### Testing Requirements

* [ ] Protocol parser tests cover new decision audit fields and blocked payload rejection.
* [ ] Server manager tests cover synthesis, decision, timeout, stale revision, duplicate, unsupported provider, and redaction behavior.
* [ ] Server route tests cover command-center routes, legacy adapters, WebSocket emissions, `/api` aliases, and compact validation errors.
* [ ] Web API, store, UI helper, and component tests cover success, reject, stale, duplicate, offline, timeout, loading, empty, error, and product-copy states.

### Non-Functional Requirements

* [ ] Broad attention rows never expose raw prompts, command bodies, terminal output, diffs, provider payloads, secrets, or broad absolute paths.
* [ ] All decision paths stay local-first and do not claim executor, hosted, Worker, remote, or push behavior.
* [ ] Attention queue controls are reachable by accessible roles and labels and handle keyboard and pointer input consistently.

### 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 server and web tests pass

***

## 8. Implementation Notes

### Working Assumptions

* Cross-package package context is intentional: the session stub names `apps/server`, `apps/web`, and `apps/hooks`, while existing command-center DTOs live in `packages/protocol`. Planning records `Package: null` because the selected work must coordinate these package boundaries.
* Existing command-center DTOs are the starting point, not a reason to skip protocol work: `CommandCenterPermissionDecision` has actor, reason, and time fields, but `CommandCenterPermissionRequest` and attention records do not yet persist enough decision audit state for the success criteria. A narrow protocol extension is safe because Phase 19 Session 01 established protocol ownership.
* Legacy permission routes remain supported adapters: `apps/server/src/routes/permission.ts` currently validates `/permission-response` and `/plan/approve` and emits compatibility events even when no resolver is pending, so the session can preserve compatibility while adding command-center state changes.

### Key Considerations

* Keep `EXAMPLES/` as evidence only. Do not copy hook bundles, prompts, transcripts, terminal output, or historical route code into runtime files.
* Approval is not execution. A successful decision should resolve local state and pending response maps only.
* Decision failures must return compact errors that do not echo raw request bodies, prompts, paths, tokens, diffs, or command output.

### Potential Challenges

* Paired attention and permission events can drift: emit both event families from the same manager decision result and cover with route tests.
* Legacy adapters can bypass command-center state: route both HTTP and WebSocket response paths through shared manager methods.
* UI controls can get stuck after stale or duplicate decisions: clear mutation keys in `finally` and on matching WebSocket change events.

### Relevant Considerations

* \[P03] **Real executors remain unimplemented by design**: approvals must not execute file, git, terminal, remote, or container families in this session.
* \[P03-packages/protocol] **Protocol leads cross-package work**: decision audit fields and parser changes land before server and web consumption.
* \[P03-apps/server] **Local server boundary must stay conservative**: new routes need validation, compact errors, body caps inherited from server config, and explicit unavailable behavior.
* \[P07] **Redaction is boundary-specific**: attention rows, permission events, route responses, WebSocket frames, and UI copy each need separate minimization.
* \[P18-apps/server] **Manager-owned persistence and snapshot emission**: attention and permission changes should stay behind one manager-owned state path.
* \[P18-apps/web] **Pure normalization before store mutation**: web reducers should normalize malformed or partial payloads before Zustand state changes.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* Duplicate approve or reject triggers can produce conflicting decision state.
* Stale revisions can resolve the wrong pending request or hide a newer risk preview.
* Hook and legacy response adapters can leak raw provider details if they bypass bounded command-center fields.

***

## 9. Testing Strategy

### Unit Tests

* Protocol parser tests for attention and permission decision fields, blocked payload fields, invalid enum values, stale revision metadata, and bounded strings.
* Server manager tests for synthesis, idempotent decisions, stale decisions, timeout expiration, unsupported provider states, redaction, and paired attention/permission changes.
* Web UI helper tests for attention filtering, risk/status labels, action availability, and blocked payload filtering.

### Integration Tests

* Server route tests for `/command-center/attention`, `/command-center/attention/:id/decision`, `/command-center/permissions/:id/decision`, `/permission-response`, `/plan/approve`, and `/api` aliases.
* Web API tests for attention decision helper responses, duplicate in-flight handling, invalid ids, timeout mapping, and stale revision mapping.
* Store and component tests for WebSocket update reducers, in-flight cleanup, reason capture, approval/rejection controls, loading, empty, offline, and error states.

### Runtime Verification

* Run focused protocol, server, and web tests for command-center attention and permission behavior.
* Run package typechecks for protocol, server, and web.
* Run `npm run lint`, `npm run format:check`, `git diff --check`, and ASCII/LF validation on touched files.

### Edge Cases

* Decision arrives after request expiration.
* Decision expected revision is stale.
* Duplicate idempotency key repeats the same decision or conflicts with another request.
* Unsupported provider posts a permission request without a blocking resolver.
* Attention item references a missing permission request or already resolved target.
* Network, timeout, or malformed response occurs after the UI disables controls.

***

## 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`
* Depended by: `phase19-session06-executor-registry`, `phase19-session08-file-and-git`, `phase19-session09-heroes-and-lineage`, `phase19-session13-collaboration-and-handoff`, `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-session05-attention-and-permissions/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.