---
title: Ops Engine (PM Operations Engine)
---

# Ops Engine (PM Operations Engine)

## What it is

**In-development** operational dashboard for the AI Project Manager.

The **Ops Engine** is a built-in virtual project (`__pm_ops_engine__`) that surfaces
operational metrics and execution health for the AI Project Manager. It docks in the
main panel beside the projects sidebar, like the other PM tools (What Changed, PM
Advisor).

## Where to find it

In-development, gated via the unreleased-feature registry (`pm-operations-engine`
in `UNRELEASED_FEATURES`, setting key `pmOpsEngineEnabled`). Enable it in
**Settings -> Lab** toggle or set `AMC_SHOW_PM_OPERATIONS_ENGINE=1`. Once enabled
it appears as a sidebar entry under the `ai-tools` parent group.

## How it behaves

The `OpsEngineDashboard` panel renders nine component sections over data
fetched via `PM_OPS_GET_DASHBOARD`, `PM_OPS_GET_SHIFT_HANDOFF`, and
`PM_OPS_GET_ACTION_LOG` IPC channels:

- **Workspace Health** (`WorkspaceHealthWidget`) — aggregate health metrics
- **Active Agent Sessions** (`ActiveAgentSessionsWidget`) — agent session status
- **Deadline Confidence** (`DeadlineConfidenceWidget`) — prediction confidence
- **Risk Heatmap** (`RiskHeatmapWidget`) — risk visualization across boards
- **Predictive Deadline** (`PredictiveDeadlineWidget`) — deadline forecasts
- **Velocity Trend** (`VelocityTrendWidget`) — velocity over time
- **Shift Handoffs** (`ShiftHandoffCard`) — unread handoff summaries
- **Decision Queue** (`DecisionQueueItem`) — pending proposed actions
- **Notification Preferences** (`PmNotificationPrefsPanel`) — per-board prefs

An empty state is shown until boards are connected and workspace data populates.

## For agents

### Architecture

- **Non-spawnable**: the panel renders its own dashboard UI and hosts no Claude
  sessions.
- Built-in integration (`amc-builtin`, plugin tier).
- Virtual project path: `__pm_ops_engine__`.
- Panel component: `OpsEngineDashboard` (`src/renderer/src/features/pm-ops/`).

### Backend service (`src/main/services/pm/ops/`)

22 files (12 top-level + 10 action handlers in `actions/`):

| File                    | Responsibility                                                                                 |
| ----------------------- | ---------------------------------------------------------------------------------------------- |
| `ops-engine-service.ts` | Lifecycle (start/stop), boot reconcile, orphan sweep                                           |
| `session-shepherd.ts`   | Monitors agent sessions linked to PM work                                                      |
| `work-queue-manager.ts` | Manages the PM work queue execution                                                            |
| `policy-queries.ts`     | Policy CRUD, orphan sweep (`sweepStaleExecuting` + `sweepStaleApproved`), action log retention |
| `policy-engine.ts`      | Policy evaluation and enforcement                                                              |
| `dashboard-data.ts`     | Dashboard data aggregation for IPC                                                             |
| `decision-queue.ts`     | Proposed-action queue and approval flow                                                        |
| `shift-handoff.ts`      | Shift handoff generation and management                                                        |
| `action-dispatcher.ts`  | Routes action execution to handlers                                                            |
| `action-registry.ts`    | Registers available ops action types                                                           |
| `ops-trust-bridge.ts`   | Trust-level gating for ops actions                                                             |
| `ops-row-coerce.ts`     | Row-shape coercion for ops data                                                                |

**`actions/` subdirectory** (10 handlers):
`adjust-timeline`, `create-item`, `move-item`, `notify`,
`pause-kill-session`, `reassign`, `restart-stalled-session`,
`spawn-next-session`, `trigger-automation`, `update-status`.

The engine is gated on `isUnreleasedFeatureVisible('pm-operations-engine')` AND
`runtime.foreignDbOwner === false` (single-instance DB ownership). On startup it
sweeps orphaned executing actions, stale approved actions, expires stale proposals
(all three periodically), and cleans action log entries older than 90 days.

### IPC channels (12 total, `src/shared/ipc-channels/pm-ops.ts`)

8 invoke channels (get-policies, set-policy, get-action-log, approve-action,
deny-action, get-dashboard, get-shift-handoff, mark-handoff-read) and 4 push
channels (policy-changed, action-logged, dashboard-updated, handoff-ready).

### CLI routes

`src/main/services/cli/cli-server-pm-ops-routes.ts` — exposed under `/pm/ops/`.

## Related

The Ops Engine docks alongside the other Mission Control tools, so
[mission-control.md](mission-control.md) is the parent page and
[pm-intelligence-advisor.md](pm-intelligence-advisor.md) is its nearest sibling panel — that
one turns the same board data into advice, where this one reports execution health.
Several widgets here are backed by the forecasting layer in
[pm-predictive-analytics.md](pm-predictive-analytics.md), and the per-board notification
preferences it renders are documented in
[pm-notification-preferences.md](pm-notification-preferences.md). The full list of library
pages is in [INDEX.md](INDEX.md).