# giulio-leone/harness-os architecture

> Architecture diagram of the GitHub repository giulio-leone/harness-os, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/giulio-leone/harness-os
- Repository: https://github.com/giulio-leone/harness-os

## Overview

HarnessOS is an agent execution layer for persistent task lifecycle, recovery, policy-aware dispatch, and multi-agent orchestration; it leaves model inference to the host. A typical workflow enters through the MCP interface, reaches orchestration dispatch and session execution, and persists leases, checkpoints, and task state. The repository also includes a dashboard and a Rust harness workspace. Some major runtime modules are indexed but unsampled, so their capabilities are represented without speculative call edges; optional memory is shown separately.

Main entry points: [`src/runtime/session-orchestrator.ts`](https://github.com/giulio-leone/harness-os/blob/main/src/runtime/session-orchestrator.ts) (Session orchestration), [`src/runtime/orchestration-supervisor.ts`](https://github.com/giulio-leone/harness-os/blob/main/src/runtime/orchestration-supervisor.ts) (Supervisor tick), [`src/runtime/orchestration-assignment-runner.ts`](https://github.com/giulio-leone/harness-os/blob/main/src/runtime/orchestration-assignment-runner.ts) (Assignment runner), [`apps/dashboard/components/dashboard-shell.tsx`](https://github.com/giulio-leone/harness-os/blob/main/apps/dashboard/components/dashboard-shell.tsx) (Dashboard UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Host Interfaces"]
  node_mcp["MCP tools"]
  node_mcp_stdio["MCP stdio<br/>[jsonrpc-stdio.ts]"]
  node_cli["Lifecycle CLI"]
end

subgraph group_orchestration["Orchestration"]
  node_supervisor["Supervisor tick"]
  node_planner["Issue planner"]
  node_dispatcher["Issue dispatcher"]
  node_assignment["Assignment runner"]
  node_symphony["Symphony workflow"]
  node_worktree["Worktree management"]
  node_policy["Policy evaluation<br/>[policy-engine.ts]"]
  node_orch_contracts["Orchestration contracts"]
  node_inspector["Queue inspector"]
end

subgraph group_runtime["Session Runtime"]
  node_session_adapter["Lifecycle adapter"]
  node_session["Session orchestration"]
  node_memory["Semantic memory"]
  node_memory_loader["Memory loader"]
end

subgraph group_state["Canonical State"]
  node_store[("SQLite store<br/>[store.ts]")]
  node_leases["Lease and queue state<br/>[lease-manager.ts]"]
  node_checkpoints["Checkpoint writer"]
end

subgraph group_dashboard["Dashboard"]
  node_dashboard_runtime["Dashboard queries"]
  node_dashboard_page["Dashboard pages<br/>[page.tsx]"]
  node_dashboard_shell["Dashboard UI"]
  node_issue_page["Issue detail page<br/>[page.tsx]"]
end

node_agent(("Agent host"))

node_agent -->|"calls tools"| node_mcp
node_mcp -->|"runs tick"| node_supervisor
node_supervisor -->|"dispatches work"| node_dispatcher
node_supervisor -->|"runs assignments"| node_assignment
node_supervisor -->|"inspects queue"| node_inspector
node_dispatcher -->|"validates worktree"| node_worktree
node_assignment -->|"starts session"| node_session
node_assignment -->|"uses workflow"| node_symphony
node_assignment -->|"uses adapter"| node_worktree
node_session_adapter -->|"delegates to"| node_session
node_session -->|"claims and releases"| node_leases
node_session -->|"writes checkpoints"| node_checkpoints
node_session -->|"runs statements"| node_store
node_leases -->|"runs statements"| node_store
node_policy -->|"uses policy types"| node_orch_contracts
node_session -.->|"bridges memory"| node_memory
node_memory_loader -.->|"loads optionally"| node_memory
node_dashboard_page -->|"renders"| node_dashboard_shell
node_issue_page -->|"renders detail UI"| node_dashboard_shell
node_dashboard_shell -.->|"loads dashboard data"| node_dashboard_runtime
node_dashboard_runtime -->|"uses queue inspection"| node_inspector

click node_mcp "https://github.com/giulio-leone/harness-os/blob/main/src/mcp/session-lifecycle-mcp-server.ts"
click node_mcp_stdio "https://github.com/giulio-leone/harness-os/blob/main/src/mcp/jsonrpc-stdio.ts"
click node_cli "https://github.com/giulio-leone/harness-os/blob/main/src/bin/session-lifecycle.ts"
click node_supervisor "https://github.com/giulio-leone/harness-os/blob/main/src/runtime/orchestration-supervisor.ts"
click node_planner "https://github.com/giulio-leone/harness-os/blob/main/src/runtime/orchestration-planner.ts"
click node_dispatcher "https://github.com/giulio-leone/harness-os/blob/main/src/runtime/orchestration-dispatcher.ts"
click node_assignment "https://github.com/giulio-leone/harness-os/blob/main/src/runtime/orchestration-assignment-runner.ts"
click node_symphony "https://github.com/giulio-leone/harness-os/blob/main/src/runtime/symphony-workflow.ts"
click node_worktree "https://github.com/giulio-leone/harness-os/blob/main/src/runtime/worktree-manager.ts"
click node_policy "https://github.com/giulio-leone/harness-os/blob/main/src/runtime/policy-engine.ts"
click node_orch_contracts "https://github.com/giulio-leone/harness-os/blob/main/src/contracts/orchestration-contracts.ts"
click node_session_adapter "https://github.com/giulio-leone/harness-os/blob/main/src/runtime/session-lifecycle-adapter.ts"
click node_session "https://github.com/giulio-leone/harness-os/blob/main/src/runtime/session-orchestrator.ts"
click node_memory "https://github.com/giulio-leone/harness-os/blob/main/src/runtime/mem0-session-bridge.ts"
click node_memory_loader "https://github.com/giulio-leone/harness-os/blob/main/src/runtime/default-mem0-loader.ts"
click node_store "https://github.com/giulio-leone/harness-os/blob/main/src/db/store.ts"
click node_leases "https://github.com/giulio-leone/harness-os/blob/main/src/db/lease-manager.ts"
click node_checkpoints "https://github.com/giulio-leone/harness-os/blob/main/src/db/checkpoint-writer.ts"
click node_dashboard_runtime "https://github.com/giulio-leone/harness-os/blob/main/src/runtime/orchestration-dashboard.ts"
click node_inspector "https://github.com/giulio-leone/harness-os/blob/main/src/runtime/orchestration-inspector.ts"
click node_dashboard_page "https://github.com/giulio-leone/harness-os/blob/main/apps/dashboard/app/page.tsx"
click node_dashboard_shell "https://github.com/giulio-leone/harness-os/blob/main/apps/dashboard/components/dashboard-shell.tsx"
click node_issue_page "https://github.com/giulio-leone/harness-os/blob/main/apps/dashboard/app/issues/%5BissueId%5D/page.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mcp,node_mcp_stdio,node_cli toneBlue
class node_supervisor,node_planner,node_dispatcher,node_assignment,node_symphony,node_worktree,node_policy,node_orch_contracts,node_inspector toneAmber
class node_session_adapter,node_session,node_memory,node_memory_loader toneMint
class node_store,node_leases,node_checkpoints toneRose
class node_dashboard_runtime,node_dashboard_page,node_dashboard_shell,node_issue_page,node_agent toneIndigo
```

## Components

### Host Interfaces

- [MCP tools](https://github.com/giulio-leone/harness-os/blob/main/src/mcp/session-lifecycle-mcp-server.ts): `src/mcp/session-lifecycle-mcp-server.ts`
- [MCP stdio](https://github.com/giulio-leone/harness-os/blob/main/src/mcp/jsonrpc-stdio.ts): `src/mcp/jsonrpc-stdio.ts`
- [Lifecycle CLI](https://github.com/giulio-leone/harness-os/blob/main/src/bin/session-lifecycle.ts): `src/bin/session-lifecycle.ts`

### Orchestration

- [Supervisor tick](https://github.com/giulio-leone/harness-os/blob/main/src/runtime/orchestration-supervisor.ts): `src/runtime/orchestration-supervisor.ts`
- [Issue planner](https://github.com/giulio-leone/harness-os/blob/main/src/runtime/orchestration-planner.ts): `src/runtime/orchestration-planner.ts`
- [Issue dispatcher](https://github.com/giulio-leone/harness-os/blob/main/src/runtime/orchestration-dispatcher.ts): `src/runtime/orchestration-dispatcher.ts`
- [Assignment runner](https://github.com/giulio-leone/harness-os/blob/main/src/runtime/orchestration-assignment-runner.ts): `src/runtime/orchestration-assignment-runner.ts`
- [Symphony workflow](https://github.com/giulio-leone/harness-os/blob/main/src/runtime/symphony-workflow.ts): `src/runtime/symphony-workflow.ts`
- [Worktree management](https://github.com/giulio-leone/harness-os/blob/main/src/runtime/worktree-manager.ts): `src/runtime/worktree-manager.ts`
- [Policy evaluation](https://github.com/giulio-leone/harness-os/blob/main/src/runtime/policy-engine.ts): `src/runtime/policy-engine.ts`
- [Orchestration contracts](https://github.com/giulio-leone/harness-os/blob/main/src/contracts/orchestration-contracts.ts): `src/contracts/orchestration-contracts.ts`
- [Queue inspector](https://github.com/giulio-leone/harness-os/blob/main/src/runtime/orchestration-inspector.ts): `src/runtime/orchestration-inspector.ts`

### Session Runtime

- [Lifecycle adapter](https://github.com/giulio-leone/harness-os/blob/main/src/runtime/session-lifecycle-adapter.ts): `src/runtime/session-lifecycle-adapter.ts`
- [Session orchestration](https://github.com/giulio-leone/harness-os/blob/main/src/runtime/session-orchestrator.ts): `src/runtime/session-orchestrator.ts`
- [Semantic memory](https://github.com/giulio-leone/harness-os/blob/main/src/runtime/mem0-session-bridge.ts): `src/runtime/mem0-session-bridge.ts`
- [Memory loader](https://github.com/giulio-leone/harness-os/blob/main/src/runtime/default-mem0-loader.ts): `src/runtime/default-mem0-loader.ts`

### Canonical State

- [SQLite store](https://github.com/giulio-leone/harness-os/blob/main/src/db/store.ts): `src/db/store.ts`
- [Lease and queue state](https://github.com/giulio-leone/harness-os/blob/main/src/db/lease-manager.ts): `src/db/lease-manager.ts`
- [Checkpoint writer](https://github.com/giulio-leone/harness-os/blob/main/src/db/checkpoint-writer.ts): `src/db/checkpoint-writer.ts`

### Dashboard

- [Dashboard queries](https://github.com/giulio-leone/harness-os/blob/main/src/runtime/orchestration-dashboard.ts): `src/runtime/orchestration-dashboard.ts`
- [Dashboard pages](https://github.com/giulio-leone/harness-os/blob/main/apps/dashboard/app/page.tsx): `apps/dashboard/app/page.tsx`
- [Dashboard UI](https://github.com/giulio-leone/harness-os/blob/main/apps/dashboard/components/dashboard-shell.tsx): `apps/dashboard/components/dashboard-shell.tsx`
- [Issue detail page](https://github.com/giulio-leone/harness-os/blob/main/apps/dashboard/app/issues/%5BissueId%5D/page.tsx): `apps/dashboard/app/issues/[issueId]/page.tsx`

### Other components

- **Agent host**

## Connections

- Agent host → MCP tools: calls tools
- MCP tools → Supervisor tick: runs tick (evidence: `src/mcp/session-lifecycle-mcp-server.ts`)
- Supervisor tick → Issue dispatcher: dispatches work (evidence: `src/runtime/orchestration-supervisor.ts`)
- Supervisor tick → Assignment runner: runs assignments (evidence: `src/runtime/orchestration-supervisor.ts`)
- Supervisor tick → Queue inspector: inspects queue (evidence: `src/runtime/orchestration-supervisor.ts`)
- Issue dispatcher → Worktree management: validates worktree (evidence: `src/runtime/orchestration-dispatcher.ts`)
- Assignment runner → Session orchestration: starts session (evidence: `src/runtime/orchestration-assignment-runner.ts`)
- Assignment runner → Symphony workflow: uses workflow (evidence: `src/runtime/orchestration-assignment-runner.ts`)
- Assignment runner → Worktree management: uses adapter (evidence: `src/runtime/orchestration-assignment-runner.ts`)
- Lifecycle adapter → Session orchestration: delegates to (evidence: `src/runtime/session-lifecycle-adapter.ts`)
- Session orchestration → Lease and queue state: claims and releases (evidence: `src/runtime/session-orchestrator.ts`)
- Session orchestration → Checkpoint writer: writes checkpoints (evidence: `src/runtime/session-orchestrator.ts`)
- Session orchestration → SQLite store: runs statements (evidence: `src/runtime/session-orchestrator.ts`)
- Lease and queue state → SQLite store: runs statements (evidence: `src/db/lease-manager.ts`)
- Policy evaluation → Orchestration contracts: uses policy types (evidence: `src/runtime/policy-engine.ts`)
- Session orchestration → Semantic memory: bridges memory (evidence: `src/runtime/session-orchestrator.ts`)
- Memory loader → Semantic memory: loads optionally
- Dashboard pages → Dashboard UI: renders (evidence: `apps/dashboard/app/page.tsx`)
- Issue detail page → Dashboard UI: renders detail UI (evidence: `apps/dashboard/app/issues/[issueId]/page.tsx`)
- Dashboard UI → Dashboard queries: loads dashboard data
- Dashboard queries → Queue inspector: uses queue inspection (evidence: `src/runtime/orchestration-dashboard.ts`)