# Task Execution Principles and Dashboard Rendering

> **What you will learn in this chapter**
> How tasks run inside dedicated git worktrees, why frequent commits are essential for survival, and how to effectively visualize results in the web dashboard.
>
> **If you are delegating for the first time**, complete [Your First Task](/guide/ht-first-task) first.

---

## 1. Where Tasks Run: Dedicated Git Worktrees

When a task begins, the agent does not touch your base working directory directly. Instead, it works inside an **isolated git worktree on a dedicated branch**.

```mermaid
sequenceDiagram
    autonumber
    participant HT as HyperTeams Engine
    participant WT as Isolated Worktree
    participant Base as Base Branch

    HT->>WT: 1. Create task worktree & checkout branch
    Note over WT: Agent executes work & commits frequently
    HT->>Base: 2. Auto-merge branch upon task completion
    HT->>WT: 3. Delete worktree folder & prune
    Note over WT: ⚠️ Uncommitted changes are permanently lost!
    HT->>WT: 4. Next turn begins with a fresh worktree
```

### Core Rule: Why Frequent Commits Matter

When the task turn finishes or is merged, HyperTeams cleans up and deletes the folder. **Only committed changes survive.**

```mermaid
flowchart TD
    Start["Task Finished & Turn Ended"] --> Check{"File State Check"}
    Check -->|"Git Commit Complete"| Saved["✅ Safely Preserved (Survives)<br/>Auto-merged into Base branch"]
    Check -->|"Uncommitted Changes"| Deleted["❌ Permanently Deleted<br/>Lost upon folder pruning"]
    Check -->|"Git-ignored Files (node_modules, .env.local, etc.)"| Deleted
```

| Category | Do Not (Don't) | Must Do (Do) |
|---|---|---|
| **Workspace** | Switch branches, create arbitrary worktrees, push directly to base | Work strictly inside the provided worktree folder |
| **Commits** | Conclude the turn without committing | **Commit frequently after each unit of work** |

---

## 2. Background Processes and Concurrency Slots

If an agent leaves a dev server or watching command (`tail -f`, file watcher) running past its turn, that process holds **one of the machine's concurrency slots**.

```mermaid
flowchart TD
    subgraph MachineSlots ["Machine Concurrency Slots"]
        Slot1["Slot 1: Task A (Running normally)"]
        Slot2["Slot 2: Zombie process from finished task ⚠️"]
        Slot3["Slot 3: Task C (Blocked waiting for slot)"]
    end

    Slot2 --> Block["🚨 Silent Block: Subsequent tasks cannot start<br/>Stalls indefinitely without error message!"]
```

> **The Rule**: Always terminate (`kill`) long-running background processes before finishing your turn.
> 
> **Need a persistent server?** Do not launch it inside a task; start it in a persistent [Terminal](/guide/ht-terminal).

---

## 3. Rendering Results in the Dashboard

The agent's reply is displayed in Markdown on the web dashboard. Use rich elements where appropriate.

```mermaid
flowchart LR
    Output["Reply Output"] --> Type{"Presentation Type"}
    Type -->|"Created File/Screenshot"| Embed["File Embed<br/>! [desc] (&lt;absolute path&gt;)"]
    Type -->|"Structure/Wireframe"| Mermaid["Diagram<br/>```mermaid"]
    Type -->|"Citation/Source"| Footnote["Footnote<br/>[^1]: path#Lline"]
    Type -->|"Metrics/Data"| Chart["Chart<br/>```chart"]
```

### 3.1 File & Media Embeds (`![desc](<path>)`)

Embed newly created or modified files directly in the dashboard.
- **Syntax**: Always use `![description](<absolute path>)` (angle brackets `< >` are mandatory for paths with spaces).
- **Supported Formats**: Images (`.png`, `.jpg`), videos (`.mp4`, `.webm`), and audio (`.mp3`, `.wav`) play inline directly.

```mermaid
flowchart TD
    FilePath["File Storage Location"] --> CheckZone{"Path Location"}
    CheckZone -->|"/tmp Directory"| TempOk["✅ Allowed (Recommended 🌟)<br/>Visual artifacts, screenshots, charts"]
    CheckZone -->|"Inside Worktree"| WorktreeOk["✅ Allowed<br/>⚠️ Broken link after worktree is deleted"]
    CheckZone -->|"Home / Desktop"| Rejected["❌ Rejected (Permission Error)"]
```

> 💡 **Keep disposable visual artifacts in `/tmp`**: Because the worktree folder is deleted upon merge, screenshots kept inside the worktree will eventually break.

### 3.2 Diagrams and UI Wireframes (`mermaid`)

- **Top-down direction (`graph TD`)**: Dashboard panes scroll vertically, so prefer `graph TD` over `LR`.
- **UI Wireframes (`block-beta`)**: Declare `block-beta` on the first line inside the `mermaid` block.

```mermaid
block-beta
columns 3
header["Header (GNB)"]:3
sidebar["Sidebar (LNB)"] main["Main Content Area"]:2
footer["Footer (Status)"]:3
```

---

## Summary

1. Tasks run in **isolated Git Worktrees**; changes **must be committed** to survive after merging.
2. Background shells must be **killed before turn end**; run persistent servers in [Terminals](/guide/ht-terminal).
3. Save visual outputs to **`/tmp`** for clean dashboard embeds.