@thatix.io/context-first-agents-cli 0.2.1 → 0.3.0

package/README.md

@@ -150,6 +150,7 @@ commands `/observe` and `/metrics` are also included.
 | `update:commands` | Overwrite the command templates |
 | `doctor` | Validate manifest, hints, indexes, and installed flow commands |
 | `status` | Show repos, risk signals, and active sessions |
+| `dashboard` | Serve a local web dashboard of sessions and running agents |
 
 `--lang en|es|pt-BR` selects the language of the installed `.md` commands.
 
@@ -157,6 +158,20 @@ commands `/observe` and `/metrics` are also included.
 `products/{collect,refine,spec,check}`, **`orchestrate`** (+ `agents/`),
 `engineer/{start,plan,work,pre-pr,pr}` (escape hatches), `quality/{observe,metrics}`.
 
+## Dashboard
+
+`/orchestrate` writes machine-readable state per session (`state.json` +
+`workers/<id>.json`, format in `SESSION-STATE.md`). Serve a live view of it:
+
+```bash
+context-agents dashboard          # → http://localhost:4517
+```
+
+The dashboard lists every session (issue), its complexity, the agent graph by wave, and
+each agent's status (`pending → running → done/blocked`) with its current step and
+verdict — auto-refreshing every 2s. Sessions created before state-writing still render via
+an `execution-plan.md` fallback (shown without live status).
+
 ## The `.md` orchestration layer (the engine)
 
 Installed into `.claude/commands/`:

package/dist/commands/dashboard.d.ts

@@ -0,0 +1,5 @@
+interface DashboardOpts {
+    port?: string;
+}
+export declare function dashboardCommand(opts: DashboardOpts): Promise<void>;
+export {};

package/dist/commands/dashboard.js

@@ -0,0 +1,55 @@
+import http from 'node:http';
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import chalk from 'chalk';
+import { loadManifest, pathExists } from '../utils/config.js';
+import { listSessions, readSession } from '../core/sessions.js';
+import { templatesDir } from '../utils/paths.js';
+export async function dashboardCommand(opts) {
+    const cwd = process.cwd();
+    const port = Number(opts.port ?? 4517);
+    if (!(await pathExists(path.join(cwd, 'context-manifest.json')))) {
+        console.log(chalk.yellow('\nNo context-manifest.json here — run inside an orchestrator.\n'));
+        process.exitCode = 1;
+        return;
+    }
+    const htmlPath = path.join(templatesDir(), 'dashboard', 'index.html');
+    const html = (await pathExists(htmlPath)) ? await fs.readFile(htmlPath, 'utf-8') : '<h1>dashboard asset missing</h1>';
+    const server = http.createServer(async (req, res) => {
+        try {
+            const url = new URL(req.url ?? '/', `http://localhost:${port}`);
+            if (url.pathname === '/' || url.pathname === '/index.html') {
+                res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+                res.end(html);
+                return;
+            }
+            if (url.pathname === '/api/sessions') {
+                const manifest = await loadManifest(cwd);
+                const ids = await listSessions(cwd);
+                const sessions = await Promise.all(ids.map((id) => readSession(cwd, id)));
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ project: manifest?.project ?? 'orchestrator', sessions }));
+                return;
+            }
+            if (url.pathname === '/api/session') {
+                const id = url.searchParams.get('id') ?? '';
+                const session = await readSession(cwd, id);
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify(session));
+                return;
+            }
+            res.writeHead(404, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'not found' }));
+        }
+        catch (err) {
+            res.writeHead(500, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: String(err) }));
+        }
+    });
+    server.listen(port, () => {
+        console.log(chalk.bold('\nContext-First Agents — dashboard\n'));
+        console.log(chalk.green(`  ▶ http://localhost:${port}`));
+        console.log(chalk.gray(`  Reading sessions from ${path.join(cwd, '.sessions')}`));
+        console.log(chalk.gray('  Press Ctrl+C to stop.\n'));
+    });
+}

package/dist/core/sessions.d.ts

@@ -0,0 +1,29 @@
+export interface WorkerState {
+    id: string;
+    archetype?: string;
+    repository?: string | null;
+    objective?: string;
+    dependsOn?: string[];
+    status: 'pending' | 'running' | 'done' | 'blocked' | 'unknown';
+    currentStep?: string | null;
+    startedAt?: string | null;
+    finishedAt?: string | null;
+    verdict?: string | null;
+}
+export interface SessionState {
+    issueId: string;
+    title?: string;
+    complexity?: string;
+    status: 'planned' | 'running' | 'blocked' | 'done' | 'unknown';
+    createdAt?: string;
+    updatedAt?: string;
+    repos?: string[];
+    waves?: string[][];
+    workers: WorkerState[];
+    /** true when built from execution-plan.md fallback (no state.json yet). */
+    fromPlanFallback?: boolean;
+}
+/** List session directories (skips _backlog, dotfiles). */
+export declare function listSessions(orchestratorDir: string): Promise<string[]>;
+/** Read one session's full state, falling back to execution-plan.md parsing. */
+export declare function readSession(orchestratorDir: string, issueId: string): Promise<SessionState>;

package/dist/core/sessions.js

@@ -0,0 +1,105 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { pathExists } from '../utils/config.js';
+async function readJson(file) {
+    try {
+        return JSON.parse(await fs.readFile(file, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** List session directories (skips _backlog, dotfiles). */
+export async function listSessions(orchestratorDir) {
+    const dir = path.join(orchestratorDir, '.sessions');
+    if (!(await pathExists(dir)))
+        return [];
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    return entries
+        .filter((e) => e.isDirectory() && !e.name.startsWith('_') && !e.name.startsWith('.'))
+        .map((e) => e.name)
+        .sort();
+}
+/** Read one session's full state, falling back to execution-plan.md parsing. */
+export async function readSession(orchestratorDir, issueId) {
+    const sdir = path.join(orchestratorDir, '.sessions', issueId);
+    const state = await readJson(path.join(sdir, 'state.json'));
+    const workers = [];
+    const workersDir = path.join(sdir, 'workers');
+    if (await pathExists(workersDir)) {
+        const files = (await fs.readdir(workersDir)).filter((f) => f.endsWith('.json'));
+        for (const f of files.sort()) {
+            const w = await readJson(path.join(workersDir, f));
+            if (w && w.id)
+                workers.push({ ...w, status: w.status ?? 'unknown' });
+        }
+    }
+    if (state || workers.length) {
+        return {
+            issueId,
+            title: state?.title,
+            complexity: state?.complexity,
+            status: state?.status ?? deriveStatus(workers),
+            createdAt: state?.createdAt,
+            updatedAt: state?.updatedAt,
+            repos: state?.repos,
+            waves: state?.waves,
+            workers: workers.length ? workers : wavesToWorkers(state?.waves),
+        };
+    }
+    // Fallback: parse execution-plan.md so old sessions still render.
+    return parsePlanFallback(sdir, issueId);
+}
+function deriveStatus(workers) {
+    if (!workers.length)
+        return 'unknown';
+    if (workers.some((w) => w.status === 'blocked'))
+        return 'blocked';
+    if (workers.every((w) => w.status === 'done'))
+        return 'done';
+    if (workers.some((w) => w.status === 'running'))
+        return 'running';
+    return 'planned';
+}
+function wavesToWorkers(waves) {
+    if (!waves)
+        return [];
+    return waves.flat().map((id) => ({ id, status: 'unknown' }));
+}
+/** Best-effort extraction of the DAG table from execution-plan.md. */
+async function parsePlanFallback(sdir, issueId) {
+    const planPath = path.join(sdir, 'execution-plan.md');
+    const empty = { issueId, status: 'unknown', workers: [], fromPlanFallback: true };
+    if (!(await pathExists(planPath)))
+        return empty;
+    const text = await fs.readFile(planPath, 'utf-8');
+    const title = /Execution Plan[^(]*\(([^)]+)\)/.exec(text)?.[1];
+    const complexity = /\*\*(simple|medium|complex)\*\*/i.exec(text)?.[1]?.toLowerCase();
+    // Parse DAG table rows: | id | archetype | repo | objective | dependsOn |
+    const workers = [];
+    for (const line of text.split('\n')) {
+        const m = /^\|([^|]*)\|([^|]*)\|([^|]*)\|([^|]*)\|([^|]*)\|/.exec(line);
+        if (!m)
+            continue;
+        const id = m[1].trim();
+        if (!/^W\d+$/.test(id))
+            continue;
+        const [archetype, repo, objective, deps] = [m[2].trim(), m[3].trim(), m[4].trim(), m[5].trim()];
+        workers.push({
+            id,
+            archetype,
+            repository: repo === '—' ? null : repo,
+            objective,
+            dependsOn: deps && deps !== '—' ? deps.split(',').map((d) => d.trim()) : [],
+            status: 'unknown',
+        });
+    }
+    return {
+        issueId,
+        title,
+        complexity,
+        status: 'unknown',
+        workers,
+        fromPlanFallback: true,
+    };
+}

package/dist/index.js

@@ -6,6 +6,7 @@ import { addRepoCommand } from './commands/add-repo.js';
 import { updateCommandsCommand } from './commands/update-commands.js';
 import { doctorCommand } from './commands/doctor.js';
 import { statusCommand } from './commands/status.js';
+import { dashboardCommand } from './commands/dashboard.js';
 const program = new Command();
 program
     .name('context-agents')
@@ -43,4 +44,9 @@ program
     .command('status')
     .description('Show orchestrator repos, risk signals, and active sessions')
     .action(statusCommand);
+program
+    .command('dashboard')
+    .description('Serve a local web dashboard of sessions and running agents')
+    .option('-p, --port <port>', 'Port to listen on', '4517')
+    .action(dashboardCommand);
 program.parseAsync(process.argv);

package/dist/templates/commands/en/orchestrate.md

@@ -93,15 +93,64 @@ See `agents/CONTEXT-CONTRACT.md` for the exact shape. In short:
 - **limits**: `contextPolicy` (default `select-do-not-dump`), `maxFilesPerWorker`
 - **return**: summary, changes, evidence, tests, unresolved questions, confidence
 
-## Step 6 — Spawn ephemeral agents (Task tool)
+## Step 5b — Prepare the session worktrees (via git, not Node)
+
+Before spawning any agent, create an **isolated git worktree per impacted repository**
+(only the ones in the graph), so each implementer has a place to write without touching
+the main repo. Use `base_path` (from `ai.properties.md`) and the `<ISSUE-ID>`.
+
+For each impacted repository `<repo>`:
+
+1. If `.sessions/<ISSUE-ID>/<repo>/` already exists, **skip** (worktree ready).
+2. Check whether branch `feature/<ISSUE-ID>` already exists in the repo:
+   ```bash
+   git -C "{base_path}/<repo>" rev-parse --verify --quiet "feature/<ISSUE-ID>"
+   ```
+3. Create the worktree from the main repo:
+   - if the branch does **not** exist (create it in the worktree):
+     ```bash
+     git -C "{base_path}/<repo>" worktree add -b "feature/<ISSUE-ID>" \
+         "$(pwd)/.sessions/<ISSUE-ID>/<repo>"
+     ```
+   - if the branch **already** exists (reuse it):
+     ```bash
+     git -C "{base_path}/<repo>" worktree add \
+         "$(pwd)/.sessions/<ISSUE-ID>/<repo>" "feature/<ISSUE-ID>"
+     ```
+
+Rules:
+- **Never** `checkout` in the main repo (`{base_path}/<repo>`) — the worktree isolates everything.
+- If `git worktree add` fails with "already exists", treat it as ready and continue.
+- Only prepare worktrees for the **impacted** repos in the graph, not every repo in the manifest.
+- Record in `execution-plan.md` which worktrees were created (path + branch).
+
+After this, each agent's `writeBoundary` (`.sessions/<ISSUE-ID>/<repo>/`) actually exists.
+
+## Step 5c — Write the initial state (for the dashboard)
+
+Write machine-readable state into `.sessions/<ISSUE-ID>/` (format in the orchestrator's
+`SESSION-STATE.md`). This feeds `context-agents dashboard`.
+
+1. `state.json`: `{ issueId, title, complexity, status:"planned", createdAt, repos, waves }`
+   (`waves` = the waves from Step 4).
+2. `workers/<id>.json` for each node: `{ id, archetype, repository, objective, dependsOn,
+   status:"pending", currentStep:null, startedAt:null, finishedAt:null, verdict:null }`.
+
+Keep writes small and frequent — the dashboard polls these files.
 
-Execute the DAG respecting `dependsOn`:
+## Step 6 — Spawn ephemeral agents (Task tool)
 
-1. **Parallel wave**: spawn all nodes whose dependencies are satisfied **in a single
-   message with multiple Task calls** so they run concurrently. Give each subagent ONLY
-   its compiled contract + objective — never the whole conversation.
-2. Wait for a wave to finish. Collect each subagent's structured return.
-3. **Next wave**: spawn nodes whose dependencies are now satisfied. Repeat until done.
+Execute the DAG respecting `dependsOn`. **On each transition, update the state files**:
+
+1. **When a wave starts**: for each node in the wave, set `workers/<id>.json` to
+   `status:"running"`, `startedAt`, and a short `currentStep`; set `state.json.status="running"`.
+2. **Parallel wave**: spawn all nodes in the wave **in a single message with multiple Task
+   calls** so they run concurrently. Give each subagent ONLY its compiled contract +
+   objective — never the whole conversation.
+3. **On return**: set each `workers/<id>.json` to `status:"done"` (or `"blocked"`),
+   `finishedAt`, and `verdict` if any (reviewer/tester/integrator).
+4. **Next wave**: spawn nodes whose dependencies are now satisfied. Repeat until done.
+5. **At the end**: `state.json.status="done"` (or `"blocked"` if any blocked).
 
 Use the archetype prompt templates in `agents/` (implementer, reviewer, integrator,
 tester, …) as the system framing for each subagent, filled with the node's objective,

package/dist/templates/commands/es/orchestrate.md

@@ -94,15 +94,64 @@ Ver `agents/CONTEXT-CONTRACT.md` para el formato exacto. En resumen:
 - **limits**: `contextPolicy` (por defecto `select-do-not-dump`), `maxFilesPerWorker`
 - **return**: summary, changes, evidence, tests, unresolved, confidence
 
-## Paso 6 — Spawnear los agentes efímeros (Task tool)
+## Paso 5b — Preparar los worktrees de la sesión (vía git, no Node)
+
+Antes de spawnear cualquier agente, crea un **git worktree aislado por repositorio
+impactado** (sólo los del grafo), para que cada implementer tenga dónde escribir sin tocar
+el repo principal. Usa `base_path` (de `ai.properties.md`) y el `<ISSUE-ID>`.
+
+Para cada repositorio impactado `<repo>`:
+
+1. Si `.sessions/<ISSUE-ID>/<repo>/` ya existe, **sáltalo** (worktree listo).
+2. Chequea si la branch `feature/<ISSUE-ID>` ya existe en el repo:
+   ```bash
+   git -C "{base_path}/<repo>" rev-parse --verify --quiet "feature/<ISSUE-ID>"
+   ```
+3. Crea el worktree desde el repo principal:
+   - si la branch **no** existe (créala en el worktree):
+     ```bash
+     git -C "{base_path}/<repo>" worktree add -b "feature/<ISSUE-ID>" \
+         "$(pwd)/.sessions/<ISSUE-ID>/<repo>"
+     ```
+   - si la branch **ya** existe (reutilízala):
+     ```bash
+     git -C "{base_path}/<repo>" worktree add \
+         "$(pwd)/.sessions/<ISSUE-ID>/<repo>" "feature/<ISSUE-ID>"
+     ```
+
+Reglas:
+- **Nunca** hagas `checkout` en el repo principal (`{base_path}/<repo>`) — el worktree aísla todo.
+- Si `git worktree add` falla con "already exists", trátalo como listo y continúa.
+- Sólo prepara worktrees de los repos **impactados** del grafo, no de todos los del manifiesto.
+- Registra en `execution-plan.md` qué worktrees se crearon (path + branch).
+
+Tras esto, el `writeBoundary` de cada agente (`.sessions/<ISSUE-ID>/<repo>/`) existe de verdad.
+
+## Paso 5c — Escribir el estado inicial (para el dashboard)
+
+Escribe el estado legible por máquina en `.sessions/<ISSUE-ID>/` (formato en el
+`SESSION-STATE.md` del orquestador). Esto alimenta `context-agents dashboard`.
+
+1. `state.json`: `{ issueId, title, complexity, status:"planned", createdAt, repos, waves }`
+   (`waves` = las olas del Paso 4).
+2. `workers/<id>.json` para cada nodo: `{ id, archetype, repository, objective, dependsOn,
+   status:"pending", currentStep:null, startedAt:null, finishedAt:null, verdict:null }`.
+
+Mantén escrituras pequeñas y frecuentes — el dashboard hace polling de estos archivos.
 
-Ejecuta el DAG respetando `dependsOn`:
+## Paso 6 — Spawnear los agentes efímeros (Task tool)
 
-1. **Ola paralela**: spawnea todos los nodos con dependencias satisfechas **en un único
-   mensaje con múltiples llamadas Task**, para que corran concurrentemente. Dale a cada
-   subagente SÓLO su contrato compilado + objetivo — nunca la conversación entera.
-2. Espera a que la ola termine. Recolecta el retorno estructurado de cada subagente.
-3. **Siguiente ola**: spawnea los nodos cuyas dependencias ya están satisfechas. Repite.
+Ejecuta el DAG respetando `dependsOn`. **En cada transición, actualiza los archivos de estado**:
+
+1. **Al iniciar una ola**: para cada nodo de la ola, marca `workers/<id>.json` con
+   `status:"running"`, `startedAt`, y un `currentStep` corto; marca `state.json.status="running"`.
+2. **Ola paralela**: spawnea todos los nodos de la ola **en un único mensaje con múltiples
+   llamadas Task**, para que corran concurrentemente. Dale a cada subagente SÓLO su
+   contrato compilado + objetivo — nunca la conversación entera.
+3. **Al retornar**: marca cada `workers/<id>.json` con `status:"done"` (o `"blocked"`),
+   `finishedAt`, y `verdict` si hay (reviewer/tester/integrator).
+4. **Siguiente ola**: spawnea los nodos cuyas dependencias ya están satisfechas. Repite.
+5. **Al final**: `state.json.status="done"` (o `"blocked"` si alguno bloqueó).
 
 Usa las plantillas de arquetipo en `agents/` (implementer, reviewer, integrator, tester…)
 como marco de cada subagente, rellenadas con objetivo, repositorio y contrato.

package/dist/templates/commands/pt-BR/orchestrate.md

@@ -94,15 +94,64 @@ Veja `agents/CONTEXT-CONTRACT.md` para o formato exato. Em resumo:
 - **limits**: `contextPolicy` (padrão `select-do-not-dump`), `maxFilesPerWorker`
 - **return**: summary, changes, evidence, tests, unresolved, confidence
 
-## Passo 6 — Spawnar os agentes efêmeros (Task tool)
+## Passo 5b — Preparar os worktrees da sessão (via git, não Node)
+
+Antes de spawnar qualquer agente, crie um **git worktree isolado por repositório
+impactado** (só os do grafo), para que cada implementer tenha onde escrever sem tocar no
+repo principal. Use `base_path` (de `ai.properties.md`) e o `<ISSUE-ID>`.
+
+Para cada repositório impactado `<repo>`:
+
+1. Se `.sessions/<ISSUE-ID>/<repo>/` já existir, **pule** (worktree já preparado).
+2. Descubra se a branch `feature/<ISSUE-ID>` já existe no repo:
+   ```bash
+   git -C "{base_path}/<repo>" rev-parse --verify --quiet "feature/<ISSUE-ID>"
+   ```
+3. Crie o worktree a partir do repo principal:
+   - se a branch **não** existe (cria a branch no worktree):
+     ```bash
+     git -C "{base_path}/<repo>" worktree add -b "feature/<ISSUE-ID>" \
+         "$(pwd)/.sessions/<ISSUE-ID>/<repo>"
+     ```
+   - se a branch **já** existe (reaproveita):
+     ```bash
+     git -C "{base_path}/<repo>" worktree add \
+         "$(pwd)/.sessions/<ISSUE-ID>/<repo>" "feature/<ISSUE-ID>"
+     ```
+
+Regras:
+- **Nunca** faça `checkout` no repo principal (`{base_path}/<repo>`) — o worktree isola tudo.
+- Se `git worktree add` falhar por "already exists", trate como já preparado e siga.
+- Só prepare worktrees dos repos **impactados** pelo grafo, não de todos do manifesto.
+- Registre no `execution-plan.md` quais worktrees foram criados (path + branch).
+
+Depois disso, o `writeBoundary` de cada agente (`.sessions/<ISSUE-ID>/<repo>/`) existe de fato.
+
+## Passo 5c — Gravar o estado inicial (para o dashboard)
+
+Grave o estado legível por máquina em `.sessions/<ISSUE-ID>/` (formato em
+`SESSION-STATE.md` do orquestrador). Isto alimenta o `context-agents dashboard`.
+
+1. `state.json`: `{ issueId, title, complexity, status:"planned", createdAt, repos, waves }`
+   (`waves` = as ondas do Passo 4).
+2. `workers/<id>.json` para cada nó: `{ id, archetype, repository, objective, dependsOn,
+   status:"pending", currentStep:null, startedAt:null, finishedAt:null, verdict:null }`.
+
+Mantenha escritas pequenas e frequentes — o dashboard faz polling desses arquivos.
 
-Execute o DAG respeitando `dependsOn`:
+## Passo 6 — Spawnar os agentes efêmeros (Task tool)
 
-1. **Onda paralela**: spawne todos os nós com dependências satisfeitas **numa única
-   mensagem com múltiplas chamadas Task**, para rodarem concorrentemente. Dê a cada
-   subagente APENAS o contrato compilado + objetivo — nunca a conversa inteira.
-2. Aguarde a onda terminar. Colete o retorno estruturado de cada subagente.
-3. **Próxima onda**: spawne os nós cujas dependências agora estão satisfeitas. Repita.
+Execute o DAG respeitando `dependsOn`. **A cada transição, atualize os arquivos de estado**:
+
+1. **Ao iniciar uma onda**: para cada nó da onda, marque `workers/<id>.json` com
+   `status:"running"`, `startedAt`, e um `currentStep` curto; marque `state.json.status="running"`.
+2. **Onda paralela**: spawne todos os nós da onda **numa única mensagem com múltiplas
+   chamadas Task**, para rodarem concorrentemente. Dê a cada subagente APENAS o contrato
+   compilado + objetivo — nunca a conversa inteira.
+3. **Ao retornar**: marque cada `workers/<id>.json` com `status:"done"` (ou `"blocked"`),
+   `finishedAt`, e `verdict` se houver (reviewer/tester/integrator).
+4. **Próxima onda**: spawne os nós cujas dependências agora estão satisfeitas. Repita.
+5. **Ao final**: `state.json.status="done"` (ou `"blocked"` se algum bloqueou).
 
 Use os templates de arquétipo em `agents/` (implementer, reviewer, integrator, tester…)
 como enquadramento de cada subagente, preenchidos com objetivo, repositório e contrato.

package/dist/templates/dashboard/index.html

@@ -0,0 +1,123 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Context-First Agents — Dashboard</title>
+<style>
+  :root {
+    --bg: #0d1117; --panel: #161b22; --border: #30363d; --text: #e6edf3;
+    --muted: #8b949e; --accent: #58a6ff;
+    --pending: #6e7681; --running: #d29922; --done: #3fb950; --blocked: #f85149;
+  }
+  * { box-sizing: border-box; }
+  body { margin: 0; background: var(--bg); color: var(--text);
+    font: 14px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; }
+  header { padding: 16px 24px; border-bottom: 1px solid var(--border);
+    display: flex; align-items: center; gap: 16px; position: sticky; top: 0; background: var(--bg); z-index: 5; }
+  header h1 { font-size: 16px; margin: 0; font-weight: 600; }
+  header .project { color: var(--accent); }
+  header .meta { margin-left: auto; color: var(--muted); font-size: 12px; }
+  .wrap { padding: 24px; max-width: 1100px; margin: 0 auto; display: grid; gap: 20px; }
+  .session { background: var(--panel); border: 1px solid var(--border); border-radius: 10px; overflow: hidden; }
+  .session > .head { padding: 14px 18px; display: flex; align-items: center; gap: 12px; cursor: pointer; }
+  .session .id { font-weight: 700; }
+  .session .title { color: var(--muted); }
+  .chip { font-size: 11px; padding: 2px 8px; border-radius: 20px; border: 1px solid var(--border); text-transform: uppercase; letter-spacing: .04em; }
+  .chip.simple { color: #3fb950; } .chip.medium { color: #d29922; } .chip.complex { color: #f85149; }
+  .status-dot { width: 9px; height: 9px; border-radius: 50%; display: inline-block; }
+  .s-planned { background: var(--pending); } .s-pending { background: var(--pending); }
+  .s-running { background: var(--running); box-shadow: 0 0 0 3px rgba(210,153,34,.2); animation: pulse 1.4s infinite; }
+  .s-done { background: var(--done); } .s-blocked { background: var(--blocked); } .s-unknown { background: #484f58; }
+  @keyframes pulse { 0%,100% { opacity: 1 } 50% { opacity: .4 } }
+  .agents { padding: 6px 18px 18px; display: grid; gap: 10px; }
+  .wave-label { font-size: 11px; color: var(--muted); text-transform: uppercase; letter-spacing: .06em; margin-top: 8px; }
+  .agent { border: 1px solid var(--border); border-radius: 8px; padding: 10px 12px; display: grid;
+    grid-template-columns: auto 1fr auto; gap: 10px; align-items: start; }
+  .agent .arch { font-size: 12px; color: var(--accent); font-weight: 600; }
+  .agent .obj { color: var(--muted); font-size: 13px; }
+  .agent .step { color: var(--running); font-size: 12px; margin-top: 2px; }
+  .agent .repo { font-size: 11px; color: var(--muted); }
+  .agent .verdict { font-size: 11px; font-weight: 700; padding: 2px 6px; border-radius: 4px; border: 1px solid var(--border); }
+  .deps { font-size: 11px; color: var(--muted); }
+  .empty { color: var(--muted); padding: 40px; text-align: center; }
+  .fallback { font-size: 11px; color: var(--running); margin-left: 8px; }
+  a { color: var(--accent); }
+</style>
+</head>
+<body>
+<header>
+  <h1>Context-First Agents · <span class="project" id="project">…</span></h1>
+  <div class="meta"><span id="count">0</span> sessions · auto-refresh <span id="tick">2s</span></div>
+</header>
+<div class="wrap" id="root"><div class="empty">Loading…</div></div>
+
+<script>
+const ARCH_ORDER = { implementer: 0, integrator: 1, reviewer: 2, tester: 3 };
+const el = (tag, cls, html) => { const e = document.createElement(tag); if (cls) e.className = cls; if (html != null) e.innerHTML = html; return e; };
+const esc = (s) => (s ?? '').replace(/[&<>]/g, c => ({ '&':'&amp;','<':'&lt;','>':'&gt;' }[c]));
+
+function agentCard(w) {
+  const card = el('div', 'agent');
+  const dot = el('div', 'status-dot s-' + (w.status || 'unknown'));
+  dot.title = w.status || 'unknown';
+  const mid = el('div');
+  mid.appendChild(el('div', 'arch', esc((w.id ? w.id + ' · ' : '') + (w.archetype || ''))));
+  if (w.objective) mid.appendChild(el('div', 'obj', esc(w.objective)));
+  if (w.currentStep && w.status === 'running') mid.appendChild(el('div', 'step', '▸ ' + esc(w.currentStep)));
+  if (w.dependsOn && w.dependsOn.length) mid.appendChild(el('div', 'deps', 'depends on ' + esc(w.dependsOn.join(', '))));
+  const right = el('div');
+  if (w.repository) right.appendChild(el('div', 'repo', esc(w.repository)));
+  if (w.verdict) { const v = el('div', 'verdict', esc(w.verdict)); v.style.color = /pass|green|consistent|done/i.test(w.verdict) ? 'var(--done)' : 'var(--blocked)'; right.appendChild(v); }
+  card.append(dot, mid, right);
+  return card;
+}
+
+function sessionCard(s) {
+  const box = el('div', 'session');
+  const head = el('div', 'head');
+  head.appendChild(el('span', 'status-dot s-' + (s.status || 'unknown')));
+  head.appendChild(el('span', 'id', esc(s.issueId)));
+  if (s.title) head.appendChild(el('span', 'title', esc(s.title)));
+  if (s.complexity) head.appendChild(el('span', 'chip ' + s.complexity, esc(s.complexity)));
+  if (s.fromPlanFallback) head.appendChild(el('span', 'fallback', '(no live state — from plan)'));
+  box.appendChild(head);
+
+  const agents = el('div', 'agents');
+  const byId = Object.fromEntries((s.workers || []).map(w => [w.id, w]));
+  const waves = s.waves && s.waves.length ? s.waves : null;
+  if (waves) {
+    waves.forEach((wave, i) => {
+      agents.appendChild(el('div', 'wave-label', 'Wave ' + (i + 1)));
+      wave.forEach(id => agents.appendChild(agentCard(byId[id] || { id, status: 'unknown' })));
+    });
+  } else {
+    const sorted = (s.workers || []).slice().sort((a, b) => (ARCH_ORDER[a.archetype] ?? 9) - (ARCH_ORDER[b.archetype] ?? 9));
+    if (!sorted.length) agents.appendChild(el('div', 'empty', 'No workers recorded yet.'));
+    sorted.forEach(w => agents.appendChild(agentCard(w)));
+  }
+  box.appendChild(agents);
+  return box;
+}
+
+async function refresh() {
+  try {
+    const res = await fetch('/api/sessions');
+    const data = await res.json();
+    document.getElementById('project').textContent = data.project || 'orchestrator';
+    document.getElementById('count').textContent = (data.sessions || []).length;
+    const root = document.getElementById('root');
+    root.innerHTML = '';
+    if (!data.sessions || !data.sessions.length) { root.appendChild(el('div', 'empty', 'No sessions yet. Run <code>/orchestrate &lt;ISSUE-ID&gt;</code>.')); return; }
+    // Most recently updated first
+    data.sessions.sort((a, b) => (b.updatedAt || b.createdAt || '').localeCompare(a.updatedAt || a.createdAt || ''));
+    data.sessions.forEach(s => root.appendChild(sessionCard(s)));
+  } catch (e) {
+    document.getElementById('root').innerHTML = '<div class="empty">Server unreachable. Is <code>context-agents dashboard</code> running?</div>';
+  }
+}
+refresh();
+setInterval(refresh, 2000);
+</script>
+</body>
+</html>

package/dist/templates/orchestrator/SESSION-STATE.md

@@ -0,0 +1,65 @@
+# Session State Schema
+
+The `/orchestrate` command writes machine-readable state into each session directory so
+tools (like `context-agents dashboard`) can render live progress. Human-readable
+`execution-plan.md` stays alongside.
+
+```
+.sessions/<ISSUE-ID>/
+├── execution-plan.md      # human-readable (prose)
+├── state.json             # session-level state
+└── workers/
+    ├── W1.json            # one file per agent/worker
+    ├── W2.json
+    └── ...
+```
+
+## `state.json`
+
+```json
+{
+  "issueId": "ISSUE-42",
+  "title": "Example feature",
+  "complexity": "medium",
+  "status": "running",
+  "createdAt": "2026-09-13T12:10:00Z",
+  "updatedAt": "2026-09-13T12:15:00Z",
+  "repos": ["client-b"],
+  "waves": [["W1", "W2"], ["W3"], ["W4"], ["W5"]]
+}
+```
+
+- `status`: `planned` | `running` | `blocked` | `done`.
+- `waves`: array of arrays of worker ids, in execution order.
+
+## `workers/<id>.json`
+
+```json
+{
+  "id": "W1",
+  "archetype": "implementer",
+  "repository": "client-b",
+  "objective": "Audio pipeline: mic+tab capture, FFT bands/RMS/onset",
+  "dependsOn": [],
+  "status": "running",
+  "currentStep": "implementing FFT analyser",
+  "startedAt": "2026-09-13T12:11:00Z",
+  "finishedAt": null,
+  "verdict": null
+}
+```
+
+- `status`: `pending` | `running` | `done` | `blocked`.
+- `verdict` (optional): for reviewer/tester/integrator, e.g. `PASS` | `BLOCKED` |
+  `GREEN` | `RED` | `CONSISTENT` | `MISMATCH`.
+
+## Update protocol (for `/orchestrate`)
+
+1. Right after the graph is approved: write `state.json` (`status: "planned"`) and one
+   `workers/<id>.json` per node (`status: "pending"`).
+2. When a wave starts: set each of its workers to `running` + a short `currentStep`;
+   set `state.json.status = "running"`.
+3. When a worker returns: set `done` (or `blocked`), `finishedAt`, and `verdict` if any.
+4. When all workers finish: set `state.json.status = "done"` (or `blocked` if any blocked).
+
+Keep writes small and frequent — the dashboard polls these files.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thatix.io/context-first-agents-cli",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "publishConfig": {
     "access": "public"
   },

package/templates/commands/en/orchestrate.md

@@ -93,15 +93,64 @@ See `agents/CONTEXT-CONTRACT.md` for the exact shape. In short:
 - **limits**: `contextPolicy` (default `select-do-not-dump`), `maxFilesPerWorker`
 - **return**: summary, changes, evidence, tests, unresolved questions, confidence
 
-## Step 6 — Spawn ephemeral agents (Task tool)
+## Step 5b — Prepare the session worktrees (via git, not Node)
+
+Before spawning any agent, create an **isolated git worktree per impacted repository**
+(only the ones in the graph), so each implementer has a place to write without touching
+the main repo. Use `base_path` (from `ai.properties.md`) and the `<ISSUE-ID>`.
+
+For each impacted repository `<repo>`:
+
+1. If `.sessions/<ISSUE-ID>/<repo>/` already exists, **skip** (worktree ready).
+2. Check whether branch `feature/<ISSUE-ID>` already exists in the repo:
+   ```bash
+   git -C "{base_path}/<repo>" rev-parse --verify --quiet "feature/<ISSUE-ID>"
+   ```
+3. Create the worktree from the main repo:
+   - if the branch does **not** exist (create it in the worktree):
+     ```bash
+     git -C "{base_path}/<repo>" worktree add -b "feature/<ISSUE-ID>" \
+         "$(pwd)/.sessions/<ISSUE-ID>/<repo>"
+     ```
+   - if the branch **already** exists (reuse it):
+     ```bash
+     git -C "{base_path}/<repo>" worktree add \
+         "$(pwd)/.sessions/<ISSUE-ID>/<repo>" "feature/<ISSUE-ID>"
+     ```
+
+Rules:
+- **Never** `checkout` in the main repo (`{base_path}/<repo>`) — the worktree isolates everything.
+- If `git worktree add` fails with "already exists", treat it as ready and continue.
+- Only prepare worktrees for the **impacted** repos in the graph, not every repo in the manifest.
+- Record in `execution-plan.md` which worktrees were created (path + branch).
+
+After this, each agent's `writeBoundary` (`.sessions/<ISSUE-ID>/<repo>/`) actually exists.
+
+## Step 5c — Write the initial state (for the dashboard)
+
+Write machine-readable state into `.sessions/<ISSUE-ID>/` (format in the orchestrator's
+`SESSION-STATE.md`). This feeds `context-agents dashboard`.
+
+1. `state.json`: `{ issueId, title, complexity, status:"planned", createdAt, repos, waves }`
+   (`waves` = the waves from Step 4).
+2. `workers/<id>.json` for each node: `{ id, archetype, repository, objective, dependsOn,
+   status:"pending", currentStep:null, startedAt:null, finishedAt:null, verdict:null }`.
+
+Keep writes small and frequent — the dashboard polls these files.
 
-Execute the DAG respecting `dependsOn`:
+## Step 6 — Spawn ephemeral agents (Task tool)
 
-1. **Parallel wave**: spawn all nodes whose dependencies are satisfied **in a single
-   message with multiple Task calls** so they run concurrently. Give each subagent ONLY
-   its compiled contract + objective — never the whole conversation.
-2. Wait for a wave to finish. Collect each subagent's structured return.
-3. **Next wave**: spawn nodes whose dependencies are now satisfied. Repeat until done.
+Execute the DAG respecting `dependsOn`. **On each transition, update the state files**:
+
+1. **When a wave starts**: for each node in the wave, set `workers/<id>.json` to
+   `status:"running"`, `startedAt`, and a short `currentStep`; set `state.json.status="running"`.
+2. **Parallel wave**: spawn all nodes in the wave **in a single message with multiple Task
+   calls** so they run concurrently. Give each subagent ONLY its compiled contract +
+   objective — never the whole conversation.
+3. **On return**: set each `workers/<id>.json` to `status:"done"` (or `"blocked"`),
+   `finishedAt`, and `verdict` if any (reviewer/tester/integrator).
+4. **Next wave**: spawn nodes whose dependencies are now satisfied. Repeat until done.
+5. **At the end**: `state.json.status="done"` (or `"blocked"` if any blocked).
 
 Use the archetype prompt templates in `agents/` (implementer, reviewer, integrator,
 tester, …) as the system framing for each subagent, filled with the node's objective,

package/templates/commands/es/orchestrate.md

@@ -94,15 +94,64 @@ Ver `agents/CONTEXT-CONTRACT.md` para el formato exacto. En resumen:
 - **limits**: `contextPolicy` (por defecto `select-do-not-dump`), `maxFilesPerWorker`
 - **return**: summary, changes, evidence, tests, unresolved, confidence
 
-## Paso 6 — Spawnear los agentes efímeros (Task tool)
+## Paso 5b — Preparar los worktrees de la sesión (vía git, no Node)
+
+Antes de spawnear cualquier agente, crea un **git worktree aislado por repositorio
+impactado** (sólo los del grafo), para que cada implementer tenga dónde escribir sin tocar
+el repo principal. Usa `base_path` (de `ai.properties.md`) y el `<ISSUE-ID>`.
+
+Para cada repositorio impactado `<repo>`:
+
+1. Si `.sessions/<ISSUE-ID>/<repo>/` ya existe, **sáltalo** (worktree listo).
+2. Chequea si la branch `feature/<ISSUE-ID>` ya existe en el repo:
+   ```bash
+   git -C "{base_path}/<repo>" rev-parse --verify --quiet "feature/<ISSUE-ID>"
+   ```
+3. Crea el worktree desde el repo principal:
+   - si la branch **no** existe (créala en el worktree):
+     ```bash
+     git -C "{base_path}/<repo>" worktree add -b "feature/<ISSUE-ID>" \
+         "$(pwd)/.sessions/<ISSUE-ID>/<repo>"
+     ```
+   - si la branch **ya** existe (reutilízala):
+     ```bash
+     git -C "{base_path}/<repo>" worktree add \
+         "$(pwd)/.sessions/<ISSUE-ID>/<repo>" "feature/<ISSUE-ID>"
+     ```
+
+Reglas:
+- **Nunca** hagas `checkout` en el repo principal (`{base_path}/<repo>`) — el worktree aísla todo.
+- Si `git worktree add` falla con "already exists", trátalo como listo y continúa.
+- Sólo prepara worktrees de los repos **impactados** del grafo, no de todos los del manifiesto.
+- Registra en `execution-plan.md` qué worktrees se crearon (path + branch).
+
+Tras esto, el `writeBoundary` de cada agente (`.sessions/<ISSUE-ID>/<repo>/`) existe de verdad.
+
+## Paso 5c — Escribir el estado inicial (para el dashboard)
+
+Escribe el estado legible por máquina en `.sessions/<ISSUE-ID>/` (formato en el
+`SESSION-STATE.md` del orquestador). Esto alimenta `context-agents dashboard`.
+
+1. `state.json`: `{ issueId, title, complexity, status:"planned", createdAt, repos, waves }`
+   (`waves` = las olas del Paso 4).
+2. `workers/<id>.json` para cada nodo: `{ id, archetype, repository, objective, dependsOn,
+   status:"pending", currentStep:null, startedAt:null, finishedAt:null, verdict:null }`.
+
+Mantén escrituras pequeñas y frecuentes — el dashboard hace polling de estos archivos.
 
-Ejecuta el DAG respetando `dependsOn`:
+## Paso 6 — Spawnear los agentes efímeros (Task tool)
 
-1. **Ola paralela**: spawnea todos los nodos con dependencias satisfechas **en un único
-   mensaje con múltiples llamadas Task**, para que corran concurrentemente. Dale a cada
-   subagente SÓLO su contrato compilado + objetivo — nunca la conversación entera.
-2. Espera a que la ola termine. Recolecta el retorno estructurado de cada subagente.
-3. **Siguiente ola**: spawnea los nodos cuyas dependencias ya están satisfechas. Repite.
+Ejecuta el DAG respetando `dependsOn`. **En cada transición, actualiza los archivos de estado**:
+
+1. **Al iniciar una ola**: para cada nodo de la ola, marca `workers/<id>.json` con
+   `status:"running"`, `startedAt`, y un `currentStep` corto; marca `state.json.status="running"`.
+2. **Ola paralela**: spawnea todos los nodos de la ola **en un único mensaje con múltiples
+   llamadas Task**, para que corran concurrentemente. Dale a cada subagente SÓLO su
+   contrato compilado + objetivo — nunca la conversación entera.
+3. **Al retornar**: marca cada `workers/<id>.json` con `status:"done"` (o `"blocked"`),
+   `finishedAt`, y `verdict` si hay (reviewer/tester/integrator).
+4. **Siguiente ola**: spawnea los nodos cuyas dependencias ya están satisfechas. Repite.
+5. **Al final**: `state.json.status="done"` (o `"blocked"` si alguno bloqueó).
 
 Usa las plantillas de arquetipo en `agents/` (implementer, reviewer, integrator, tester…)
 como marco de cada subagente, rellenadas con objetivo, repositorio y contrato.

package/templates/commands/pt-BR/orchestrate.md

@@ -94,15 +94,64 @@ Veja `agents/CONTEXT-CONTRACT.md` para o formato exato. Em resumo:
 - **limits**: `contextPolicy` (padrão `select-do-not-dump`), `maxFilesPerWorker`
 - **return**: summary, changes, evidence, tests, unresolved, confidence
 
-## Passo 6 — Spawnar os agentes efêmeros (Task tool)
+## Passo 5b — Preparar os worktrees da sessão (via git, não Node)
+
+Antes de spawnar qualquer agente, crie um **git worktree isolado por repositório
+impactado** (só os do grafo), para que cada implementer tenha onde escrever sem tocar no
+repo principal. Use `base_path` (de `ai.properties.md`) e o `<ISSUE-ID>`.
+
+Para cada repositório impactado `<repo>`:
+
+1. Se `.sessions/<ISSUE-ID>/<repo>/` já existir, **pule** (worktree já preparado).
+2. Descubra se a branch `feature/<ISSUE-ID>` já existe no repo:
+   ```bash
+   git -C "{base_path}/<repo>" rev-parse --verify --quiet "feature/<ISSUE-ID>"
+   ```
+3. Crie o worktree a partir do repo principal:
+   - se a branch **não** existe (cria a branch no worktree):
+     ```bash
+     git -C "{base_path}/<repo>" worktree add -b "feature/<ISSUE-ID>" \
+         "$(pwd)/.sessions/<ISSUE-ID>/<repo>"
+     ```
+   - se a branch **já** existe (reaproveita):
+     ```bash
+     git -C "{base_path}/<repo>" worktree add \
+         "$(pwd)/.sessions/<ISSUE-ID>/<repo>" "feature/<ISSUE-ID>"
+     ```
+
+Regras:
+- **Nunca** faça `checkout` no repo principal (`{base_path}/<repo>`) — o worktree isola tudo.
+- Se `git worktree add` falhar por "already exists", trate como já preparado e siga.
+- Só prepare worktrees dos repos **impactados** pelo grafo, não de todos do manifesto.
+- Registre no `execution-plan.md` quais worktrees foram criados (path + branch).
+
+Depois disso, o `writeBoundary` de cada agente (`.sessions/<ISSUE-ID>/<repo>/`) existe de fato.
+
+## Passo 5c — Gravar o estado inicial (para o dashboard)
+
+Grave o estado legível por máquina em `.sessions/<ISSUE-ID>/` (formato em
+`SESSION-STATE.md` do orquestrador). Isto alimenta o `context-agents dashboard`.
+
+1. `state.json`: `{ issueId, title, complexity, status:"planned", createdAt, repos, waves }`
+   (`waves` = as ondas do Passo 4).
+2. `workers/<id>.json` para cada nó: `{ id, archetype, repository, objective, dependsOn,
+   status:"pending", currentStep:null, startedAt:null, finishedAt:null, verdict:null }`.
+
+Mantenha escritas pequenas e frequentes — o dashboard faz polling desses arquivos.
 
-Execute o DAG respeitando `dependsOn`:
+## Passo 6 — Spawnar os agentes efêmeros (Task tool)
 
-1. **Onda paralela**: spawne todos os nós com dependências satisfeitas **numa única
-   mensagem com múltiplas chamadas Task**, para rodarem concorrentemente. Dê a cada
-   subagente APENAS o contrato compilado + objetivo — nunca a conversa inteira.
-2. Aguarde a onda terminar. Colete o retorno estruturado de cada subagente.
-3. **Próxima onda**: spawne os nós cujas dependências agora estão satisfeitas. Repita.
+Execute o DAG respeitando `dependsOn`. **A cada transição, atualize os arquivos de estado**:
+
+1. **Ao iniciar uma onda**: para cada nó da onda, marque `workers/<id>.json` com
+   `status:"running"`, `startedAt`, e um `currentStep` curto; marque `state.json.status="running"`.
+2. **Onda paralela**: spawne todos os nós da onda **numa única mensagem com múltiplas
+   chamadas Task**, para rodarem concorrentemente. Dê a cada subagente APENAS o contrato
+   compilado + objetivo — nunca a conversa inteira.
+3. **Ao retornar**: marque cada `workers/<id>.json` com `status:"done"` (ou `"blocked"`),
+   `finishedAt`, e `verdict` se houver (reviewer/tester/integrator).
+4. **Próxima onda**: spawne os nós cujas dependências agora estão satisfeitas. Repita.
+5. **Ao final**: `state.json.status="done"` (ou `"blocked"` se algum bloqueou).
 
 Use os templates de arquétipo em `agents/` (implementer, reviewer, integrator, tester…)
 como enquadramento de cada subagente, preenchidos com objetivo, repositório e contrato.

package/templates/dashboard/index.html

@@ -0,0 +1,123 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Context-First Agents — Dashboard</title>
+<style>
+  :root {
+    --bg: #0d1117; --panel: #161b22; --border: #30363d; --text: #e6edf3;
+    --muted: #8b949e; --accent: #58a6ff;
+    --pending: #6e7681; --running: #d29922; --done: #3fb950; --blocked: #f85149;
+  }
+  * { box-sizing: border-box; }
+  body { margin: 0; background: var(--bg); color: var(--text);
+    font: 14px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; }
+  header { padding: 16px 24px; border-bottom: 1px solid var(--border);
+    display: flex; align-items: center; gap: 16px; position: sticky; top: 0; background: var(--bg); z-index: 5; }
+  header h1 { font-size: 16px; margin: 0; font-weight: 600; }
+  header .project { color: var(--accent); }
+  header .meta { margin-left: auto; color: var(--muted); font-size: 12px; }
+  .wrap { padding: 24px; max-width: 1100px; margin: 0 auto; display: grid; gap: 20px; }
+  .session { background: var(--panel); border: 1px solid var(--border); border-radius: 10px; overflow: hidden; }
+  .session > .head { padding: 14px 18px; display: flex; align-items: center; gap: 12px; cursor: pointer; }
+  .session .id { font-weight: 700; }
+  .session .title { color: var(--muted); }
+  .chip { font-size: 11px; padding: 2px 8px; border-radius: 20px; border: 1px solid var(--border); text-transform: uppercase; letter-spacing: .04em; }
+  .chip.simple { color: #3fb950; } .chip.medium { color: #d29922; } .chip.complex { color: #f85149; }
+  .status-dot { width: 9px; height: 9px; border-radius: 50%; display: inline-block; }
+  .s-planned { background: var(--pending); } .s-pending { background: var(--pending); }
+  .s-running { background: var(--running); box-shadow: 0 0 0 3px rgba(210,153,34,.2); animation: pulse 1.4s infinite; }
+  .s-done { background: var(--done); } .s-blocked { background: var(--blocked); } .s-unknown { background: #484f58; }
+  @keyframes pulse { 0%,100% { opacity: 1 } 50% { opacity: .4 } }
+  .agents { padding: 6px 18px 18px; display: grid; gap: 10px; }
+  .wave-label { font-size: 11px; color: var(--muted); text-transform: uppercase; letter-spacing: .06em; margin-top: 8px; }
+  .agent { border: 1px solid var(--border); border-radius: 8px; padding: 10px 12px; display: grid;
+    grid-template-columns: auto 1fr auto; gap: 10px; align-items: start; }
+  .agent .arch { font-size: 12px; color: var(--accent); font-weight: 600; }
+  .agent .obj { color: var(--muted); font-size: 13px; }
+  .agent .step { color: var(--running); font-size: 12px; margin-top: 2px; }
+  .agent .repo { font-size: 11px; color: var(--muted); }
+  .agent .verdict { font-size: 11px; font-weight: 700; padding: 2px 6px; border-radius: 4px; border: 1px solid var(--border); }
+  .deps { font-size: 11px; color: var(--muted); }
+  .empty { color: var(--muted); padding: 40px; text-align: center; }
+  .fallback { font-size: 11px; color: var(--running); margin-left: 8px; }
+  a { color: var(--accent); }
+</style>
+</head>
+<body>
+<header>
+  <h1>Context-First Agents · <span class="project" id="project">…</span></h1>
+  <div class="meta"><span id="count">0</span> sessions · auto-refresh <span id="tick">2s</span></div>
+</header>
+<div class="wrap" id="root"><div class="empty">Loading…</div></div>
+
+<script>
+const ARCH_ORDER = { implementer: 0, integrator: 1, reviewer: 2, tester: 3 };
+const el = (tag, cls, html) => { const e = document.createElement(tag); if (cls) e.className = cls; if (html != null) e.innerHTML = html; return e; };
+const esc = (s) => (s ?? '').replace(/[&<>]/g, c => ({ '&':'&amp;','<':'&lt;','>':'&gt;' }[c]));
+
+function agentCard(w) {
+  const card = el('div', 'agent');
+  const dot = el('div', 'status-dot s-' + (w.status || 'unknown'));
+  dot.title = w.status || 'unknown';
+  const mid = el('div');
+  mid.appendChild(el('div', 'arch', esc((w.id ? w.id + ' · ' : '') + (w.archetype || ''))));
+  if (w.objective) mid.appendChild(el('div', 'obj', esc(w.objective)));
+  if (w.currentStep && w.status === 'running') mid.appendChild(el('div', 'step', '▸ ' + esc(w.currentStep)));
+  if (w.dependsOn && w.dependsOn.length) mid.appendChild(el('div', 'deps', 'depends on ' + esc(w.dependsOn.join(', '))));
+  const right = el('div');
+  if (w.repository) right.appendChild(el('div', 'repo', esc(w.repository)));
+  if (w.verdict) { const v = el('div', 'verdict', esc(w.verdict)); v.style.color = /pass|green|consistent|done/i.test(w.verdict) ? 'var(--done)' : 'var(--blocked)'; right.appendChild(v); }
+  card.append(dot, mid, right);
+  return card;
+}
+
+function sessionCard(s) {
+  const box = el('div', 'session');
+  const head = el('div', 'head');
+  head.appendChild(el('span', 'status-dot s-' + (s.status || 'unknown')));
+  head.appendChild(el('span', 'id', esc(s.issueId)));
+  if (s.title) head.appendChild(el('span', 'title', esc(s.title)));
+  if (s.complexity) head.appendChild(el('span', 'chip ' + s.complexity, esc(s.complexity)));
+  if (s.fromPlanFallback) head.appendChild(el('span', 'fallback', '(no live state — from plan)'));
+  box.appendChild(head);
+
+  const agents = el('div', 'agents');
+  const byId = Object.fromEntries((s.workers || []).map(w => [w.id, w]));
+  const waves = s.waves && s.waves.length ? s.waves : null;
+  if (waves) {
+    waves.forEach((wave, i) => {
+      agents.appendChild(el('div', 'wave-label', 'Wave ' + (i + 1)));
+      wave.forEach(id => agents.appendChild(agentCard(byId[id] || { id, status: 'unknown' })));
+    });
+  } else {
+    const sorted = (s.workers || []).slice().sort((a, b) => (ARCH_ORDER[a.archetype] ?? 9) - (ARCH_ORDER[b.archetype] ?? 9));
+    if (!sorted.length) agents.appendChild(el('div', 'empty', 'No workers recorded yet.'));
+    sorted.forEach(w => agents.appendChild(agentCard(w)));
+  }
+  box.appendChild(agents);
+  return box;
+}
+
+async function refresh() {
+  try {
+    const res = await fetch('/api/sessions');
+    const data = await res.json();
+    document.getElementById('project').textContent = data.project || 'orchestrator';
+    document.getElementById('count').textContent = (data.sessions || []).length;
+    const root = document.getElementById('root');
+    root.innerHTML = '';
+    if (!data.sessions || !data.sessions.length) { root.appendChild(el('div', 'empty', 'No sessions yet. Run <code>/orchestrate &lt;ISSUE-ID&gt;</code>.')); return; }
+    // Most recently updated first
+    data.sessions.sort((a, b) => (b.updatedAt || b.createdAt || '').localeCompare(a.updatedAt || a.createdAt || ''));
+    data.sessions.forEach(s => root.appendChild(sessionCard(s)));
+  } catch (e) {
+    document.getElementById('root').innerHTML = '<div class="empty">Server unreachable. Is <code>context-agents dashboard</code> running?</div>';
+  }
+}
+refresh();
+setInterval(refresh, 2000);
+</script>
+</body>
+</html>

package/templates/orchestrator/SESSION-STATE.md

@@ -0,0 +1,65 @@
+# Session State Schema
+
+The `/orchestrate` command writes machine-readable state into each session directory so
+tools (like `context-agents dashboard`) can render live progress. Human-readable
+`execution-plan.md` stays alongside.
+
+```
+.sessions/<ISSUE-ID>/
+├── execution-plan.md      # human-readable (prose)
+├── state.json             # session-level state
+└── workers/
+    ├── W1.json            # one file per agent/worker
+    ├── W2.json
+    └── ...
+```
+
+## `state.json`
+
+```json
+{
+  "issueId": "ISSUE-42",
+  "title": "Example feature",
+  "complexity": "medium",
+  "status": "running",
+  "createdAt": "2026-09-13T12:10:00Z",
+  "updatedAt": "2026-09-13T12:15:00Z",
+  "repos": ["client-b"],
+  "waves": [["W1", "W2"], ["W3"], ["W4"], ["W5"]]
+}
+```
+
+- `status`: `planned` | `running` | `blocked` | `done`.
+- `waves`: array of arrays of worker ids, in execution order.
+
+## `workers/<id>.json`
+
+```json
+{
+  "id": "W1",
+  "archetype": "implementer",
+  "repository": "client-b",
+  "objective": "Audio pipeline: mic+tab capture, FFT bands/RMS/onset",
+  "dependsOn": [],
+  "status": "running",
+  "currentStep": "implementing FFT analyser",
+  "startedAt": "2026-09-13T12:11:00Z",
+  "finishedAt": null,
+  "verdict": null
+}
+```
+
+- `status`: `pending` | `running` | `done` | `blocked`.
+- `verdict` (optional): for reviewer/tester/integrator, e.g. `PASS` | `BLOCKED` |
+  `GREEN` | `RED` | `CONSISTENT` | `MISMATCH`.
+
+## Update protocol (for `/orchestrate`)
+
+1. Right after the graph is approved: write `state.json` (`status: "planned"`) and one
+   `workers/<id>.json` per node (`status: "pending"`).
+2. When a wave starts: set each of its workers to `running` + a short `currentStep`;
+   set `state.json.status = "running"`.
+3. When a worker returns: set `done` (or `blocked`), `finishedAt`, and `verdict` if any.
+4. When all workers finish: set `state.json.status = "done"` (or `blocked` if any blocked).
+
+Keep writes small and frequent — the dashboard polls these files.