opencastle 0.17.0 → 0.19.0

package/src/dashboard/src/pages/index.astro

@@ -26,6 +26,7 @@ const base = import.meta.env.BASE_URL;
     <!-- Sidebar Navigation -->
     <nav class="dash-sidebar" id="dash-sidebar">
       <ul class="dash-sidebar__list">
+        <li><a class="dash-sidebar__link" href="#convoy-section" data-section="convoy-section">Convoy</a></li>
         <li><a class="dash-sidebar__link dash-sidebar__link--active" href="#kpi-row" data-section="kpi-row">Overview</a></li>
         <li><a class="dash-sidebar__link" href="#pipeline-section" data-section="pipeline-section">Pipeline</a></li>
         <li><a class="dash-sidebar__link" href="#agent-section" data-section="agent-section">Agents</a></li>
@@ -66,9 +67,25 @@ const base = import.meta.env.BASE_URL;
           <option value="failed">Failed</option>
         </select>
       </div>
+      <div class="filter-group">
+        <label class="filter-label" for="filter-convoy">Convoy</label>
+        <select class="filter-select" id="filter-convoy">
+          <option value="">All convoys</option>
+        </select>
+      </div>
       <button class="dash-btn dash-btn--ghost filter-reset" id="filter-reset" type="button">Reset</button>
     </div>
 
+    <!-- Convoy Status Section -->
+    <section class="chart-card convoy-status" id="convoy-section" data-nav-section style="display:none">
+      <div class="chart-card__header">
+        <h2 class="chart-card__title">Convoy Status</h2>
+        <p class="chart-card__desc" id="convoy-desc">Select a convoy to view details</p>
+      </div>
+      <div class="chart-card__body" id="convoy-body">
+      </div>
+    </section>
+
     <!-- KPI Row -->
     <section class="kpi-row" id="kpi-row" data-nav-section>
       <div class="kpi-card" id="kpi-sessions">
@@ -1154,12 +1171,14 @@ const base = import.meta.env.BASE_URL;
   let rawDelegations = [];
   let rawPanels = [];
   let rawReviews = [];
+  let rawConvoys = [];
 
   function applyFilters() {
     const dateFrom = document.getElementById('filter-date-from').value;
     const dateTo = document.getElementById('filter-date-to').value;
     const agentFilter = document.getElementById('filter-agent').value;
     const outcomeFilter = document.getElementById('filter-outcome').value;
+    const convoyFilter = document.getElementById('filter-convoy').value;
 
     function matchDate(ts) {
       const date = ts.slice(0, 10);
@@ -1168,27 +1187,43 @@ const base = import.meta.env.BASE_URL;
       return true;
     }
 
-    const sessions = rawSessions.filter((s) => {
+    let sessions = rawSessions.filter((s) => {
       if (!matchDate(s.timestamp)) return false;
       if (agentFilter && s.agent !== agentFilter) return false;
       if (outcomeFilter && s.outcome !== outcomeFilter) return false;
       return true;
     });
 
-    const delegations = rawDelegations.filter((d) => {
+    let delegations = rawDelegations.filter((d) => {
       if (!matchDate(d.timestamp)) return false;
       if (agentFilter && d.agent !== agentFilter) return false;
       if (outcomeFilter && d.outcome !== outcomeFilter) return false;
       return true;
     });
 
-    const panels = rawPanels.filter((p) => matchDate(p.timestamp));
-    const reviews = rawReviews.filter((r) => {
+    let panels = rawPanels.filter((p) => matchDate(p.timestamp));
+    let reviews = rawReviews.filter((r) => {
       if (!matchDate(r.timestamp)) return false;
       if (agentFilter && r.agent !== agentFilter) return false;
       return true;
     });
 
+    if (convoyFilter) {
+      sessions = sessions.filter((s) => s.convoy_id === convoyFilter);
+      delegations = delegations.filter((d) => d.convoy_id === convoyFilter);
+      panels = panels.filter((p) => p.convoy_id === convoyFilter);
+      reviews = reviews.filter((r) => r.convoy_id === convoyFilter);
+    }
+
+    const convoySection = document.getElementById('convoy-section');
+    if (convoySection) {
+      convoySection.style.display = convoyFilter ? '' : 'none';
+      if (convoyFilter) {
+        const convoy = rawConvoys.find((c) => c.id === convoyFilter);
+        renderConvoyStatus(convoy);
+      }
+    }
+
     renderAll(sessions, delegations, panels, reviews);
   }
 
@@ -1300,8 +1335,80 @@ const base = import.meta.env.BASE_URL;
     URL.revokeObjectURL(url);
   }
 
+  function populateConvoyFilter(convoys) {
+    const select = document.getElementById('filter-convoy');
+    if (!select) return;
+    while (select.options.length > 1) select.remove(1);
+    const sorted = convoys.slice().sort((a, b) => b.created_at.localeCompare(a.created_at));
+    sorted.forEach((c) => {
+      const opt = document.createElement('option');
+      opt.value = c.id;
+      opt.textContent = c.name + ' (' + c.status + ')';
+      select.appendChild(opt);
+    });
+  }
+
+  function renderConvoyStatus(convoy) {
+    const descEl = document.getElementById('convoy-desc');
+    const bodyEl = document.getElementById('convoy-body');
+    if (!descEl || !bodyEl) return;
+
+    if (!convoy) {
+      bodyEl.innerHTML = emptyStateHtml('pipeline', 'Convoy not found', 'No matching convoy data available.');
+      return;
+    }
+
+    descEl.textContent = convoy.name + ' — ' + (convoy.branch || 'no branch');
+
+    const s = convoy.summary || {};
+    const total = s.total || (convoy.tasks ? convoy.tasks.length : 0);
+    const done = s.done || 0;
+    const pct = total > 0 ? Math.round((done / total) * 100) : 0;
+
+    const statusClass = convoy.status === 'done' ? 'success'
+      : (convoy.status === 'failed' || convoy.status === 'gate-failed') ? 'failed'
+      : convoy.status === 'running' ? 'partial' : '';
+
+    let html = '';
+    html += '<div class="convoy-overview">';
+    html += '<div class="convoy-stat"><span class="convoy-stat__label">Status</span><span class="outcome-badge outcome-badge--' + statusClass + '">' + escapeHtml(convoy.status) + '</span></div>';
+    html += '<div class="convoy-stat"><span class="convoy-stat__label">Branch</span><span class="convoy-stat__value">' + escapeHtml(convoy.branch || '\u2014') + '</span></div>';
+    html += '<div class="convoy-stat"><span class="convoy-stat__label">Tasks</span><span class="convoy-stat__value">' + done + '/' + total + '</span></div>';
+    html += '<div class="convoy-stat"><span class="convoy-stat__label">Events</span><span class="convoy-stat__value">' + (convoy.events_count || 0) + '</span></div>';
+    html += '<div class="convoy-stat"><span class="convoy-stat__label">Started</span><span class="convoy-stat__value">' + (convoy.started_at ? formatTime(convoy.started_at) : '\u2014') + '</span></div>';
+    html += '</div>';
+
+    html += '<div class="convoy-progress">';
+    html += '<div class="convoy-progress__bar"><div class="convoy-progress__fill" style="width:' + pct + '%"></div></div>';
+    html += '<span class="convoy-progress__label">' + pct + '% complete</span>';
+    html += '</div>';
+
+    if (convoy.tasks && convoy.tasks.length > 0) {
+      html += '<table class="sessions-table convoy-tasks">';
+      html += '<thead><tr><th>Task</th><th>Phase</th><th>Agent</th><th>Adapter</th><th>Status</th><th>Retries</th></tr></thead>';
+      html += '<tbody>';
+      convoy.tasks.forEach(function(t) {
+        const tStatus = t.status === 'done' ? 'success'
+          : (t.status === 'failed' || t.status === 'timed-out') ? 'failed'
+          : t.status === 'running' ? 'partial' : '';
+        html += '<tr>';
+        html += '<td>' + escapeHtml(t.id) + '</td>';
+        html += '<td class="td-num">' + t.phase + '</td>';
+        html += '<td class="td-agent">' + escapeHtml(t.agent) + '</td>';
+        html += '<td>' + escapeHtml(t.adapter || '\u2014') + '</td>';
+        html += '<td><span class="outcome-badge outcome-badge--' + tStatus + '">' + escapeHtml(t.status) + '</span></td>';
+        html += '<td class="td-num">' + (t.retries || 0) + '</td>';
+        html += '</tr>';
+      });
+      html += '</tbody></table>';
+    }
+
+    bodyEl.innerHTML = html;
+  }
+
   async function main() {
     const events = await loadNdjson(base + 'data/events.ndjson');
+    const convoys = await loadNdjson(base + 'data/convoys.ndjson');
 
     const sessions = events.filter((e) => e.type === 'session');
     const delegations = events.filter((e) => e.type === 'delegation');
@@ -1312,23 +1419,72 @@ const base = import.meta.env.BASE_URL;
     rawDelegations = delegations;
     rawPanels = panels;
     rawReviews = reviews;
+    rawConvoys = convoys;
 
     populateAgentFilter(sessions, delegations, reviews);
+    populateConvoyFilter(convoys);
+
+    // ── Read URL params ───────────────────────────────────
+    const urlParams = new URLSearchParams(window.location.search);
+    const convoyParam = urlParams.get('convoy');
+    if (convoyParam === 'active') {
+      const running = rawConvoys.find((c) => c.status === 'running');
+      const latest = rawConvoys.slice().sort((a, b) => b.created_at.localeCompare(a.created_at))[0];
+      const target = running || latest;
+      if (target) {
+        const sel = document.getElementById('filter-convoy');
+        if (sel) sel.value = target.id;
+      }
+    } else if (convoyParam) {
+      const sel = document.getElementById('filter-convoy');
+      if (sel) sel.value = convoyParam;
+    }
+
     renderAll(sessions, delegations, panels, reviews);
 
+    // Apply convoy param after initial render (shows convoy section if needed)
+    if (convoyParam) applyFilters();
+
     // ── Filter event listeners ────────────────────────────
     document.getElementById('filter-date-from')?.addEventListener('change', applyFilters);
     document.getElementById('filter-date-to')?.addEventListener('change', applyFilters);
     document.getElementById('filter-agent')?.addEventListener('change', applyFilters);
     document.getElementById('filter-outcome')?.addEventListener('change', applyFilters);
+    document.getElementById('filter-convoy')?.addEventListener('change', applyFilters);
     document.getElementById('filter-reset')?.addEventListener('click', () => {
       document.getElementById('filter-date-from').value = '';
       document.getElementById('filter-date-to').value = '';
       document.getElementById('filter-agent').value = '';
       document.getElementById('filter-outcome').value = '';
+      document.getElementById('filter-convoy').value = '';
       applyFilters();
     });
 
+    // ── Auto-refresh for live convoy monitoring ───────────
+    let refreshInterval = null;
+    function startAutoRefresh() {
+      if (refreshInterval) return;
+      refreshInterval = setInterval(async () => {
+        const freshEvents = await loadNdjson(base + 'data/events.ndjson');
+        const freshConvoys = await loadNdjson(base + 'data/convoys.ndjson');
+        rawSessions = freshEvents.filter((e) => e.type === 'session');
+        rawDelegations = freshEvents.filter((e) => e.type === 'delegation');
+        rawPanels = freshEvents.filter((e) => e.type === 'panel');
+        rawReviews = freshEvents.filter((e) => e.type === 'review');
+        rawConvoys = freshConvoys;
+        const currentValue = document.getElementById('filter-convoy')?.value;
+        populateConvoyFilter(freshConvoys);
+        const sel = document.getElementById('filter-convoy');
+        if (sel && currentValue) sel.value = currentValue;
+        applyFilters();
+      }, 5000);
+    }
+
+    const selectedConvoy = rawConvoys.find((c) => c.id === document.getElementById('filter-convoy')?.value);
+    if (convoyParam === 'active' || (selectedConvoy && selectedConvoy.status === 'running')) {
+      startAutoRefresh();
+    }
+
     // ── Export button ─────────────────────────────────────
     document.getElementById('export-btn')?.addEventListener('click', exportData);
 

package/src/dashboard/src/styles/dashboard.css

@@ -1533,3 +1533,63 @@ body {
     padding: 8px 6px;
   }
 }
+
+/* ---------- Convoy Section ---------- */
+.convoy-overview {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 24px;
+  margin-bottom: 20px;
+}
+
+.convoy-stat {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.convoy-stat__label {
+  font-size: 0.75rem;
+  color: var(--text-tertiary);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+.convoy-stat__value {
+  font-size: 0.95rem;
+  color: var(--text-primary);
+}
+
+/* Progress bar */
+.convoy-progress {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  margin-bottom: 20px;
+}
+
+.convoy-progress__bar {
+  flex: 1;
+  height: 8px;
+  background: var(--bg-tertiary);
+  border-radius: 4px;
+  overflow: hidden;
+}
+
+.convoy-progress__fill {
+  height: 100%;
+  background: var(--gradient-accent);
+  border-radius: 4px;
+  transition: width var(--transition-base);
+}
+
+.convoy-progress__label {
+  font-size: 0.8rem;
+  color: var(--text-secondary);
+  white-space: nowrap;
+}
+
+/* Task table inherits .sessions-table styles */
+.convoy-tasks {
+  margin-top: 8px;
+}

package/src/orchestrator/agents/session-guard.agent.md

@@ -72,6 +72,20 @@ If the session summary mentions fast reviews or panel reviews, verify matching r
 
 Only flag if the session produced code changes that should have been committed. Research-only or analysis sessions may not produce commits.
 
+### 7. Convoy Observability (if convoy was executed)
+
+If the session involved running a convoy (check for `.opencastle/convoy.db` or references to convoy execution in the session summary):
+
+**Verify convoy NDJSON export:**
+- `cat .opencastle/logs/convoys.ndjson | tail -1` should show the latest convoy record
+- Record should have `status: done` or `status: failed` (not `running`)
+
+**Verify convoy tasks logged:**
+- Each completed convoy task should have a corresponding event in the NDJSON log
+- Check: `grep '"type":"session"' .github/customizations/logs/events.ndjson | tail -10`
+
+**Fix:** If convoy export is missing, the engine should have auto-exported. Manual export: run `opencastle run --status` to verify the convoy completed.
+
 ## Output
 
 Return a structured report:

package/src/orchestrator/agents/team-lead.agent.md

@@ -17,9 +17,12 @@ handoffs:
   - label: Quick Refinement
     agent: 'Team Lead (OpenCastle)'
     prompt: 'Use the quick-refinement prompt to handle these follow-up refinements (UI tweaks, polish, adjustments):'
-  - label: Generate Convoy Spec
+  - label: Generate Convoy
     agent: 'Team Lead (OpenCastle)'
-    prompt: 'Use the generate-task-spec prompt to create a .convoy.yml spec for autonomous convoy runs based on:'
+    prompt: 'Use the generate-convoy prompt to create a .convoy.yml spec for autonomous convoy execution based on:'
+  - label: Run Convoy
+    agent: 'Team Lead (OpenCastle)'
+    prompt: 'Run an existing .convoy.yml spec file. Parse the spec, validate the DAG, and execute via the convoy engine:'
   - label: Resolve PR Comments
     agent: 'Team Lead (OpenCastle)'
     prompt: 'Use the resolve-pr-comments prompt to resolve the GitHub PR review comments on this PR:'
@@ -135,6 +138,46 @@ See the **team-lead-reference** skill for model tiers, token estimates, duration
 
 Before EVERY delegation verify: (1) Tracker issue exists, (2) File partition is clean, (3) Dependencies verified Done, (4) Prompt includes file paths + acceptance criteria, (5) Self-improvement reminder included.
 
+## Convoy Integration
+
+The convoy engine is the preferred execution mechanism for multi-task work. Use it when a request decomposes into 3 or more subtasks.
+
+### When to use convoy vs. direct delegation
+
+| Task count | Approach |
+|------------|----------|
+| 1–2 subtasks | **Direct delegation** — sub-agents inline, standard workflow |
+| 3+ subtasks | **Convoy execution** — generate spec, hand to user to run |
+
+### How to generate a convoy spec
+
+1. Decompose the request into tasks as normal (Steps 1–2)
+2. Use the `generate-convoy` prompt with the decomposed task list as context
+3. The `generate-convoy` prompt produces a valid `.convoy.yml` spec with DAG, agents, file scopes, and gates
+
+### How to execute a convoy
+
+Tell the user to run:
+```
+npx opencastle run -f <name>.convoy.yml
+```
+This gives the user control over when execution starts (preferred — supports overnight/unattended runs and manual review of the spec before execution).
+
+### After convoy completes
+
+1. Run all validation gates (lint, test, build) on the convoy's output branch
+2. Open a PR from the convoy's configured `branch` — do NOT merge
+3. Link the PR in the tracker issue
+4. Log the session record as usual
+
+### What the convoy engine handles automatically
+
+- **Isolated git worktrees** per task — parallel agents never touch the same files
+- **Parallel execution** with configurable concurrency
+- **Merge queue ordering** — respects `depends_on` DAG when merging worktrees
+- **Crash recovery** — `opencastle run --resume` continues from last checkpoint
+- **Progress monitoring** — `opencastle run --status` shows live task state
+
 ## Workflow
 
 ### Step 1: Understand

package/src/orchestrator/prompts/bootstrap-customizations.prompt.md

@@ -270,7 +270,7 @@ Now that your project is configured, here's what you can do:
 3. **Implement a feature** — Use the **"Implement Feature"** prompt to have the Team Lead orchestrate a full feature build with task tracking, delegation, and verification
 4. **Fix a bug** — Use the **"Bug Fix"** prompt for structured triage, root cause analysis, and fix with tracker tracking
 5. **Brainstorm first** — Not sure how to approach something? Use the **"Brainstorm"** prompt to explore requirements and trade-offs before committing to a plan
-6. **Create a task spec** — Use the **"Generate Task Spec"** prompt to create `opencastle.tasks.yml` for autonomous overnight runs with `npx opencastle run` CLI command.
+6. **Generate a convoy spec** — Use the **"Generate Convoy"** prompt to create a `.convoy.yml` spec for autonomous convoy execution with `npx opencastle run` CLI command.
 
 ## Guidelines
 

package/src/orchestrator/prompts/brainstorm.prompt.md

@@ -107,11 +107,12 @@ Not every task needs a brainstorm. Skip this prompt and go directly to `implemen
 - The task is a simple config change or docs update
 - The technical approach is obvious and unambiguous
 - The scope is a single file or component with no design decisions
+- The task is well-understood and can be expressed as a convoy spec directly → use `generate-convoy` instead
 
 ## After Brainstorming
 
 Once the brainstorm is complete and the user confirms (or you're confident in the approach):
 
-1. **Transition to planning** — use the brainstorm report as input for `implement-feature` or the appropriate workflow
+1. **Transition to planning** — use the brainstorm report as input for `implement-feature` (which will choose between direct delegation and convoy execution based on task count)
 2. **Preserve context** — include the brainstorm report in delegation prompts so agents understand *why* an approach was chosen
 3. **Reference in tracker** — link the brainstorm findings in the tracker issue description

package/src/orchestrator/prompts/{generate-task-spec.prompt.md → generate-convoy.prompt.md}

@@ -1,13 +1,13 @@
 ---
-description: 'Generate a valid .convoy.yml spec file for autonomous convoy runs based on a high-level description of what needs to be done.'
+description: 'Generate a .convoy.yml spec file for autonomous convoy execution based on a high-level goal.'
 agent: 'Team Lead (OpenCastle)'
 ---
 
 <!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .github/customizations/ directory instead. -->
 
-# Generate Task Spec for Autonomous Run
+# Generate Convoy Spec
 
-You are the Team Lead. The user wants to run `opencastle run` to execute a batch of tasks autonomously (e.g., overnight). Your job is to produce a valid `.convoy.yml` file they can feed to the CLI. Derive a short, descriptive, kebab-case filename from the user's goal (2–4 words max) and use it as the filename — for example `auth-refactor.convoy.yml` or `add-search.convoy.yml`. Always use the `.convoy.yml` extension.
+You are the Team Lead. The user wants to run `opencastle run` to execute a batch of tasks autonomously via the convoy engine. Your job is to produce a valid `.convoy.yml` file they can feed to the CLI. Derive a short, descriptive, kebab-case filename from the user's goal (2–4 words max) and use it as the filename — for example `auth-refactor.convoy.yml` or `add-search.convoy.yml`. Always use the `.convoy.yml` extension.
 
 ## User Goal
 
@@ -174,4 +174,4 @@ Also provide:
 2. An **estimated total duration** (sum of timeouts on the critical path).
 3. A `--dry-run` command they can use to validate: `npx opencastle run --file <feature-name>.convoy.yml --dry-run`
 
-> **Backward compatibility:** `.tasks.yml` files without `version` still work with the legacy executor. Only spec files with `version: 1` are routed to the convoy engine.
+

package/src/orchestrator/prompts/implement-feature.prompt.md

@@ -45,10 +45,34 @@ Every subtask must be tracked. **No issue = no implementation.** This step produ
    - **Acceptance criteria:** Verifiable checklist
    - **Dependencies:** Links to prerequisite issues
 5. **Link to roadmap** — Reference the roadmap section in the issue description so context is never lost
-6. **Verify issues exist** — List all created issue IDs. If count is 0, do NOT proceed to Step 3
+6. **Verify issues exist** — List all created issue IDs. If count is 0, do NOT proceed to Step 2.5
+
+### 2.5 Choose Execution Path (BLOCKING — decides how Step 3 proceeds)
+
+With the full task list in hand, decide the execution mechanism:
+
+| Condition | Execution path |
+|-----------|----------------|
+| 1–2 subtasks | **Direct delegation** — delegate to sub-agents as today (proceed to Step 3 as-is) |
+| 3+ subtasks | **Convoy execution** — generate a `.convoy.yml` spec using the `generate-convoy` prompt, then hand it to the user |
+
+#### Direct delegation (1–2 subtasks)
+
+Proceed with the normal Step 3 delegation workflow. Sub-agents handle each task inline.
+
+#### Convoy execution (3+ subtasks)
+
+1. **Generate the spec** — use the `generate-convoy` prompt with the decomposed task list as context. The spec IS the implementation plan — no manual per-task delegation is needed.
+2. **Hand the spec to the user** — tell them to run: `npx opencastle run -f <name>.convoy.yml`
+3. **The convoy engine handles** isolated git worktrees, parallel execution, merge queue ordering, and crash recovery automatically.
+4. **After convoy completes** — proceed to Step 4 (validation) and Step 5 (delivery/PR). The convoy engine will have created its own commits on the configured branch.
+
+> **Why convoy for 3+ tasks?** Parallel worktree isolation prevents file conflicts. The merge queue ensures safe ordering. Crash recovery means a failing task doesn't block others. Manual delegation of 3+ parallel tasks risks conflicts and is harder to monitor.
 
 ### 3. Implementation Rules
 
+> **For convoy execution (3+ subtasks):** The convoy spec file IS the implementation plan — skip the manual delegation workflow below and jump to Step 4 after the user runs the convoy. The convoy engine delegates tasks internally using the agents and prompts defined in the spec.
+
 #### Issue Traceability
 
 - **Pass issue ID to every agent** — When delegating a subtask (sub-agent or background), include the tracker issue ID and title in the prompt so the agent knows which tracked task it is completing
@@ -93,6 +117,8 @@ Every subtask must pass ALL gates before being marked Done:
 
 Follow the **Delivery Outcome** defined in the **git-workflow** skill — commit, push, open PR (not merged), and link to the tracker.
 
+> **For convoy execution:** The convoy engine creates commits on the configured `branch` directly. After validation passes, open the PR from that branch. No additional commits from the Team Lead are needed unless gates failed and required manual fixes.
+
 ### 6. Documentation & Traceability
 
 Keep documentation current so future sessions have full context:

package/src/orchestrator/prompts/quick-refinement.prompt.md

@@ -127,6 +127,8 @@ Stop the follow-up workflow and switch to a full roadmap task if:
 
 When escalating, explain to the user what you found and why it needs proper tracking.
 
+- **Multi-task escalation** — If the refinement decomposes into 3+ subtasks, switch to `implement-feature` (which will use convoy execution for multi-task work)
+
 ### 8. Completion
 
 The follow-up is complete when: