> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/phases/phase_19/prd_phase_19.md). # PRD\_phase\_19 ## PRD Phase 19: Orchestration Command Center Execution **Status**: Complete **Sessions**: 16 (initial estimate) **Estimated Duration**: 8-12 days **Progress**: 16/16 sessions (100%) *** ### Overview Phase 19 turns the current web Orchestration panel from a compact local read-only cockpit slice into the command center described by the source-backed study preserved in Appendix A of this PRD. The current product already has local queue, template, lineage, and guarded action visibility. The study identifies the gap: plans/campaigns, attention, permissions, executable guarded-action families, diagnostics, handoff/resume, file intent protection, provider readiness, terminal/container capability, War Room and Notice Board context, channel/webhook intake, metrics, and operator ergonomics need to connect through current protocol contracts, server managers, store slices, React components, tests, and stable docs. `EXAMPLES/` remains evidence only. This phase does not import, copy, transform, or ship historical code, bundles, assets, prompts, transcripts, terminal output, or hosted-service behavior. Execution work must preserve the local-first boundary, explicit permission model, redaction rules, audit trails, unavailable states, tests, and docs required by the master PRD carry-forward items. *** ### Progress Tracker | Session | Name | Status | Est. Tasks | Validated | | ------- | ------------------------------ | -------- | ---------- | ---------- | | 01 | Protocol And Events | Complete | 20 | 2026-06-26 | | 02 | Server Backbone | Complete | 20 | 2026-06-26 | | 03 | Web Shell And Store | Complete | 20 | 2026-06-26 | | 04 | Campaign Workbench | Complete | 20 | 2026-06-26 | | 05 | Attention And Permissions | Complete | 20 | 2026-06-26 | | 06 | Executor Registry | Complete | 22 | 2026-06-26 | | 07 | Provider Diagnostics | Complete | 22 | 2026-06-26 | | 08 | File And Git | Complete | 23 | 2026-06-26 | | 09 | Heroes And Lineage | Complete | 25 | 2026-06-26 | | 10 | Mission Artifacts | Complete | 18 | 2026-06-26 | | 11 | Templates And Planning Context | Complete | 22 | 2026-06-26 | | 12 | Terminal And Containers | Complete | 25 | 2026-06-26 | | 13 | Collaboration And Handoff | Complete | 24 | 2026-06-26 | | 14 | Channels And Scope | Complete | 22 | 2026-06-27 | | 15 | Metrics And Notifications | Complete | 22 | 2026-06-28 | | 16 | Ergonomics And Documentation | Complete | 20 | 2026-06-28 | *** ### Completed Sessions * Session 01: Protocol And Events - completed 2026-06-26. Added the shared command-center protocol contracts, compact WebSocket event families, REST aliases, fail-closed parser helpers, capability/unavailable envelopes, compatibility tests, and protocol documentation in `packages/protocol`. * Session 02: Server Backbone - completed 2026-06-26. Added the server command-center manager scaffold, validation adapters, root and `/api` REST routes, compact WebSocket hydration and mutation events, diagnostics counts, redaction-safe storage behavior, server/API documentation, and server tests in `apps/server`. * Session 03: Web Shell And Store - completed 2026-06-26. Added typed web command-center API helpers, normalized Zustand slices, WebSocket reducers, product-facing orchestration shell components, tabs, drawer states, redaction-safe labels, and focused web tests in `apps/web`. * Session 04: Campaign Workbench - completed 2026-06-26. Added the server campaign manager, campaign and queue mutation routes, queue transition controls, web campaign and queue workbench components, mutation helpers, duplicate-trigger guards, stale-revision handling, redaction-safe UI copy, and focused server/web tests across `apps/server` and `apps/web`. * Session 05: Attention And Permissions - completed 2026-06-26. Added protocol-backed attention and permission decision audit fields, bounded server adapters for hook and legacy approval paths, paired command-center WebSocket updates, the web Attention workbench with reason capture and duplicate-trigger guards, local-only documentation, and focused protocol, server, web, and hook tests. * Session 06: Executor Registry - completed 2026-06-26. Added the registry-backed guarded-action approval boundary, default fail-closed executor capabilities, command-center execution run helpers, executor probe and detail routes, paired REST and WebSocket execution updates, the web Executors tab cards and run-history drawer, bounded redaction-safe summaries, and focused server, web, diagnostics, WebSocket, lint, format, typecheck, and full-suite validation. * Session 07: Provider Diagnostics - completed 2026-06-26. Added shared provider/setup/runtime diagnostics contracts, the server diagnostics manager and recovery routes, CLI status and doctor readiness output, the web Diagnostics tab capability matrix and recovery panel, redaction-safe docs, and focused protocol, server, CLI, web, lint, format, typecheck, security, and full-suite validation. * Session 08: File And Git - completed 2026-06-26. Added shared File/Git command-center contracts, server-owned file intent and Git workbench managers, bounded conflict and Git execution routes, guarded-action execution wiring, hook attribution promotion, the web File/Git workbench tab, redaction-safe docs, and focused protocol, server, hook, web, lint, format, typecheck, security, and full-suite validation. * Session 09: Heroes And Lineage - completed 2026-06-26. Added expanded hero lifecycle and lineage roster contracts, server-owned lifecycle command handling, mission graph roster derivation, bounded hook metadata promotion, the web Hero/Lineage workbench, redaction-safe API documentation, and focused protocol, server, hook, web, lint, format, typecheck, security, and full-suite validation. * Session 10: Mission Artifacts - completed 2026-06-26. Added server-owned workpad, evidence, verification, and review-gate behavior with validated mutation routes, compact artifact WebSocket updates, attention side effects, web mission artifact helpers, the Mission Artifacts panel, drawer-linked artifact details, reducer reconciliation, redaction-safe docs, and focused server, web, lint, format, typecheck, security, and full-suite validation. * Session 11: Templates And Planning Context - completed 2026-06-26. Added bounded template metadata and source-attribution contracts, server planning context helpers, template suggestion and queue-from-template routes, campaign memory filters, auto-improvement attention proposals, the web Template Workbench, safe source and memory detail rows, and focused protocol, server, web, lint, format, typecheck, security, and full-suite validation. * Session 12: Terminal And Containers - completed 2026-06-26. Added shared terminal and container contracts, server-owned PTY terminal and container runtime managers, local terminal/container routes, guarded executor capability integration, isolation diagnostics, scoped web terminal runtime and isolation readiness UI, optional PTY dependency metadata, redaction-safe docs, and focused protocol, server, web, lint, format, typecheck, security, audit, and full-suite validation. * Session 13: Collaboration And Handoff - completed 2026-06-26. Added bounded collaboration and handoff contracts, server-owned Notice linkback and handoff readiness flows, compact War Room relay posture, the web Federation/Handoff workbench, redaction-safe docs, and focused protocol, server, War Room, web, lint, format, typecheck, security, coverage, and full-suite validation. * Session 14: Channels And Scope - completed 2026-06-27. Added protocol-backed channel command and scope contracts, server-owned channel/webhook intake with replay guards and proposal-first conversion, adapter attribution helpers, web scope controls and channel command panels, redaction-safe docs, and focused protocol, adapter, server, web, lint, format, typecheck, security, and full-suite validation. * Session 15: Metrics And Notifications - completed 2026-06-28. Added enriched command-center metrics and notification contracts, manager-owned server aggregation, readiness and subscription guardrails, local notification routing, the web Metrics and Notifications panel, attention summaries, mobile filters, redaction-safe docs, and focused protocol, server, web, lint, format, typecheck, security, and full-suite validation. * Session 16: Ergonomics And Documentation - completed 2026-06-28. Added command-center keyboard workflows, selected-target safety, accessible shortcut labels, adjacent-surface cross-links, focused desktop/mobile Playwright coverage, stable docs closeout, and no-claim wording for hosted, remote, and unsupported executor surfaces. *** ### Upcoming Sessions * None. Phase 19 session work is complete. *** ### Objectives 1. Establish shared orchestration contracts, server managers, routes, store slices, and event reducers for the expanded command center. 2. Turn queue, templates, lineage, guarded actions, permissions, campaigns, diagnostics, handoffs, channels, and metrics into operator workflows with explicit capability and unavailable states. 3. Ship executable local families deliberately behind permission, audit, redaction, validation, and documentation gates without promoting hosted or historical claims. *** ### Prerequisites * Phase 18 completed and archived as Quest Board Suggestion Parity. * Appendix A of this PRD reviewed as the Phase 19 feature inventory and evidence index. * The master PRD carry-forward boundaries for real executors, inbound commands, hosted services, War Room external transfer, and historical evidence remain active. *** ### Planning Assumptions And Resolutions #### Working Assumptions * The supplied orchestration study is the authoritative source for Phase 19 scope: it is a current repository document dated 2026-06-26, contains a session split plan, and cites current code/docs plus `EXAMPLES/` evidence. The master PRD Future Phase Rules allow source-backed future phases, so phasebuild can proceed without user arbitration. * One large 16-session phase is acceptable for this command-center objective: the study already groups work by dependency order, and the work remains one cohesive orchestration-command-center phase even though it is larger than the typical 4-8 session guideline. * Execution remains local-first and guarded: approvals become executable only for executor-ready families with explicit contracts, capability probes, permission state, audit fields, redaction, bounded outputs, tests, and docs. #### Conflict Resolutions * The master PRD and `state.json` ended at Phase 18 complete with no Phase 19 row, while the user supplied a source-backed phase plan. The chosen interpretation is to create Phase 19 as the next sequential phase and update both master PRD and state tracking because the PRD explicitly permits new source-backed future phases and already carries forward executor and inbound command requirements. * The master PRD says real executors, Docker isolation, remote execution, and inbound commands are deferred or no-claim without threat, permission, audit, tests, and docs, while the study says execution is in scope. The chosen interpretation is that Phase 19 may implement execution families only by satisfying those gates; unsupported families keep structured unavailable or proposal-only states until ready. *** ### Technical Considerations #### Architecture * Contract-first: shared DTOs, validators, route shapes, and WebSocket events land in `packages/protocol` before server and web behavior. * Manager-owned state: each new runtime area has a server manager responsible for persistence, idempotency, expected revision checks, timeout cleanup, audit fields, event emission, and bounded payloads. * Capability-first execution: executor families report unavailable, observe-only, proposal-only, approved-not-executing, executor-ready, executing, executed, and failed states before approvals can run anything. * Web decomposition: `OrchestrationPanel.tsx` is split into focused tabs and drawers while keeping the compact current panel usable. * Historical evidence stays trace-only: `EXAMPLES/` artifacts are never copied into runtime code or public product claims. #### Technologies * TypeScript across `packages/protocol`, `apps/server`, and `apps/web` * Zod request and protocol validation * Vitest projects for protocol, server, and web coverage * Playwright for Orchestration detail modal flows once mutating controls land * Local JSON or existing manager-owned persistence under the current server conventions * WebSocket event hydration plus refresh-on-mutation helpers #### Risks * Execution can break the conservative local boundary: require per-family capability probes, previews, permission decisions, audit logs, output caps, and docs before enabling run behavior. * Cross-package drift can corrupt orchestration state: protocol changes must precede server and web implementation, and store normalization must be pure. * Sensitive developer data can leak through broad rows or external transfer: show compact labels and metadata in broad views, with raw command bodies, diffs, terminal output, prompts, transcripts, and artifacts kept in scoped local details only. * The phase is large: session ordering must keep contracts, backbone, and store foundations ahead of feature-specific executor and collaboration work. * Hosted and War Room claims can drift: remote, Worker, push, tunnel, and external channel surfaces remain opt-in, redacted, disabled by default, and documented as separate transfer boundaries. #### Relevant Considerations * \[P03] **Real executors remain unimplemented by design**: Phase 19 can close this only through a separate threat model, authorization, audit log, tests, and docs for each shipped family. * \[P03-packages/protocol] **Protocol leads cross-package work**: Session 01 owns shared orchestration shapes before package-specific behavior. * \[P03-apps/server] **Local server boundary must stay conservative**: new routes need validation, rate limits, body caps, origin protections, and explicit unavailable behavior. * \[P07] **Redaction is boundary-specific**: queue, lineage, guarded-action, Worker, diagnostics, replay, export, adapter, backup, and future external payloads must each minimize data separately. * \[P06-apps/warroom+apps/web] **War Room federation is optional and redacted**: room-visible orchestration state must not imply hosted identity, production auditability, broad collaboration safety, or full erasure. * \[P07] **Hosted services ship as disabled-default guardrails only**: push, tunnels, remote access, hosted identity, hosted storage, and analytics remain inactive claims until separately implemented with consent and tests. * \[P18-apps/server] **Manager-owned persistence and snapshot emission**: expanded orchestration managers should keep filtering, state, and broadcasts aligned. * \[P18-apps/web] **Pure normalization before store mutation**: web event reducers should normalize malformed or partial payloads before Zustand state changes. *** ### Folded Source Coverage This PRD now owns the full source material that previously lived in the retired ongoing-project study document. Appendix A preserves the study text, the generated session split, every implementation target, the balls-to-the-wall implementation tracks, the hook/listener mapping, the tests and done criteria, the bottom line, and the complete reference index with links rewritten relative to this phase directory. Session stubs in this directory also carry session-specific source coverage and EXAMPLES links so `plansession` can create focused specs without reopening the retired ongoing-project document. *** ### Success Criteria Phase complete when: * [x] All 16 sessions completed * [x] New orchestration DTOs, validators, routes, WebSocket events, managers, store slices, and docs are implemented for the command-center surface * [x] Queue and campaign workflows can create, mutate, approve, pause, resume, retry, cancel, dispatch, and inspect tasks with evidence and verification * [x] Attention merges guarded actions, permission requests, plan approvals, blocked tasks, failed verification, review gates, and channel commands * [x] Executor-ready families can produce audited execution runs, while unsupported families return structured capability errors * [x] File/git, hero lifecycle, lineage, mission artifacts, templates, terminal/container capability, collaboration, handoff, channel intake, metrics, notifications, shortcuts, and cross-links are covered by tests and stable documentation * [x] Security, privacy, hosted-service, War Room, inbound command, and historical evidence boundaries are updated without making unsupported product claims *** ### Dependencies #### Depends On * Phase 18: Quest Board Suggestion Parity * Appendix A: Preserved Orchestration Panel EXAMPLES Study (2026-06-26) #### Enables * Future phase: orchestration execution hardening, release evidence, and any hosted or production validation that remains claim-gated after Phase 19 *** ### Appendix A: Preserved Orchestration Panel EXAMPLES Study (2026-06-26) The following material is preserved from the retired source study. Relative links were rewritten for this phase PRD so the evidence remains directly navigable from `.spec_system/archive/phases/phase_19/`. `EXAMPLES/` remains traceability evidence only; do not import, copy, transform, or ship historical code or assets directly. ## Orchestration Panel EXAMPLES Study Date: 2026-06-26 Status: second-pass implementation plan. This document is not a shipped behavior claim. ### Session Split Plan #### Session 01: Protocol And Events **Objective**: Define the shared orchestration contracts that every server, store, and panel slice will depend on. **Scope**: * Add protocol DTOs and validators for plans, tasks, attention items, executor capabilities, hero lifecycle commands, execution runs, permission requests, file intents, workpad records, evidence artifacts, verification attempts, review gates, handoffs, diagnostics, channel commands, and usage metrics. * Add WebSocket event contracts for plan, task, attention, executor, hero, execution, permission, file intent, workpad, evidence, verification, handoff, diagnostic, channel command, and usage updates. * Add fixture round trips and compatibility notes for current guarded action, queue, template, and lineage payloads. **Outputs**: * Protocol package updates for the new orchestration DTOs and event families. * Validator fixtures and tests covering valid payloads, rejected payloads, and backwards-compatible current snapshots. * Protocol documentation describing the new contracts and deprecated unavailable-only states. **Dependencies / Notes**: * This session should happen before broad server or web work. * Assumption: existing guarded action family/kind names remain canonical unless a protocol test proves a rename is required. **Acceptance Checks**: * Protocol tests pass for every added DTO and event family. * Existing guarded action, queue, template, and lineage consumers still compile. * Documentation names each new DTO/event and its owning surface. #### Session 02: Server Backbone **Objective**: Add the server orchestration backbone without yet implementing every executor family. **Scope**: * Add manager shells and REST route bindings for plan campaigns, attention, executor capabilities, hero lifecycle, permissions, file intents, workpad/evidence, git, terminal, containers, handoffs, diagnostics, channels, and usage metrics. * Implement shared idempotency, expected revision, timeout, audit, event emission, and bounded payload helpers. * Preserve current read-only/local behavior where implementation is not ready, but return structured capability states and repair guidance instead of ambiguous unavailable responses. **Outputs**: * Server manager and route scaffolding under the current server conventions. * Shared orchestration mutation utilities and WebSocket broadcast helpers. * Route tests for validation, stale revisions, duplicate mutation, event emission, and structured capability errors. **Dependencies / Notes**: * Depends on Session 01 contracts. * Open question: exact persistence layer for new manager records should follow existing server state patterns unless a current README documents otherwise. **Acceptance Checks**: * Server tests prove each route rejects invalid input and emits expected events for accepted placeholder or real mutations. * Current APIs continue to respond for existing Orchestration panel data. * Docs clearly distinguish scaffolded capability states from implemented execution. #### Session 03: Web Shell And Store **Objective**: Restructure the web orchestration surface around the new contracts while keeping the existing compact panel usable. **Scope**: * Extend `orchestrationApi` for the new routes and mutation helpers. * Add store slices and WebSocket reducers for plans, attention, executors, hero lifecycle, permissions, file intents, workpad, evidence, diagnostics, channels, and metrics. * Split the current panel into shell, header, tabs, drawers, and focused subcomponents for queue, attention, campaigns, templates, lineage, executors, diagnostics, federation, and metrics. * Add refresh-on-mutation behavior, loading states, capability states, and stale revision handling. **Outputs**: * Focused Orchestration web components replacing the monolithic operational modal internals. * Store/API reducer tests for every WebSocket event family added in Session 01. * A compact panel that still shows current queue, templates, lineage, and guarded actions while deeper tabs are introduced. **Dependencies / Notes**: * Depends on Sessions 01 and 02. * Assumption: the existing panel remains the entry point; new work should not create a separate landing page or disconnected command center. **Acceptance Checks**: * Existing Orchestration panel behavior is preserved in component tests. * New store slices hydrate from route snapshots and update from WebSocket events. * The detail modal can render empty, unavailable, observe-only, and executor-ready states without crashing. #### Session 04: Campaign Workbench **Objective**: Turn the queue into a plan and campaign workbench with real mutation and dispatch controls. **Scope**: * Implement plan/campaign intake, plan preview, dependency graph, task prompt editing, approval, cancel, pause, resume, retry failed, refine, and dispatch flows. * Expand queue details with source, owner hero, related plan/template, revision timeline, last transition, task dependencies, verification status, evidence/workpad links, and scoped drawers. * Add queue mutations for create from template, update state, reject with reason, restore, mark unavailable, and dispatch. **Outputs**: * `planCampaignManager` behavior and routes backed by current server state. * `CampaignWorkbench` and `QueueWorkbench` UI flows. * Tests for idempotent plan mutations, stale revision conflicts, task graph rendering, and queue mutation controls. **Dependencies / Notes**: * Depends on Sessions 01 through 03. * Open question: plan decomposition can initially accept manual task input if a model-backed decomposer is not yet available locally. **Acceptance Checks**: * A user can create or preview a campaign, approve dispatch, pause/resume, cancel, and retry failed tasks from Orchestration. * Queue rows remain summary-only while task artifacts open in scoped details. * API, store, component, and route tests cover successful and rejected mutations. #### Session 05: Attention And Permissions **Objective**: Merge plans, permissions, guarded actions, blocked tasks, and review gates into one operator attention queue. **Scope**: * Implement `attentionManager` and permission request round trips for blocking hooks, plan approvals, local proposals, async notices, stale queue decisions, failed verification, and review gates. * Add timeout, requester, family/kind, risk, preview, target, revision, expected result, reason, actor, and result state to attention items. * Wire approve/reject decisions from the panel through reason capture and audited result updates. **Outputs**: * Unified `AttentionQueue` UI and server-backed attention snapshot. * Permission and plan approval response adapters for supported providers. * Tests for timeout behavior, blocking response persistence, rejected stale decisions, and visible attention counts. **Dependencies / Notes**: * Depends on Sessions 01 through 04 for contracts, routes, store, and campaign states. * Assumption: unsupported provider hooks appear as capability errors, not as silently dropped attention items. **Acceptance Checks**: * Guarded actions, permission requests, plan approvals, blocked tasks, and review gates appear in one queue with correct urgency labels. * Approve/reject decisions record who, when, why, revision, and result. * Blocking permission requests unblock or time out through tested response paths. #### Session 06: Executor Registry **Objective**: Make guarded actions executable through explicit family capabilities and execution runs. **Scope**: * Build an executor registry keyed by family/kind with input schemas, preview renderers, probes, timeout, result schema, cleanup notes, and rollback notes. * Add capability states for unavailable, observe-only, proposal-only, approved-not-executing, executor-ready, executing, executed, and failed. * Make approval trigger decision, execution, and result persistence when a family is executor-ready; otherwise return structured repair guidance. **Outputs**: * `executorRegistry` and execution run routes with capability probes and run history. * `ExecutorFamiliesPanel` with compact status cards and scoped result drawers. * Tests for execution state transitions, unsupported family errors, bounded outputs, and event emission. **Dependencies / Notes**: * Depends on Sessions 01, 02, 03, and 05. * Assumption: broad list rows never expose command bodies, diffs, terminal output, or raw artifacts; drawers own detailed content. **Acceptance Checks**: * Executor-ready approval produces an execution run and final result state. * Non-ready families return visible repair guidance and do not claim success. * Execution run history is visible from guarded actions and family cards. #### Session 07: Provider Diagnostics **Objective**: Surface provider, model, IDE, setup, and runtime readiness as actionable orchestration capability. **Scope**: * Probe Claude Code, OpenCode, Cursor, Bedrock, Vertex, hooks, model discovery, permission mode support, plan mode support, fork/handoff support, IDE/open file readiness, project setup docs, package manager, commands, env examples, scan roots, and running services. * Add diagnostics for server connection, listener PID health, spool health, queue capacity, template availability, graph degradation, guarded-action expiry, provider readiness, and isolation posture. * Add recovery actions or exact CLI repair commands where the server cannot safely repair in process. **Outputs**: * `diagnosticsManager` and provider/setup capability snapshots. * Header capability matrix and `DiagnosticsRecoveryPanel`. * Tests for probe normalization, redacted env reporting, recovery route guards, and disabled reason rendering. **Dependencies / Notes**: * Depends on Sessions 01 through 03 and should precede deep executor rollout. * Assumption: secret values are never returned to the browser; only missing or present names and redacted metadata are allowed. **Acceptance Checks**: * The panel explains why a provider, hook, IDE, setup, or runtime capability is disabled. * Recovery actions either perform a tested safe repair or show an exact command with clear limits. * Setup readiness can create or link a "needs setup" task source. #### Session 08: File And Git **Objective**: Implement file intent protection and Git workbench execution as the first concrete executor families. **Scope**: * Add active write/edit file intents with owner hero, operation, path label, TTL, related task, conflict state, and resolution action. * Emit and display file conflict prevented events and link conflicts to queue items, guarded actions, and reassignment or override decisions. * Implement Git proposals and executions for changes, stage, unstage, commit, push, stash, revert, switch branch, dirty state, conflicts, git-risk guards, and per-agent attribution where available. **Outputs**: * `fileIntentManager` and `gitWorkbenchManager` with guarded executor wiring. * File intent lane and Git workbench summaries inside Orchestration. * Tests for conflict checks, lock TTL, guarded Git risk previews, execution results, and attribution display. **Dependencies / Notes**: * Depends on Sessions 05 through 07. * Assumption: file paths shown broadly should use stable repo-relative labels and avoid leaking absolute paths. **Acceptance Checks**: * Conflicting writes/edits surface as actionable warnings tied to owners and tasks. * Git proposals can be approved or rejected and record execution results. * Dirty/conflict state and file-intent state update live in the panel. #### Session 09: Heroes And Lineage **Objective**: Add internal hero lifecycle controls and deepen lineage into an operator roster. **Scope**: * Implement spawn, fork, handoff, resume, message, stop, dismiss, model change, permission mode change, and isolation mode lifecycle intents. * Track provider, model, permission mode, worktree, process IDs, terminal or listener associations, lifecycle state, unavailable reasons, and events. * Expand lineage with active/completed subagent rows, parent hero, child mission, subagent type, description, state, timing, degraded reasons, filters, and future guarded stop/resume/reassign hooks. **Outputs**: * `heroLifecycleManager`, lifecycle routes, and lineage event handling. * `HeroLifecyclePanel` and `LineageOperatorView`. * Tests for lifecycle command validation, state transitions, malformed lineage events, duplicate events, and degraded graph explanations. **Dependencies / Notes**: * Depends on Sessions 01 through 07. * Open question: process ownership and listener association should match the current hook/listener implementation discovered during Session 07. **Acceptance Checks**: * Orchestration can launch or control supported heroes and show unavailable reasons for unsupported commands. * Subagent roster rows show type, description, parent, state, duration, and completion result. * Lineage degradation is visible and test-covered instead of silently hidden. #### Session 10: Mission Artifacts **Objective**: Bring mission progress, workpad, evidence, verification, and review gates into Orchestration details. **Scope**: * Add mission progress chips for objectives, verification state, elapsed time, token/cost estimates, line-change estimates, last tool family, stalls, and escalations. * Implement durable workpad records, evidence artifact metadata, verification attempts, retry limits, visual check instructions, review decisions, merge/skip-verification actions, and Mission Control links. * Attach artifacts and verification to plans, tasks, queue entries, missions, and execution runs without putting raw contents in broad rows. **Outputs**: * `workpadEvidenceManager` behavior and artifact/review routes. * `WorkpadEvidencePanel` and mission progress integrations for queue, graph, and attention rows. * Tests for artifact metadata, verification retries, review transitions, mission chip rendering, and event reducers. **Dependencies / Notes**: * Depends on Sessions 04 through 06 and benefits from Session 09 mission links. * Assumption: raw evidence file contents remain in dedicated artifact or mission views; Orchestration shows metadata and links. **Acceptance Checks**: * Each plan/task can show workpad, evidence, verification history, and review state. * Budget, stall, verification, and escalation states can raise attention items. * Completed-but-unmerged work can enter the review queue. #### Session 11: Templates And Planning Context **Objective**: Make templates, Quest Board signals, analysis, and transcript memory usable sources for orchestration work. **Scope**: * Expand template details with descriptions, model choices, categories, workflow instructions, constraints, default priority, approval requirement, max queue items, max context labels, prompt preview, read-only badge, and tool-scope badge. * Add template suggestions from selected mission, queue, issue, analysis, and project scan context; support queue item creation and later hero spawn from templates. * Link queue items to suggestions, scan issues, analysis results, project scan items, session follow-ups, auto-improvement candidates, and transcript-mined memory used during planning. * Add controls to include or exclude memory categories before plan generation. **Outputs**: * `TemplateWorkbench` with source links and spawnable or queueable templates. * Quest Board and analysis source attribution in queue/campaign details. * Memory context badges with freshness, confidence, category, and source task attribution. **Dependencies / Notes**: * Depends on Sessions 03 and 04; memory inclusion should integrate with plan generation once Session 04 supports generated plans. * Open question: custom/local template storage should follow the current project settings pattern once schema ownership is clear. **Acceptance Checks**: * A template can create a queue item with a preview and idempotency key. * Queue items show why they exist and which signal or memory informed them. * Failed work can produce auto-improvement proposals in the attention queue. #### Session 12: Terminal And Containers **Objective**: Add terminal PTY execution and isolated runtime support as owned executor capabilities. **Scope**: * Implement terminal capability probing, session count, cwd, shell, status, command preview, env handling, output caps, timeouts, input, kill, restart, exit state, and result attachment to workpad/evidence. * Implement container and isolation diagnostics for Docker, Apple Containers, image state, browser dependencies, auth mount mode, worktree mount, network and port profile, provider/runtime availability, cleanup, and fallback reason. * Add isolated spawn as a guarded lifecycle action once capability checks pass. **Outputs**: * `terminalSessionManager` and `containerRuntimeManager` integrations. * Scoped terminal drawer and isolation capability UI. * Tests for PTY lifecycle, bounded terminal output, kill/restart behavior, container probe states, isolated spawn preview, and cleanup events. **Dependencies / Notes**: * Depends on Sessions 06, 07, and 09. * Assumption: terminal output is never rendered in broad list rows; summaries show command status, exit code, duration, and owning task or hero. **Acceptance Checks**: * The panel can request, approve, run, observe, kill, and record terminal commands when PTY support is ready. * Isolation readiness shows exact fallback reasons and image/runtime state. * Isolated hero spawn is gated by tested capability probes. #### Session 13: Collaboration And Handoff **Objective**: Connect War Room posture, Notice Board decisions, remote access state, handoff, and resume workflows to Orchestration. **Scope**: * Add local-only, room-visible, relay unavailable, catch-up pending, imported, external, remote-originated, and external-transfer-disabled labels for queue, mission, notice, file-intent, guarded action, and hero states. * Link notices to tasks, approvals, conflicts, completions, handoffs, and room state; add post review request, post blocker, and post completion actions. * Implement handoff readiness, handoff scaffold creation, secret scan result, validation, staleness checks, branch/file-state checks, resume queue source, and lineage links. * Summarize remote access/tunnel state without moving sensitive remote controls into Orchestration unless the PRD requires it. **Outputs**: * `FederationNoticePanel` and `handoffManager` integrations. * Room/notice/handoff route and store updates. * Tests for visibility labels, notice linkbacks, handoff validation, staleness checks, resume source creation, and privacy-safe payload rendering. **Dependencies / Notes**: * Depends on Sessions 04, 05, 08, 09, and current War Room/Notice Board APIs. * Open question: remote access controls stay adjacent summary state unless a future PRD explicitly makes Orchestration own tunnel creation. **Acceptance Checks**: * Orchestration rows show whether they are local, room-visible, imported, or remote-originated. * Operators can post bounded review/blocker/completion notices from selected queue or decision contexts. * Handoff and resume flows produce validated, linked records and queue sources. #### Session 14: Channels And Scope **Objective**: Add external command intake and cross-project/session scoping to the Orchestration command flow. **Scope**: * Add channel health, pairing, provider config, validation status, source attribution, generic webhooks, GitHub webhooks, replay guards, and inbound command proposals. * Convert Telegram, Discord, GitHub, and generic webhook events into queue entries, attention items, or guarded actions through the same execution machinery. * Add scope labels and filters for current project, all projects, active room, imported sessions, remote context, project/worktree/source, and session roster state without exposing absolute paths. **Outputs**: * `channelCommandManager` behavior and command intake UI. * Scope controls and filters across queue, graph, attention, and guarded actions. * Tests for webhook validation, replay protection, source attribution, command conversion, and path-safe project labels. **Dependencies / Notes**: * Depends on Sessions 04 through 06 and 13. * Assumption: external channel payloads create proposals first unless a source is explicitly configured for trusted automatic queue intake. **Acceptance Checks**: * Inbound channel or webhook events can become visible queue items, attention items, or guarded actions with source and validation state. * Scope filters consistently affect queue, lineage, attention, and guarded action views. * Project labels avoid absolute path leakage. #### Session 15: Metrics And Notifications **Objective**: Add orchestration telemetry and attention routing for desktop, mobile, and hidden-tab operation. **Scope**: * Add metrics for duration, events, tool-use count, estimated tokens/cost, lines changed, failures, retries, throughput, stalled tasks, blocked age, review backlog, pending approvals age, latency, queue age, executor utilization, provider usage imports, and plan/hero/task rollups. * Add compact attention count, severity distribution, mobile filters, local notification readiness, Web Push VAPID subscribe/unsubscribe, payload categories, and notification routing for approvals, questions, blocked tasks, failed tasks, and review gates. * Link cost projection and usage surfaces where current helpers own the calculation. **Outputs**: * `usageMetricsManager`, `MetricsPanel`, and notification readiness UI. * Header attention summary and mobile-oriented filters. * Tests for metric aggregation, notification preferences, push subscription validation, severity counts, and hidden-tab routing behavior. **Dependencies / Notes**: * Depends on Sessions 04, 05, 06, 09, 10, and 14 for meaningful state. * Open question: exact token/cost math should reuse existing cost helpers if present rather than introducing a second calculation path. **Acceptance Checks**: * Operators can see task, hero, plan, queue, and executor health metrics from Orchestration. * Attention state can notify locally and, when configured, through Web Push. * Severity, age, timeout, and notification routing are test-covered. #### Session 16: Ergonomics And Documentation **Objective**: Finish the command center with keyboard workflows, cross-links, end-to-end coverage, and accurate documentation. **Scope**: * Add keyboard shortcuts for opening Orchestration details, focusing attention, approving/rejecting selected pending items, cycling blocked or failed queue items, filtering states, and launching spawn/handoff flows behind explicit focused controls. * Use historical UI chunk names as a cross-link checklist for current surfaces: Mission Control, Plan Workpad, Permission Modal, Notice Board, Quest Board, War Room, Settings, Git/Codex, terminal, handoff, export, replay, achievements, mission history, channels, remote access, and usage. * Add Playwright coverage for the Orchestration detail modal and update docs in `docs/api/`, `apps/server/README_server.md`, `apps/web/README_web.md`, and `packages/protocol/README_protocol.md` as execution families ship. **Outputs**: * Shortcut handling, accessible shortcut labels, cross-links, and final UI polish across the Orchestration panel. * End-to-end tests for primary approval, campaign, executor, attention, and detail modal flows. * Documentation that replaces obsolete read-only or unavailable claims with the implemented behavior and remaining limits. **Dependencies / Notes**: * Depends on the functional slices it documents and tests. * Assumption: destructive approvals remain behind explicit visible controls even when keyboard focus is active. **Acceptance Checks**: * Keyboard workflows improve operator speed without enabling accidental destructive approvals. * Every historical adjacent surface called out by the study has a current cross-link, capability row, or documented deferment. * End-to-end tests and README updates match the implemented execution families. ### Scope This study compares the current web Orchestration panel with the equivalent historical system preserved under `EXAMPLES/`. The goal is to extract every source-backed opportunity to turn `apps/web/src/components/OrchestrationPanel.tsx` into the real operator command center for task campaigns, internal heroes, approval/permission flow, executor families, diagnostics, handoffs, federation-adjacent state, metrics, and runtime recovery. Second-pass stance: execution is in scope. The current "local/read-only/ unavailable" product boundary is treated as the gap to close, not the target. Reference links are evidence; implementation belongs in the current source tree with current protocol contracts, server managers, store slices, tests, and docs. The `EXAMPLES/` intake caveat remains useful for provenance: [`EXAMPLES/README_examples.md`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/README_examples.md#L108-L121) and [`docs/README_docs.md`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/docs/README_docs.md#L203-L210). ### Current Baseline The current panel is a compact local cockpit surface over four local orchestration streams: | Current surface | Evidence | | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | Header labels the scope as local queue, templates, lineage, and guarded actions | [`OrchestrationPanel.tsx`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/apps/web/src/components/OrchestrationPanel.tsx#L201-L240) | | Queue list has filtering, counts, six-row cap, priority, revision, rejection label, and hero/mission reference openers | [`OrchestrationPanel.tsx`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/apps/web/src/components/OrchestrationPanel.tsx#L252-L296) | | Template list has role filtering and compact tag display | [`OrchestrationPanel.tsx`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/apps/web/src/components/OrchestrationPanel.tsx#L298-L346) | | Lineage shows compact graph nodes, edges, parent/child/subagent labels | [`OrchestrationPanel.tsx`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/apps/web/src/components/OrchestrationPanel.tsx#L348-L396) | | Guarded actions show family/kind/state/revision/result and can approve or reject pending proposals | [`OrchestrationPanel.tsx`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/apps/web/src/components/OrchestrationPanel.tsx#L398-L472) | | Detail modal repeats the four sections but remains primarily read-only | [`OrchestrationPanel.tsx`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/apps/web/src/components/OrchestrationPanel.tsx#L546-L685) | | Approval copy is explicit that local decisions do not execute commands | [`OrchestrationPanel.tsx`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/apps/web/src/components/OrchestrationPanel.tsx#L997-L1011) | The current server and protocol are still bound to a non-executing local subset. Current docs say approved guarded actions return unavailable when no executor exists, and the server does not run file, git, terminal, remote, or container actions: [`docs/api/README_api.md`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/docs/api/README_api.md#L570-L609), [`apps/server/README_server.md`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/apps/server/README_server.md#L496-L521), and [`packages/protocol/README_protocol.md`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/packages/protocol/README_protocol.md#L401-L412). Those lines identify the implementation work to remove or replace as executor families land. ### Historical Reference Shape The example system is much broader than the current panel. `EXAMPLES/` contains: | Reference area | Evidence | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Original package snapshot, curated first-pass artifacts, and analysis notes | [`EXAMPLES/README_examples.md`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/README_examples.md#L41-L48) | | Provenance and AgentCraft/FactionOS naming caveat | [`EXAMPLES/README_examples.md`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/README_examples.md#L50-L68) | | Former extraction report summarizing captured API, WebSocket, hooks, LLM engines, UI, collaboration, and runtime support | [`REPORT.md`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/REPORT.md#L12-L23) | | Extraction coverage note listing what was high/medium confidence | [`extraction-coverage.md`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/extraction-coverage.md#L10-L20) | | Curated artifact index with plugin layer, skills, server data, frontend, Docker, and manifests | [`1st-pass-artifacts/README_1st-pass-artifacts.md`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/README_1st-pass-artifacts.md#L12-L60) | | Reading order for understanding the old package | [`1st-pass-artifacts/README_1st-pass-artifacts.md`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/README_1st-pass-artifacts.md#L72-L84) | | Recovered architecture: hook layer, executors, mission/task system, suggestions, context, external integrations, and utilities | [`findings/architecture.md`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/architecture.md#L90-L203) | | Historical tech stack: Node/Express/ws, Anthropic SDK, Supabase, node-pty, PostHog, web-push, xterm, Web Speech, PWA, 37 named frontend chunks | [`findings/tech-stack.md`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/tech-stack.md#L11-L158) | | Asset/build-output inventory confirming historical modal and panel chunk names such as Spawn, Handoff, Fork, Resume, War Room, Remote Access, Channels, Mission History, Gold Mine, and Transcript | [`asset-inventory.md`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/asset-inventory.md#L36-L88) | | Historical REST inventory, including internal heroes, Codex/git, task queue, remote access, War Room, settings, skills, channels, and webhooks | [`findings/api-routes.txt`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L1-L210) | | Historical WebSocket inventory, including task, plan, terminal, remote, git, mission, internal hero, and War Room event families | [`findings/websocket-events.txt`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/websocket-events.txt#L1-L172) | | Historical user guide covering the operator experience | [`skills/factionos-guide/SKILL.md`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md#L11-L18) | ### Second-Pass Build Thesis Orchestration should become the cockpit's command layer, not an informational sidebar. The end state is an operator surface that can: * create, decompose, dispatch, pause, resume, retry, cancel, verify, and close plans/campaigns; * spawn, fork, handoff, resume, message, stop, and inspect internal heroes; * merge guarded actions, permission requests, plan approvals, blocked tasks, channel/webhook requests, and review gates into one attention queue; * execute file, git, terminal, subagent, mission, handoff, remote access, and container families through explicit executor contracts; * show workpad, evidence, verification attempts, mission progress, cost, token, latency, file-intent, and diagnostics state in one place; * route to War Room, Notice Board, Quest Board, Mission Control, Git/Codex, terminal, handoff, settings, and provider/runtime repair surfaces. Every build target below should resolve to concrete current-source changes: protocol DTOs, validation, managers, REST routes, WebSocket events, Zustand store handlers, `orchestrationApi` calls, React components, tests, and stable docs. Idempotency keys, expected revisions, audit fields, ownership labels, and bounded payloads are not a reason to defer execution; they are the mechanics that let execution ship without corrupting state. ### Implementation Targets Extracted From EXAMPLES #### 1. Turn Queue Into A Campaign Workbench Reference evidence: The old route inventory included a full plan/campaign workflow: task progress, retry, trace, plan approval/cancel/pause/resume/retry-failed/refine/review, evidence, workpad, analytics, cleanup, quality scan, convention extraction, campaign submission, and task lookup ([routes](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L159-L189)). Its plan decomposer produced dependency-ordered tasks with per-task prompt, priority, complexity, dependencies, and verification instructions ([plan schema](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/llm-prompts/plan-decomposer.md#L23-L45)). Downstream, the historical plan was broadcast, approved, dispatched, verified, and mined for knowledge ([downstream flow](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/llm-prompts/plan-decomposer.md#L66-L73)). Current gap: Our queue can create/update/reject in the server, but the web panel only lists existing entries and opens references. It does not submit plans, expose task dependencies, show progress/evidence, pause/resume/cancel/retry, or connect queue items to verification. Implementation moves: * Add a detail-first queue workbench with full queue item summaries, dependency graph, source, owner hero, related plan/template, revision timeline, and last transition. * Ship local controls for queue mutation: create from template, update state, reject with reason, restore, mark unavailable, and dispatch. Keep explicit idempotency keys and stale revision handling. * Add plan/campaign intake: submit feature spec, preview generated plan, edit task prompts, approve plan, cancel plan, pause/resume dispatch, and retry failed tasks. * Add evidence and workpad tabs for each plan/task as part of the executor-ready detail view. List rows stay summary-only; scoped drawers open artifacts. * Add verification status: pending, verifying, passed, failed, skipped, retries, and visual verification instructions for UI tasks. Implementation target: Panel can create and mutate queue entries, create a plan/campaign, approve dispatch, pause/resume/cancel/retry tasks, and show workpad/evidence/ verification for each task. Server work lands in `TaskQueueManager` plus a new plan/campaign manager; web work lands in a queue workbench tab rather than the current six-row summary. #### 2. Add Internal Hero Lifecycle Controls Reference evidence: The old guide says the operator could spawn, fork, handoff, resume, and dismiss agents from the UI, including provider, model, permission mode, worktree, and prompt selection ([hero coordination](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md#L38-L48)). The route inventory backs this with internal hero routes for commands, choice, fork, handoff, messages, model, permission mode, prompt, resume, status, stop, spawn, isolated spawn, and web spawn ([routes](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L84-L107)). Current gap: The current panel can display references and guarded-action decisions, but it does not launch, stop, resume, fork, handoff, or message agents. Implementation moves: * Add an "Agents" or "Executors" section in Orchestration details that lists local executor capability, not just observed heroes. * Implement spawn, fork, handoff, resume, message, and stop commands as first class lifecycle intents. Capability rows can show build status while the executor manager lands. * Add spawn from template: provider, model, permission mode, worktree, isolation toggle, and first prompt. * Add fork/handoff flows through guarded actions and wire them to local process ownership in the same executor contract. * Track lifecycle state: spawning, active, awaiting, idle, stopping, stopped, failed, stale, dismissed, and unavailable. Implementation target: Create an internal hero lifecycle manager that owns command state, process IDs, provider metadata, terminal/listener association, and lifecycle WebSocket events. The Orchestration panel becomes the primary place to launch and control heroes, with deep links into richer hero detail panels. #### 3. Unify Plans, Permissions, And Guarded Actions Reference evidence: The old side panel had plan review and permission requests inline with the hero chat/git/files workflow ([side panel](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md#L101-L112)). Permission modes included plan mode, bypass permissions, and default/manual approval ([permission modes](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md#L137-L145)). The permission hook was designed to block internal heroes until UI approval, polling response files with a 10 minute timeout ([permission hook](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-permission-request.sh#L1-L13), [`ExitPlanMode` flow](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-permission-request.sh#L46-L94), [`PermissionRequest` flow](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-permission-request.sh#L96-L154)). The old route inventory included pending approvals and plan approval request and response endpoints ([routes](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L118-L122)). Current gap: We have separate current surfaces for permissions and plan workpad elsewhere, while OrchestrationPanel only handles guarded action proposal decisions. The operator cannot see one unified approval queue. Implementation moves: * Add an "Attention" lane that merges guarded actions, permission requests, plan approvals, stale queue decisions, and blocked tasks. * Label each request as blocking hook, local proposal, plan review, or async notice so operators understand urgency. * Show timeout/expiry, requester, family/kind, risk, preview, target, revision, and expected result. * Add reason input for approve/reject and record who/when/why. * Link plan approvals to generated task graph and verification instructions. Implementation target: Implement the blocking hook round trip for supported providers with explicit response adapters. Permission requests, plan approvals, and guarded actions all appear in the same attention queue with timeout, requester, revision, reason, and result state. #### 4. Evolve Guarded Actions Into Executable Families Deliberately Reference evidence: The current protocol already names file, git, terminal, subagent, mission, handoff, remote access, and container families ([protocol](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/packages/protocol/src/guardedActions.ts#L1-L29)). The old system had concrete supporting mechanics: * bash command tracking with command truncation and subagent detection ([bash hook](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-bash-command.sh#L15-L38)) * file access with read/write/edit classification, line counts, and synchronous conflict checks ([file hook](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-file-access.sh#L27-L74), [conflict check](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-file-access.sh#L76-L116)) * git-risk interception before command tracking ([git guard](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-git-guard.sh#L3-L19), [classification](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-git-guard.sh#L38-L88)) * old Codex/git routes for branches, changes, commit, generate commit message, push, revert, stage, stash, switch branch, and unstage ([routes](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L42-L54)) * old file routes for blame, conflict check, diff, operations, and open-file ([routes](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L78-L81), [open-file](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L115-L115)) Current gap: Approval records do not run anything. This leaves several named families as inert labels. Implementation moves: * Add per-family status cards: `unavailable`, `observe-only`, `proposal-only`, `approved-not-executing`, `executor-ready`, `executing`, `executed`, and `failed`. * Build an executor registry keyed by family/kind. Each executor declares input schema, preview renderer, required capability probes, timeout, result schema, and rollback/cleanup notes. * Implement git/file first, then subagent/mission/handoff, then terminal, container, remote access, and channel-created command intake. * Make approve trigger `decision -> execution -> result` when `executor-ready`; otherwise return a capability error with repair guidance. * Keep broad rows compact; command bodies, diffs, terminal output, and artifacts live in scoped drawers with copy/open controls. Implementation target: Approve becomes an execution decision for executor-ready families. The protocol already has `executed`, `failed`, and `unavailable` result states; the server needs executor dispatch and result persistence to make those states real. #### 5. Show File Conflict Protection As First-Class Orchestration Reference evidence: The old file hook could synchronously deny write/edit when another agent held a lock, returning a provider-specific denial reason ([file conflict flow](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-file-access.sh#L76-L116)). The user guide exposed file conflict protection as an on-by-default setting ([settings](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md#L315-L335)). Historical routes and events included file conflict checks, collaboration file intents, and conflict-prevented events ([routes](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L55-L58), [`/file-conflict-check`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L79-L79), [`file_conflict_prevented` and intents](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/websocket-events.txt#L38-L41)). Current gap: The panel does not show file locks, intents, contention, lock owner, TTL, or which task/hero is blocked by a conflict. Implementation moves: * Add a "File intents" section showing active write/edit locks with owner hero, file basename or relative path, operation, TTL, and related task. * Emit and display `file_conflict_prevented` as an actionable warning with a suggested alternate task or reassignment. * Add queue/guarded-action references to file locks so reviewers can resolve conflicts from the panel. * Add settings status: protection on/off/unavailable, scan root, ignored paths. Implementation target: File-intent state becomes a live orchestration lane. The panel shows who owns a write/edit intent, which task is blocked, how long the intent has left, and the resolution action: reassign, wait, split task, or override through a guarded action. #### 6. Deepen Subagent Lineage From Compact Graph To Operator View Reference evidence: The old guide represented Claude Task tool subagents as units that spawn near the parent, travel based on work type, disappear on completion, and can be cycled with Tab ([units](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md#L61-L68)). The hook map sends Task/Agent through subagent spawn and SubagentStop through subagent complete ([hook map](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-config.json#L33-L49), [`SubagentStop`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-config.json#L122-L130)). The spawn hook forwards subagent type and description ([subagent hook](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-subagent-spawn.sh#L15-L30)). Historical routes and events included subagent/session and agent lifecycle events ([`/subagents/:sessionId`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L148-L148), [`agent_start` and related events](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/websocket-events.txt#L8-L11), [`subagent_spawn`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/websocket-events.txt#L138-L138)). Current gap: Our lineage section shows mission graph nodes and edge labels, but not a subagent roster, durations, type/description, current task, owning hero, or control actions. Implementation moves: * Add active/completed subagent rows under each graph node: type, description, parent hero, child mission, state, start/end times, degraded reason. * Add filters by parent hero, state, and subagent type. * Add a lineage detail drawer that explains degradation: missing ID, malformed ID, duplicate event, missing parent/child, unsupported payload. * Later add guarded stop/resume/reassign actions after executor support exists. Implementation target: Lineage grows from compact graph to operator roster: parent, subagent type, task description, current state, duration, completion result, and control actions. Raw prompts/transcripts stay in dedicated mission/transcript detail surfaces; orchestration renders the control summary. #### 7. Bring Mission Progress Into Orchestration Reference evidence: The old guide made every prompt a mission with tracker objectives, full Mission Control, duration, token usage, cost, lines changed, and historical summaries ([missions](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md#L69-L78)). The WebSocket inventory includes mission, mission history, mission summary, task progress, verification, budget warning/exhausted, plan workpad, and plan completion events ([events](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/websocket-events.txt#L83-L116), [`task_progress_update`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/websocket-events.txt#L140-L146)). Current gap: The panel links graph nodes to missions but does not show mission objectives, progress, budget, verification, or summary context. Implementation moves: * Add mission-progress chips to queue and lineage rows: active objective count, verification status, elapsed time, token/cost estimate, line-change estimate, last tool family. * Add "open Mission Control" links from selected queue/graph rows. * Add task progress events and near-stall/stalled/escalation states once the server emits them. * Show budget warning/exhausted states as attention items rather than burying them in a mission-only panel. Implementation target: Mission state becomes first-class orchestration context. Queue rows, graph nodes, and attention items all show objective progress, budget/cost, elapsed time, verification state, and stalled/escalated signals. #### 8. Upgrade Templates From Tags To Spawnable Roles Reference evidence: The curated `agent-templates.json` includes named templates with display names, descriptions, model choices, categories, detailed workflow instructions, and read-only constraints for review/planning roles ([templates](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/agent-templates.json#L1-L127)). The old artifact index calls this "Built-in agent templates" ([index](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/README_1st-pass-artifacts.md#L45-L53)). Current gap: The panel renders template name, role, local-only label, and tags, but no description, prompt/instructions, model, category, allowed tools, constraints, suggestion rationale, or "queue from template" action. Implementation moves: * Expand template detail rows with summary, default priority, approval requirement, max queue items, max context, constraints, and prompt preview. * Add template suggestions from selected mission/queue/issue context. * Add "create queue item from template" with title/summary/prompt preview and idempotency key. * Add read-only badge and tool-scope badge for reviewer/planner templates. * Support custom/local project templates after schema and storage are defined. Implementation target: Templates become spawnable/queueable role blueprints. A template can create a queue item, seed a plan task, or spawn an internal hero when the selected provider/executor is ready. #### 9. Add Workpad, Evidence, And Verification Surfaces Reference evidence: The old route inventory exposes task evidence, plan evidence, workpad, review, merge, skip-verification, and verification endpoints ([task evidence](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L29-L30), [`/task-queue/:planId/workpad`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L179-L179), [`/verify`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L198-L198)). The plan decomposer schema required visual instructions for UI task self-verification ([schema](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/llm-prompts/plan-decomposer.md#L35-L41)). Current gap: The current OrchestrationPanel detail modal has no workpad, evidence artifacts, review gate, or verification history. Implementation moves: * Add task/plan detail tabs: overview, dependencies, workpad, evidence, verification, decision history. * Store evidence metadata first: filename label, type, createdAt, owner, task, checksum/size if needed. Avoid raw file content in broad list rows. * Add verification attempts with status, max retries, failure reason, and visual check instructions. * Add review queue integration for completed-but-unmerged work. Implementation target: Each plan/task has durable workpad, evidence, review, and verification records. The panel shows artifact metadata, verification attempts, reviewer decisions, merge/skip-verification actions, and links to the owning mission/queue item. #### 10. Reconnect Quest Board And Analysis To Orchestration Reference evidence: Historical prompt notes describe next-step suggestions when a hero idles ([idle suggestions](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/llm-prompts/idle-suggestion-engine.md#L7-L10)), bounded, specific, non-generic suggestions ([rules](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/llm-prompts/idle-suggestion-engine.md#L19-L49)), on-demand analysis for issues worth spawning an agent to fix ([analysis prompt](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/llm-prompts/on-demand-analysis.md#L16-L35)), and auto-improvement tasks triggered by failure rate or long-running tasks ([auto-improver](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/llm-prompts/auto-improver.md#L7-L14)). The old UI rendered idle suggestions as side-panel cards with numeric accept shortcuts ([frontend rendering](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/llm-prompts/idle-suggestion-engine.md#L81-L88)). Current gap: Our Quest Board is strong but separate. OrchestrationPanel does not show why a queue item exists, which suggestion/analysis produced it, or how failed tasks feed self-improvement. Implementation moves: * Add "source" links from queue items to suggestions, scan issues, analysis results, project scan items, and session follow-ups. * Add queue actions for Quest Board accepts: accept as queue item, assign to idle hero, dismiss, or convert to plan. * Add failure-metrics widgets: failure rate, long-running count, stalled tasks, auto-improvement candidate count. * Feed auto-improvement proposals into the attention queue with accept/run, dismiss, and convert-to-plan controls. Implementation target: Quest Board and analysis results become task sources. The Orchestration panel must show why a task exists, what signal produced it, and whether failed work created a follow-up improvement task. #### 11. Add Transcript-Mined Memory To Planning Context Reference evidence: The transcript miner extracted workspace facts, conventions, anti-patterns, build fixes, confidence, tags, and source task IDs from completed campaigns ([transcript miner](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/llm-prompts/transcript-miner.md#L31-L43)). The notes call this a learning loop for future plans and analyses ([why it matters](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/llm-prompts/transcript-miner.md#L51-L79)). Current gap: The current panel does not show what learned context informed a plan, queue item, template suggestion, or analysis issue. Implementation moves: * Add "context used" badges for plan decomposition and template suggestions: conventions, build fixes, anti-patterns, confidence, source mission/task. * Add an operator control to include/exclude memory categories before generating a plan. * Add memory freshness and source attribution in detail views. Implementation target: Transcript-mined memory becomes visible planning context. Plan generation, template suggestions, and analysis tasks show which conventions, fixes, anti-patterns, and source tasks informed them, with drill-down to the memory record. #### 12. Surface Terminal And PTY As Capability, Not Default UI Reference evidence: The old guide had an integrated xterm.js terminal with tabs, persistent PTYs, restart-on-exit, and project-directory shell startup ([terminal guide](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md#L125-L136)). The tech stack identifies node-pty and xterm.js as the historical backend and frontend pieces ([node-pty](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/tech-stack.md#L35-L44), [`xterm.js`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/tech-stack.md#L100-L116)). The WebSocket inventory included terminal output and exit events ([events](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/websocket-events.txt#L148-L149)). Current gap: The panel has no terminal status or PTY capability row, and guarded terminal actions are explicitly non-executing. Implementation moves: * Add a terminal executor capability row connected to real PTY availability, session count, cwd, shell, status, and kill/restart controls. * Add terminal sessions as explicit guarded local actions with command preview, cwd, shell, env handling, output caps, timeout, and kill control. * Keep terminal output in a scoped terminal drawer; summaries show command status, exit code, duration, and owning task/hero. Implementation target: Terminal execution lands as an owned executor family, not a separate hidden feature. The panel can request a command, approve/run it, watch state, kill it, and attach the result to workpad/evidence. #### 13. Add Git/Codex Workbench Cross-Links Reference evidence: The old guide had a Git/Codex panel for pending changes, syntax-highlighted diffs, staging, reverting, edit attribution, and hunk navigation ([git panel](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md#L224-L232)). Historical routes include Codex branches, changes, commit, commit-message generation, push, revert, stage, stash, switch branch, and unstage ([routes](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L42-L54)). Historical events include git conflict, dirty, and pushed states ([events](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/websocket-events.txt#L44-L46)). Current gap: OrchestrationPanel has no git-state lane and no per-agent edit attribution. Implementation moves: * Add a "workspace changes" summary: dirty state, changed files count, conflict count, last actor, linked queue/task. * Add guarded Git proposal previews: stage, unstage, commit, push, stash, revert. * Add per-agent attribution if current file-access/tool-use data can support it without exposing raw paths broadly. * Integrate git-risk guards into guarded action proposals. Implementation target: Git becomes an execution family and adjacent workbench. The Orchestration panel shows dirty/conflict state, can propose stage/unstage/commit/push/stash/revert, and records each result against the owning task/mission. #### 14. Show Provider, Model, IDE, And Runtime Capability Reference evidence: The old guide supported Claude Code, OpenCode, Cursor, and a browser-based Claude Cloud mode ([providers](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md#L147-L158)). It had custom model handling, inherit mode for Bedrock/Vertex, per-hero model changes, fork inheritance, and Cursor model discovery ([models](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md#L160-L220)). Historical routes included Cursor/OpenCode models, IDE detection, project rules, MCP/plugins/skills, and provider agent config ([routes](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L61-L75), [`/cursor/models` and `/opencode/models`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L73-L116)). Current gap: The panel does not summarize provider readiness, model defaults, permission-mode support, IDE/open-file availability, or why a provider is disabled. Implementation moves: * Add a capability matrix: provider installed, hook installed, model list available, supports manual permission, supports plan mode, supports fork, supports handoff, supports isolation. * Add provider-specific disabled reasons and repair links to CLI doctor. * Add model display for selected hero/queue template with future guarded model change proposals. * Add IDE/open-file readiness only as local capability metadata. Implementation target: Provider readiness becomes a capability matrix. The browser gets capability booleans, model labels, and repair state; the server owns probing for Claude Code, OpenCode, Cursor, Bedrock, Vertex, hook install, model discovery, and IDE integration. #### 15. Add Isolation Runtime Planning Reference evidence: The old guide supported Docker and Apple Containers, each agent receiving a separate localhost, with worktree volume mounts, auth handling, runtime probing, and graceful fallback ([isolated heroes](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md#L49-L60)). The Dockerfile shows a Node 20 image, Chromium dependencies, Claude Code, agent-browser, non-root `agent`, OpenCode, Cursor CLI, and `/workspace` mount ([Dockerfile](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/Dockerfile.isolated#L1-L11), [`Dockerfile`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/Dockerfile.isolated#L43-L69)). Troubleshooting includes runtime detection and fallback expectations ([troubleshooting](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/references/troubleshooting.md#L201-L220)). Historical routes include container refresh and isolated spawn ([routes](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L72-L72), [`spawn-isolated`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L106-L106)). Current gap: The panel has no isolation posture beyond current docs saying executors and container routes remain unavailable. Implementation moves: * Add isolation capability diagnostics: Docker available, Apple Containers available, image built, browser deps ready, auth mount supported, fallback reason. * Add queue/template isolation requirement labels before execution exists. * Later wire isolated spawn as a guarded action with volume, cwd, provider, network, browser, env, and cleanup preview. Implementation target: Isolation becomes a runtime target for internal heroes and executor actions. The panel shows Docker/Apple Containers readiness, image state, auth mount mode, network/port profile, cleanup state, and fallback reason; isolated spawn is a first-class lifecycle command. #### 16. Integrate War Room And Remote Access As Adjacent State Reference evidence: The old War Room federated multiple local instances through a Cloudflare Durable Object relay, sharing hero state, missions, basename-only file access, session roster, and notice board messages, but not file contents, prompts, transcripts, or terminal access ([War Room](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md#L279-L293)). External-services notes repeat the Worker privacy posture ([external services](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/external-services.md#L12-L24)). Remote access generated expiring tokenized tunnel links ([remote access](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md#L268-L278)). Routes include remote access and War Room operations ([remote routes](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L129-L133), [`warroom` routes](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L200-L207)). Current gap: War Room exists as a separate panel and Worker backend. OrchestrationPanel does not summarize whether a task/hero/queue item is local-only or visible in a room. Implementation moves: * Add room-local/room-visible labels to queue, mission, and guarded-action rows. * Show a compact "federation posture" summary: local-only, room connected, relay unavailable, catch-up pending, external transfer disabled. * Add notice cross-links for room notices that relate to queue/task conflicts. * Keep remote access/tunnel controls outside OrchestrationPanel unless the PRD makes it the operator command center. Implementation target: Orchestration rows carry federation posture. The panel shows whether queue, mission, notice, file-intent, and hero states are local-only, room-visible, or remote-originated. Worker payload contracts stay explicit and versioned. #### 17. Connect Notice Board To Orchestration Decisions Reference evidence: The historical notice-board skill defined status, question, review, announcement, conflict, and completion notices with scripts to post/list them ([notice skill](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/notice-board/SKILL.md#L15-L53)). The old War Room guide included notice board messages in the shared room context ([shared state](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md#L285-L288)). Current gap: The current Notice Board exists, but OrchestrationPanel does not show notices attached to tasks, approvals, conflicts, or handoffs. Implementation moves: * Add related notice count and latest notice summary to queue/task/guarded rows. * Add "post review request", "post blocker", and "post completion" actions from selected queue/task after notice validation. * Auto-post bounded completion/conflict notices for future executor transitions. Implementation target: Notice Board becomes an orchestration side channel. Queue/tasks/permissions can post status, question, review, conflict, and completion notices; room-visible notices link back to the owning task/decision. #### 18. Add Handoff And Resume Workflows Reference evidence: The handoff skill supported session transfer from a source session UUID, document handoff creation, resume, proactive handoff suggestion after substantial work, validation, staleness checks, and chaining ([handoff skill](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-handoff/SKILL.md#L14-L55), [`CREATE`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-handoff/SKILL.md#L58-L119), [`RESUME`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-handoff/SKILL.md#L120-L174)). The template captured metadata, architecture, critical files, completed work, decisions, pending work, assumptions, gotchas, environment state, and resources ([template](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-handoff/references/handoff-template.md#L34-L142)). Current gap: The current protocol names handoff as a guarded action family/kind, but the panel does not manage handoff documents, handoff readiness, or resume context. Implementation moves: * Add handoff readiness indicators for long-running or context-heavy tasks. * Add "create handoff" proposal from selected mission/queue with metadata scaffold and secret scan result. * Add "resume from handoff" queue source with staleness and branch checks. * Link handoff lineage into mission graph. Implementation target: Handoff and resume become lifecycle actions. The panel creates handoff scaffolds, validates them, shows staleness/branch/file-state checks, and turns a resume checklist into a new queue source or hero resume command. #### 19. Add App Setup And Environment Readiness Reference evidence: The app-setup skill checks for `.factionos/app-setup.md`, otherwise reads project docs/package files, discovers install/dev commands, and considers env examples ([app setup](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/app-setup/SKILL.md#L7-L15)). The historical guide exposed project filter, default model, quest ignore, IDE, analytics, teams, and visual settings ([settings](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md#L315-L335)). Current gap: OrchestrationPanel does not show environment readiness for tasks: dependencies, dev server, env file, scan root, or workspace script availability. Implementation moves: * Add per-project setup status: setup doc present, package manager detected, install command known, dev command known, env example present, scan root ready. * Add queue/task preflight checks before execution: clean worktree, deps ready, server ports, required env names present, no secret values shown. * Add "needs setup" task source when setup is missing. Implementation target: Environment readiness becomes task preflight. The panel shows setup docs, package manager, install/dev/test commands, env example coverage, running services, and missing setup tasks; installs and dev-server starts route through executor proposals. #### 20. Add Diagnostics And Recovery From The Operator Panel Reference evidence: Historical troubleshooting covered server, WebSocket, hooks, stuck heroes, permissions, suggestions, remote access, isolated agents, achievements, and factory reset ([troubleshooting](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/references/troubleshooting.md#L23-L260)). Listener spawning used terminal PID files and saved session IDs ([hero spawn listener](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-hero-spawn.sh#L57-L106), [`spawn-listeners.sh`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/spawn-listeners.sh#L19-L45)). Current gap: The current panel only shows loading/unavailable banners for orchestration snapshots. Diagnostics live mostly in CLI/status/doctor paths. Implementation moves: * Add a diagnostics drawer: server connection, hook install status, listener PID health, spool health, queue capacity, template availability, graph degradation, guarded-action expiry, provider capability, isolation posture. * Add repair actions that either call an owned recovery endpoint or generate the exact CLI command for the operator. * Link stale listener/spool recovery to `factionos doctor --recover-orchestration` and make clear what it does not erase. Implementation target: Diagnostics become actionable from Orchestration. The panel can show server, hook, listener, spool, provider, isolation, queue, graph, and guarded-action health, then trigger supported repairs or hand the operator an exact command. #### 21. Add Attention Notifications And Mobile-Oriented States Reference evidence: The old guide had mobile PWA, QR remote connect, background push for plan approvals/permission requests/questions, haptics, and mobile chat ([mobile PWA](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md#L294-L305)). Historical routes included push subscribe/unsubscribe/VAPID key ([routes](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L126-L128)). Current gap: The current web app supports local notifications but not push. OrchestrationPanel does not expose an attention queue tuned for mobile or hidden-tab operation. Implementation moves: * Add a compact attention count and severity distribution to the panel header. * Add mobile-friendly filters: awaiting approval, blocked, failed, stalled, needs review, remote conflict. * Implement local notification readiness first, then Web Push with VAPID, subscribe/unsubscribe, payload categories, and mobile attention filters. Implementation target: Attention state works on desktop, mobile, and hidden-tab operation. The panel owns severity, age, timeout, and notification routing for approvals, questions, blocked tasks, failed tasks, and review gates. #### 22. Add Metrics, Cost, And Usage Links Reference evidence: The old mission model included duration, token usage, cost, and lines changed ([missions](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md#L69-L77)). The guide had a Gold Mine usage quota surface ([usage](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md#L233-L237)). Routes included Claude stats, usage, hero metrics, token stats by executor, and usage ([routes](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L21-L31), [`hero metrics`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L83-L83), [`/usage`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L197-L197)). Current gap: The panel has counts but not cost, throughput, token, latency, failure-rate, or executor utilization metrics. Implementation moves: * Add metrics by selected queue/plan/hero: duration, events, tool-use count, estimated tokens/cost, lines changed, failures, retries. * Add aggregate queue health: throughput, stalled tasks, blocked age, review backlog, pending approvals age. * Add cost projection links if current cost helpers already own the calculation. Implementation target: Metrics become orchestration telemetry. The panel shows task/hero/plan throughput, token/cost estimates, provider usage imports when available, latency, retry/failure rate, queue age, and executor utilization. #### 23. Add Keyboard Shortcuts And Control-Group Ergonomics Reference evidence: The old guide and shortcut reference included hero selection, state cycling, control groups, panel toggles, mission/git/timeline/search, handoff/fork, terminal, subagent cycling, suggestions, and help ([guide shortcuts](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md#L400-L415), [`keyboard reference`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/references/keyboard-shortcuts.md#L8-L90)). Current gap: The panel has filters and buttons but no orchestration-specific keyboard workflow beyond existing global cockpit shortcuts. Implementation moves: * Add shortcuts for opening Orchestration details, focusing approval queue, approving/rejecting selected pending action, cycling blocked queue items, and filtering by pending/blocked/failed. * Add accessible shortcut labels in the existing shortcuts modal. * Keep destructive approvals behind focused, explicit controls to avoid accidental keyboard approvals. Implementation target: Keyboard control becomes part of the operator loop. Add shortcuts for opening orchestration, focusing the attention queue, approving/rejecting the selected item, cycling blocked/failed tasks, and launching spawn/handoff flows. #### 24. Cross-Project And Session Scope Reference evidence: The old guide supported filtering to the current project by default, showing all projects when disabled, and preserving hidden heroes in memory/disk ([project filter](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md#L337-L345)). Historical routes and events included sessions, all sessions, session roster, transcripts, and remote transcript updates ([routes](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L19-L24), [`sessions`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L138-L138), [`transcript`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L195-L195), [`session_roster`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/websocket-events.txt#L134-L134)). Current gap: The panel does not expose whether orchestration state is current-project only, all-projects, imported, external, or remote. Implementation moves: * Add scope label: current project, all projects, active room, imported sessions, or remote context. * Add project labels and counts without absolute path leakage. * Add filters by project/worktree/source for queue, graph, and guarded actions. Implementation target: Scope is visible and filterable. The panel can switch current project, all projects, room context, imported sessions, and remote-originated state while keeping stable repo/worktree labels. #### 25. Channel And Webhook Command Intake Reference evidence: Historical routes included channel pairings, provider config, channel status, generic webhooks, and GitHub webhooks ([channel routes](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L35-L39), [`webhooks`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L208-L209)). External service notes identify Telegram and Discord channel adapters as historical surfaces, with current adapters limited differently ([external services](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/external-services.md#L50-L66)). Current gap: The panel does not represent inbound command requests, external channel health, or webhook-created queue items. Implementation moves: * Show inbound command proposals as guarded actions and queue entries. * Add channel health, pairing, provider config, validation status, and command source attribution. * Convert webhook requests into queue items with source, validation status, replay guard, and run controls. Implementation target: Channels and webhooks become orchestration intake. Telegram/Discord/GitHub/ generic webhook events can create queue entries, attention items, or guarded actions, then flow through the same execution machinery. #### 26. Use Historical UI Chunks As A Cross-Link Checklist Reference evidence: The historical Vite output preserved named chunks for operator surfaces: SpawnModal, HeroHandoffModal, HeroForkModal, ResumeSessionModal, WarRoomModal, RemoteAccessModal, ChannelsModal, MissionHistoryModal, GoldMinePanel, TranscriptModal, SettingsPanel, TownHallPanel, BarracksPanel, BuildingPanel, and others ([asset inventory](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/asset-inventory.md#L56-L88)). The tech-stack note also lists 37 component chunks, including spawn, fork, handoff, mission history, terminal-adjacent remote access, War Room, and settings surfaces ([component chunks](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/tech-stack.md#L122-L139)). Current gap: The current OrchestrationPanel is isolated from several adjacent cockpit surfaces that should be one click away from orchestration decisions. Implementation moves: * Treat the historical chunk names as a routing checklist, not as code to copy. * Add cross-links from Orchestration detail rows to existing current surfaces: mission detail, Plan Workpad, Permission Modal, Notice Board, Quest Board, War Room, Settings, achievements, and export/replay where relevant. * For future surfaces, reserve panel slots/capability rows and link them to the relevant build target rather than hiding the orchestration family. Implementation target: Use historical chunk names as route and interaction coverage, not copied UI. Build current React components that connect Orchestration to Mission Control, Plan Workpad, Permission Modal, Notice Board, Quest Board, War Room, Settings, Git/Codex, terminal, handoff, export, and replay surfaces. ### Balls-To-The-Wall Implementation Plan This is the aggressive build plan implied by the EXAMPLES study. It assumes the panel is becoming the command center and the server/protocol must catch up. #### Track A: Protocol And Events Implement or extend protocol packages before broad UI work: * `PlanCampaign`: plan id, title, source prompt/spec, owner, state, tasks, dependencies, generatedAt, approvedAt, pausedAt, completedAt, revision. * `PlanTask`: task id, prompt, priority, complexity, dependencies, verification instructions, executor assignment, queue entry, mission, state. * `AttentionItem`: merged view over guarded actions, permissions, plan approvals, blocked tasks, channel commands, failed verification, review gates, and stale handoffs. * `ExecutorCapability`: family, kind, provider/runtime, installed/probed state, missing dependency, repair command, last probe, executor readiness. * `HeroLifecycleCommand`: spawn, fork, handoff, resume, message, stop, dismiss, model change, permission mode change, isolation mode. * `ExecutionRun`: action id, executor family/kind, command/input preview, startedAt, completedAt, status, output summary, artifact ids, failure code. * `PermissionRequest`: requester, hook event, tool name, input preview, timeoutAt, response path/id, decision, reason, result. * `FileIntent`: owner hero/subagent, operation, path label, queue/task, acquiredAt, expiresAt, conflict state, resolution. * `WorkpadRecord`, `EvidenceArtifact`, `VerificationAttempt`, `ReviewGate`, `HandoffRecord`, `RuntimeDiagnostic`, `ChannelCommand`, and `UsageMetric`. WebSocket event families to add or deepen: * `plan_campaign_update`, `plan_task_update`, `attention_update`, `executor_capability_update`, `hero_lifecycle_update`, `execution_run_update`, `permission_request_update`, `file_intent_update`, `workpad_update`, `evidence_update`, `verification_update`, `handoff_update`, `diagnostic_update`, `channel_command_update`, `usage_metric_update`. #### Track B: Server Managers And Routes Add managers under `apps/server/src/managers/` and bind routes under `api`: | Manager | Routes | EXAMPLES evidence | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `planCampaignManager` | `POST /plans`, `GET /plans`, `GET /plans/:id`, `POST /plans/:id/approve`, `POST /plans/:id/pause`, `POST /plans/:id/resume`, `POST /plans/:id/cancel`, `POST /plans/:id/retry-failed`, `POST /plans/:id/refine` | [`api-routes.txt`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L159-L189), [`plan-decomposer.md`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/llm-prompts/plan-decomposer.md#L23-L73) | | `attentionManager` | `GET /attention`, `POST /attention/:id/decision` | [`permission routes`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L118-L122), [`permission-request.sh`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-permission-request.sh#L1-L154) | | `executorRegistry` | `GET /executors/capabilities`, `POST /executions`, `GET /executions/:id`, `POST /executions/:id/kill` | [`architecture executors`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/architecture.md#L140-L195), [`guarded route inventory`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L42-L115) | | `heroLifecycleManager` | `POST /internal-heroes/spawn`, `POST /internal-heroes/:id/fork`, `POST /internal-heroes/:id/handoff`, `POST /internal-heroes/:id/resume`, `POST /internal-heroes/:id/stop`, `PATCH /internal-heroes/:id/model`, `PATCH /internal-heroes/:id/permission-mode` | [`api-routes.txt`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L84-L107), [`factionos-guide`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md#L38-L60) | | `permissionRequestManager` | `POST /permission-request`, `POST /permission-response`, `POST /plan-approval-request`, `POST /plan-approval-response` | [`permission hook`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-permission-request.sh#L46-L154), [`claude hook contract`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/claude-hook-contract.md#L61-L99) | | `fileIntentManager` | `GET /file-intents`, `POST /file-conflict-check`, `POST /file-intents/:id/resolve` | [`file-access.sh`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-file-access.sh#L76-L116), [`file conflict routes`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L55-L81) | | `workpadEvidenceManager` | `GET/POST /task-queue/:id/workpad`, `GET/POST /task-queue/:id/evidence`, `POST /task-queue/:id/verify`, `POST /task-queue/:id/review` | [`api-routes.txt`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L29-L30), [`api-routes.txt`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L179-L198) | | `gitWorkbenchManager` | `GET /git/changes`, `POST /git/stage`, `POST /git/unstage`, `POST /git/commit`, `POST /git/push`, `POST /git/stash`, `POST /git/revert`, `POST /git/switch-branch` | [`api-routes.txt`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L42-L54), [`git-guard.sh`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-git-guard.sh#L1-L98) | | `terminalSessionManager` | `GET /terminal/sessions`, `POST /terminal/sessions`, `POST /terminal/sessions/:id/input`, `POST /terminal/sessions/:id/kill` | [`terminal guide`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md#L125-L136), [`terminal events`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/websocket-events.txt#L148-L149) | | `containerRuntimeManager` | `GET /containers/capabilities`, `POST /containers/build-image`, `POST /containers/run`, `POST /containers/:id/cleanup` | [`Dockerfile.isolated`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/Dockerfile.isolated#L1-L70), [`isolated heroes`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md#L49-L60) | | `handoffManager` | `GET /handoffs`, `POST /handoffs`, `POST /handoffs/:id/validate`, `POST /handoffs/:id/resume` | [`handoff skill`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-handoff/SKILL.md#L14-L174), [`resume checklist`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-handoff/references/resume-checklist.md#L1-L83) | | `diagnosticsManager` | `GET /diagnostics/orchestration`, `POST /diagnostics/orchestration/recover` | [`troubleshooting`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/references/troubleshooting.md#L23-L260), [`spawn-listeners.sh`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/spawn-listeners.sh#L1-L46) | | `channelCommandManager` | `GET /channels`, `POST /channels/:id/pair`, `GET /channel-commands`, `POST /webhooks/github`, `POST /webhooks/generic` | [`channel routes`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L35-L39), [`webhook routes`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L208-L209) | | `usageMetricsManager` | `GET /usage`, `GET /hero-metrics`, `GET /token-stats`, `GET /plans/:id/metrics` | [`usage routes`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L21-L31), [`Gold Mine`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md#L233-L237) | #### Track C: Web Restructure Split `OrchestrationPanel.tsx` into owned components once the contracts exist: * `OrchestrationPanel`: shell, counts, hydration, keyboard shortcuts, modal. * `OrchestrationHeader`: connection, scope, attention, capability summary. * `AttentionQueue`: merged approvals/permissions/blocked/review/channel queue. * `CampaignWorkbench`: plan list, task graph, dispatch controls, retry/pause. * `QueueWorkbench`: existing task queue plus create/update/reject/restore forms. * `HeroLifecyclePanel`: spawn/fork/handoff/resume/message/stop/model controls. * `ExecutorFamiliesPanel`: file/git/terminal/subagent/mission/handoff/remote/ container capability and run history. * `TemplateWorkbench`: searchable spawnable templates and role details. * `LineageOperatorView`: mission graph plus subagent roster and controls. * `WorkpadEvidencePanel`: workpad, evidence, verification, review gates. * `DiagnosticsRecoveryPanel`: hook/listener/spool/provider/runtime recovery. * `FederationNoticePanel`: War Room posture and Notice Board links. * `MetricsPanel`: queue age, throughput, cost/tokens, failures, retries. Store/API work: * Extend `apps/web/src/lib/orchestrationApi.ts` for every new route above. * Add store slices in `useGameStore`: `orchestrationPlans`, `orchestrationAttention`, `orchestrationExecutors`, `orchestrationHeroLifecycle`, `orchestrationPermissions`, `orchestrationFileIntents`, `orchestrationWorkpad`, `orchestrationEvidence`, `orchestrationDiagnostics`, `orchestrationChannels`, `orchestrationMetrics`. * Add reducers for each WebSocket event family and refresh-on-mutation helpers. * Keep the compact panel usable, but move real operation into the detail modal with tabs and focused drawers. #### Track D: Hook And Listener Integration Use the historical hook map as the implementation checklist: * `SessionStart`: ensure current hooks send hero identity, cwd/project label, terminal id, listener status, provider, and session id. * `UserPromptSubmit`: create/attach mission, set hero active, seed mission progress, and link to queue/plan when applicable. * `Stop`: close mission progress and trigger suggestions/auto-improvement. * `PreToolUse[Task|Agent]`: create subagent lineage rows and optional guarded spawn records. * `PreToolUse[AskUserQuestion]` and `PostToolUse[AskUserQuestion]`: create and resolve attention items. * `PreToolUse[ExitPlanMode]` and `PermissionRequest`: use the blocking response-file round trip for internal heroes. * `PreToolUse[Bash]`: create terminal/git proposals, run git guard, attach command summary to mission/tool history. * `PreToolUse[Read|Write|Edit]`: update file access, file intents, conflict checks, and evidence/workpad links. * `SubagentStop`: mark subagent lineage completion with result state. Reference mapping: [`hooks-config.json`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-config.json#L1-L143), [`claude-hook-contract.md`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/claude-hook-contract.md#L21-L236), [`hooks-bundle/hooks.json`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/hooks.json#L1-L143). #### Track E: Execution Family Order Build in this order while keeping all tracks moving: 1. Queue/campaign mutations, attention queue, permission requests, and plan approval round trip. 2. Provider/model/hook/listener diagnostics and capability matrix. 3. File intents/conflict checks and git workbench execution. 4. Internal hero spawn/fork/handoff/resume/stop. 5. Workpad/evidence/verification/review gate flow. 6. Terminal PTY executor with scoped terminal drawer. 7. Container isolation and isolated hero spawn. 8. War Room posture, Notice Board integration, remote access summary. 9. Channel/webhook command intake, push/mobile attention, metrics/cost/usage. #### Track F: Tests And Done Criteria Each implementation slice should include: * protocol validators and fixture round trips for new DTOs/events; * manager unit tests for idempotency, stale revision, duplicate mutation, timeout, and result persistence; * REST route tests for validation, conflict responses, and event emission; * Web store reducer tests for every WebSocket event family; * component tests for attention actions, queue mutations, template spawn, and executor-family result rendering; * Playwright coverage for the Orchestration detail modal once mutating controls land; * docs updates in `docs/api/`, `apps/server/README_server.md`, `apps/web/README_web.md`, and `packages/protocol/README_protocol.md` to replace current "unavailable" claims as each executor family ships. ### Reference Index Every EXAMPLES detail used above is linked here for traceability: * Intake and provenance: [`README_examples.md`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/README_examples.md#L1-L134), [`REPORT.md`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/REPORT.md#L1-L49), [`1st-pass-artifacts README`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/README_1st-pass-artifacts.md#L1-L137), [`findings README`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/README_findings.md#L1-L15), [`extraction coverage`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/extraction-coverage.md#L1-L43), [`findings SUMMARY`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/SUMMARY.md#L1-L60), [`BUILD_LINKS`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/BUILD_LINKS.md#L1-L148), [`directory tree`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/directory-tree.txt#L1-L48), [`tarball manifest`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/tarball-manifest.txt#L1-L603). * Architecture, routes, events, services, stack: [`architecture.md`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/architecture.md#L1-L283), [`architecture.mmd`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/architecture.mmd#L1-L59), [`tech-stack.md`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/tech-stack.md#L1-L215), [`asset-inventory.md`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/asset-inventory.md#L1-L108), [`api-routes.txt`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L1-L210), [`websocket-events.txt`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/websocket-events.txt#L1-L172), [`external-services.md`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/external-services.md#L1-L167), [`external-urls.txt`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/external-urls.txt#L1-L14), [`posthog-and-supabase.md`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/posthog-and-supabase.md#L1-L58), [`claude-hook-contract.md`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/claude-hook-contract.md#L1-L236), [`claude-models-used.txt`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/claude-models-used.txt#L1-L15). * Package and plugin: [`package.json`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/package-0.4.1/package.json#L1-L103), [`package bin`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/package-0.4.1/bin/agentcraft.js#L1-L2), [`package cli`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/package-0.4.1/lib/cli.js#L1-L12), [`package config`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/package-0.4.1/lib/config.js#L1-L1), [`package installer`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/package-0.4.1/lib/installer.js#L1-L1), [`package launcher`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/package-0.4.1/lib/launcher.js#L1-L1), [`package migrate-data`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/package-0.4.1/lib/migrate-data.js#L1-L1), [`plugin manifest`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/package-0.4.1/plugin/.claude-plugin/plugin.json#L1-L21), [`start-rts command`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/package-0.4.1/plugin/commands/start-rts.md#L1-L43), [`package hooks.json`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/package-0.4.1/plugin/hooks/hooks.json#L1-L143), [`package ws listener`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/package-0.4.1/plugin/ws-listener/listener.js#L1-L3), [`package ws listener package`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/package-0.4.1/plugin/ws-listener/package.json#L1-L12), [`hooks-config.json`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-config.json#L1-L143), [`plugin-manifest.json`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/plugin-manifest.json#L1-L22), [`build-env.json`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/build-env.json), [`bundled README`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/bundled-README.md#L1-L126), [`bundled package`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/bundled-package.json#L1-L103), [`server package`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/server-package.json#L1-L13), [`skills catalog`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills-catalog.json#L1-L142), [`frontend index`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/frontend-index.html#L1-L60), [`frontend manifest`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/frontend-manifest.json#L1-L55). * Hook mechanics: [`hooks-bundle hooks.json`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/hooks.json#L1-L143), [`hooks-bundle package`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/package.json#L1-L3), [`hook utils`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/lib/hook-utils.js#L1-L2), [`awaiting-input.js`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-awaiting-input.js#L1-L2), [`awaiting-input.sh`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-awaiting-input.sh#L1-L51), [`hero-spawn.sh`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-hero-spawn.sh#L1-L108), [`hero-spawn.js`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-hero-spawn.js#L1-L2), [`hero-active.sh`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-hero-active.sh#L1-L189), [`hero-active.js`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-hero-active.js#L1-L3), [`hero-idle.sh`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-hero-idle.sh#L1-L39), [`hero-idle.js`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-hero-idle.js#L1-L2), [`bash-command.sh`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-bash-command.sh#L1-L41), [`bash-command.js`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-bash-command.js#L1-L2), [`file-access.sh`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-file-access.sh#L1-L134), [`file-access.js`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-file-access.js#L1-L4), [`file-edit.js`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-file-edit.js#L1-L5), [`git-guard.sh`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-git-guard.sh#L1-L98), [`git-guard.js`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-git-guard.js#L1-L8), [`permission-request.sh`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-permission-request.sh#L1-L154), [`permission-request.js`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-permission-request.js#L1-L2), [`subagent-spawn.sh`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-subagent-spawn.sh#L1-L33), [`subagent-spawn.js`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-subagent-spawn.js#L1-L2), [`subagent-complete.sh`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-subagent-complete.sh#L1-L26), [`subagent-complete.js`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-subagent-complete.js#L1-L2), [`subagent-start.js`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-subagent-start.js#L1-L2), [`input-received.sh`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-input-received.sh#L1-L30), [`input-received.js`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-input-received.js#L1-L2), [`tool-failure.js`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-tool-failure.js#L1-L2), [`spawn-listeners.sh`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/spawn-listeners.sh#L1-L46), [`ws-listener.js`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/ws-listener.js#L1-L3). * User-facing guide and references: [`factionos-guide`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md#L1-L466), [`keyboard shortcuts`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/references/keyboard-shortcuts.md#L1-L90), [`troubleshooting`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/references/troubleshooting.md#L1-L260), [`openclaw event cookbook`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/openclaw-SKILL.md#L1-L183). * Templates, setup, handoff, notice board, isolation: [`agent-templates.json`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/agent-templates.json#L1-L127), [`app-setup`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/app-setup/SKILL.md#L1-L15), [`handoff skill`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-handoff/SKILL.md#L1-L207), [`handoff template`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-handoff/references/handoff-template.md#L1-L142), [`resume checklist`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-handoff/references/resume-checklist.md#L1-L83), [`handoff staleness script`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-handoff/scripts/check_staleness.py#L1-L352), [`handoff create script`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-handoff/scripts/create_handoff.py#L1-L385), [`handoff list script`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-handoff/scripts/list_handoffs.py#L1-L125), [`handoff validate script`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-handoff/scripts/validate_handoff.py#L1-L285), [`notice-board skill`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/notice-board/SKILL.md#L1-L53), [`notice list script`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/notice-board/scripts/list_notices.sh#L1-L50), [`notice post script`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/notice-board/scripts/post_notice.sh#L1-L41), [`Dockerfile.isolated`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/Dockerfile.isolated#L1-L70). * LLM prompt surfaces: [`llm-prompts README`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/llm-prompts/README_llm-prompts.md#L1-L54), [`plan-decomposer`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/llm-prompts/plan-decomposer.md#L1-L76), [`idle-suggestion-engine`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/llm-prompts/idle-suggestion-engine.md#L1-L88), [`on-demand-analysis`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/llm-prompts/on-demand-analysis.md#L1-L90), [`auto-improver`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/llm-prompts/auto-improver.md#L1-L99), [`transcript-miner`](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/llm-prompts/transcript-miner.md#L1-L87). ### Bottom Line The first pass correctly mapped the historical system. The second pass is the build mandate: make Orchestration the operator command center and wire it all the way down. The current panel's queue/templates/lineage/guarded-action slice should expand into campaigns, attention, internal hero lifecycle, executor families, file intents, workpad/evidence/verification, handoff/resume, diagnostics/recovery, War Room/Notice Board context, channels/webhooks, and metrics. The shortest path is not another read-only pass. Start with protocol/event contracts, server managers/routes, and store slices, then split the current panel into focused tabs and begin turning approvals into actual executor runs family by family. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/phases/phase_19/prd_phase_19.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.