@polderlabs/bizar 8.1.0 → 9.0.0

package/.claude/worktrees/kanban-overhaul/bizar-dash/src/server/task-delegator.mjs

@@ -0,0 +1,969 @@
+/**
+ * src/server/task-delegator.mjs
+ *
+ * v6.3.0 — Odin task delegation, REWRITTEN for Claude Code.
+ *
+ * Accepts a single "natural language" task from the user. Splits it into
+ * 1-5 subtasks via heuristic rules (an LLM call would replace this in
+ * v3.3), assigns each subtask to the best-fit agent based on tags /
+ * keywords / category, and dispatches them to the background agent
+ * infrastructure when available.
+ *
+ * v3.5.1 — agents.maxParallel cap applied here. Background dispatch is
+ * limited to the configured number of concurrent instances; overflow
+ * subtasks are marked queued and dispatched as slots free up.
+ *
+ * The delegator is intentionally tolerant: a failure to enqueue a
+ * background instance must NOT break the user-facing task creation.
+ * Subtasks are always persisted to the regular tasks store first; the
+ * background dispatch is best-effort.
+ *
+ * v6.3.0 — Dispatch path replaced. The previous Cline path shell-executed
+ * `node plugins/bizar/dist/cli.js bg enqueue`, then `cline run` via
+ * cline-runner.mjs. Claude Code has no equivalent `serve` child — the
+ * new path spawns `claude -p "<prompt>"` per subtask via
+ * `claude-runner.mjs` (in-process when the SDK is available,
+ * subprocess otherwise). The dispatch is gated on `pingClaudeSdk()`
+ * (in-process SDK reachable) OR the `claude` binary on PATH.
+ *
+ * If neither is available we log a clear warning at startup AND
+ * surface the dispatch failure in the `/submit` response, so the
+ * user can re-dispatch manually with `/api/tasks/:id/start`
+ * once the runtime is up.
+ */
+
+import { tasksStore, ALLOWED_TASK_STATUSES } from './tasks-store.mjs';
+import { agentsStore } from './agents-store.mjs';
+import { notificationsStore } from './notifications-store.mjs';
+import { backgroundStore } from './background-store.mjs';
+import { projectsStore } from './projects-store.mjs';
+import { getActualBgLogPath } from './lib/path-safe.mjs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, statSync, renameSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { randomBytes } from 'node:crypto';
+
+const HOME = homedir();
+
+// Background state directory — defaults to what the cline plugin
+// actually uses (see plugins/bizar/src/background-state.ts: stateDir
+// defaults to `~/.cache/bizar` so instances live at
+// `~/.cache/bizar/bg/<instanceId>.json`).
+const BG_DIRS = [
+  join(HOME, '.cache', 'bizar', 'bg'),
+  join(HOME, '.config', 'cline', 'bg'),
+  join(HOME, '.bizar', 'bg'),
+];
+
+function genId(prefix) {
+  return `${prefix}_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`;
+}
+
+function genShortHex(bytes = 6) {
+  return randomBytes(bytes).toString('hex');
+}
+
+/**
+ * v3.5.4 — Synthesize the prompt text for a subtask. Combines the
+ * subtask title and description in the same shape the plugin's own
+ * `bizar_spawn_background` tool uses internally, so an cline agent
+ * receives the same brief whether it was dispatched via MCP or via
+ * the dashboard's HTTP bridge.
+ */
+function buildPromptText(sub) {
+  const parts = [];
+  parts.push(`# ${sub.title || 'Subtask'}`);
+  if (sub.description) parts.push(String(sub.description).trim());
+  parts.push('');
+  parts.push('---');
+  parts.push(`Subtask ID: ${sub.id}`);
+  parts.push(`Assigned agent: ${sub.assignee || 'tyr'}`);
+  parts.push(`Parent task ID: ${sub.parent || '(none)'}`);
+  parts.push(`Runtime: Claude Code (claude -p)`);
+  return parts.join('\n');
+}
+
+/**
+ * v3.5.4 — Write a per-instance state file under BG_DIRS so the
+ * dashboard's `backgroundStore.list()` and `kill()` paths find this
+ * bg instance. The shape matches what `background-state.ts` writes
+ * so the existing merge + dedupe logic works without changes.
+ *
+ * Idempotent: writes are atomic via tmp + rename. Failures are logged
+ * but do NOT throw — the cline session is already running.
+ */
+function writeBgStateFile(instanceId, payload) {
+  const dir = pickBgDir();
+  try {
+    mkdirSync(dir, { recursive: true });
+  } catch (err) {
+    console.warn(`[task-delegator] cannot create bg dir ${dir}: ${err.message}`);
+    return null;
+  }
+  const file = join(dir, `${instanceId}.json`);
+  const tmp = `${file}.tmp`;
+  try {
+    writeFileSync(tmp, JSON.stringify(payload, null, 2), 'utf8');
+    try {
+      renameSync(tmp, file);
+    } catch {
+      writeFileSync(file, JSON.stringify(payload, null, 2), 'utf8');
+    }
+    return file;
+  } catch (err) {
+    console.warn(`[task-delegator] failed to write bg state file ${file}: ${err.message}`);
+    return null;
+  }
+}
+
+/**
+ * Read-only enumeration of bg state files for diagnostics / debug.
+ * Used by `dispatchToBackground` to pick a target state dir.
+ */
+function pickBgDir() {
+  for (const dir of BG_DIRS) {
+    if (existsSync(dir)) return dir;
+  }
+  return BG_DIRS[0];
+}
+
+/**
+ * v3.7.1 — Auto-generate a task title from a prompt body when the
+ * caller didn't supply one. Mirrors `autoTitleFromContent` in
+ * `src/web/lib/utils.ts`. Strips markdown headers, takes the first
+ * non-empty line, truncates to ~60 chars at a word boundary. Falls
+ * back to a timestamped placeholder if there's nothing to summarize.
+ */
+function autoTitleFromContent(body, fallback = true) {
+  const raw = (body || '').replace(/\r\n?/g, '\n').trim();
+  if (!raw) {
+    if (!fallback) return '';
+    const now = new Date();
+    const pad = (n) => String(n).padStart(2, '0');
+    return `Untitled task — ${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())} ${pad(now.getHours())}:${pad(now.getMinutes())}`;
+  }
+  const firstLine = raw
+    .split('\n')
+    .map((l) => l.replace(/^[\s>#*\-]+/, '').trim())
+    .find((l) => l.length > 0) || '';
+  if (!firstLine) {
+    if (!fallback) return '';
+    const now = new Date();
+    const pad = (n) => String(n).padStart(2, '0');
+    return `Untitled task — ${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())} ${pad(now.getHours())}:${pad(now.getMinutes())}`;
+  }
+  if (firstLine.length <= 60) return firstLine;
+  const cut = firstLine.slice(0, 60);
+  const lastSpace = cut.lastIndexOf(' ');
+  return (lastSpace > 20 ? cut.slice(0, lastSpace) : cut).trimEnd() + '…';
+}
+
+// v3.22 — Shared helper: count running + pending bg instances.
+async function runningBgCount() {
+  const list = await backgroundStore.list();
+  return list.filter((b) => b.status === 'running' || b.status === 'pending').length;
+}
+
+export const taskDelegator = {
+  /**
+   * Submit a task to Odin. Odin analyzes, splits, and dispatches.
+   *
+   * @param {object} taskInput - { title, description, priority?, tags? }
+   * @param {object} ctx - { projectRoot, projectId, broadcast }
+   * @returns {Promise<{ main, subtasks }>}
+   */
+  async submit(taskInput, ctx = {}) {
+    const broadcast = ctx.broadcast || (() => {});
+    const projectId = ctx.projectId || null;
+
+    // v3.7.1 — Title is now optional. Auto-generate from the description
+    // when the caller didn't supply one. Reject only when BOTH fields
+    // are empty (so curl/api callers without a description get a clear
+    // error).
+    const description = (taskInput.description || '').trim();
+    let title = (taskInput.title || '').trim();
+    if (!title && description) {
+      title = autoTitleFromContent(description);
+    }
+    if (!title) {
+      throw new Error('title or description is required');
+    }
+
+    // 1. Create the main task. Persisted via the regular store so it
+    //    shows up in /api/tasks and the UI immediately.
+    const main = await tasksStore.create(projectId, {
+      title,
+      description: taskInput.description || '',
+      status: 'queued',
+      priority: ['low', 'normal', 'high'].includes(taskInput.priority)
+        ? taskInput.priority
+        : 'normal',
+      tags: Array.isArray(taskInput.tags) ? taskInput.tags : [],
+      assignee: 'odin',
+      parent: null,
+      metadata: { progress: 0, currentStep: 'Queued for delegation', progressHistory: [{ ts: new Date().toISOString(), progress: 0, step: 'Queued for delegation' }] },
+    });
+    broadcast({ type: 'tasks:change', task: main });
+
+    // v3.3.0 — Drop a notification that the user submitted a task.
+    try {
+      notificationsStore.add({
+        severity: 'info',
+        source: 'odin',
+        title: 'Task submitted',
+        message: `Odin is splitting "${title}" into subtasks.`,
+        link: null,
+        meta: { taskId: main.id },
+      }, { broadcast });
+    } catch { /* best-effort */ }
+
+    // 2. Odin analyzes and splits.
+    const subtasks = await this.splitTask(main, ctx);
+
+    // 3. For each subtask, match an agent and persist the assignment.
+    const agents = agentsStore.list();
+    for (const sub of subtasks) {
+      const agent = this.matchAgent(sub, agents);
+      sub.assignee = agent.name;
+      const persisted = await tasksStore.update(projectId, sub.id, {
+        assignee: agent.name,
+      });
+      if (persisted) {
+        broadcast({ type: 'tasks:change', task: persisted });
+      }
+    }
+
+    // 4. Flip the main task to `doing` and record its subtasks.
+    main.subtasks = subtasks.map((s) => s.id);
+    const moved = await tasksStore.update(projectId, main.id, {
+      status: 'doing',
+      metadata: { progress: 10, currentStep: `Split into ${subtasks.length} subtask(s)`, startedAt: new Date().toISOString() },
+    });
+    if (moved) {
+      moved.subtasks = subtasks.map((s) => s.id);
+      broadcast({ type: 'tasks:change', task: moved });
+    }
+
+    // 5. Best-effort dispatch to background infrastructure. We collect
+    //    per-subtask errors instead of swallowing them so the response
+    //    includes `dispatchErrors[]`. The HTTP caller (and the UI toast)
+    //    can then surface "X subtasks could not be dispatched" instead
+    //    of a silent success.
+    const dispatchResult = { dispatched: [], errors: [], warnings: [] };
+    try {
+      const r = await this.dispatchToBackground(moved || main, subtasks, ctx, broadcast);
+      if (r && typeof r === 'object') {
+        if (Array.isArray(r.dispatched)) dispatchResult.dispatched = r.dispatched;
+        if (Array.isArray(r.errors)) dispatchResult.errors = r.errors;
+        if (Array.isArray(r.warnings)) dispatchResult.warnings = r.warnings;
+      }
+    } catch (err) {
+      console.error('[task-delegator] dispatch crashed:', err.message);
+      dispatchResult.errors.push({ kind: 'fatal', message: err.message || String(err) });
+    }
+
+    if (dispatchResult.errors.length > 0) {
+      try {
+        notificationsStore.add({
+          severity: 'warning',
+          source: 'odin',
+          title: 'Dispatch incomplete',
+          message: `${dispatchResult.errors.length} subtask(s) could not be dispatched. Use POST /api/tasks/:id/start to retry.`,
+          meta: { mainId: main.id, errors: dispatchResult.errors.slice(0, 5) },
+        }, { broadcast });
+      } catch { /* best-effort */ }
+    }
+
+    // 6. Audit activity.
+    try {
+      ctx.state?.appendActivity?.({
+        kind: 'task.delegated',
+        mainId: main.id,
+        subtasks: subtasks.map((s) => s.id),
+        title: main.title,
+      });
+      // Also write to the dashboard activity log so the Activity tab
+      // sees the delegation event.
+      try {
+        const { activityLog } = await import('./activity-log.mjs');
+        activityLog.append({
+          kind: 'task.delegated',
+          nodeId: `task:${main.id}`,
+          mainId: main.id,
+          subtaskIds: subtasks.map((s) => s.id),
+          title: main.title,
+        });
+      } catch { /* best-effort */ }
+    } catch {
+      /* best-effort */
+    }
+
+    return { main: moved || main, subtasks, dispatch: dispatchResult };
+  },
+
+  /**
+   * Split a task into 2-5 subtasks using heuristic rules.
+   * The split is intentionally conservative — when no signal matches
+   * the rule set we fall back to a single "do the work" subtask plus
+   * an optional "verify" subtask if the title hints at testing.
+   *
+   * @param {Task} main
+   * @param {object} ctx - { projectId, broadcast }
+   * @returns {Promise<Task[]>}
+   */
+  async splitTask(main, ctx = {}) {
+    const projectId = ctx.projectId || null;
+    const broadcast = ctx.broadcast || (() => {});
+    const title = (main.title || '').toLowerCase();
+    const desc = (main.description || '').toLowerCase();
+    const text = `${title} ${desc}`;
+
+    const wantImpl = /\b(implement|build|create|add|write|develop|craft|code|ship)\b/.test(text);
+    const wantTest = /\b(test|verify|validate|check|qa|cover|spec)\b/.test(text);
+    const wantDocs = /\b(document|readme|docs|comment|explain|write[- ]up)\b/.test(text);
+    const wantDesign = /\b(design|ui|ux|style|styling|theme|visual|layout|mockup)\b/.test(text);
+    const wantResearch = /\b(research|find|explore|investigate|compare|survey|analyze)\b/.test(text);
+    const wantRefactor = /\b(refactor|rework|restructure|clean[- ]up|reorganize)\b/.test(text);
+
+    const fragments = [];
+
+    if (wantImpl || wantRefactor) {
+      fragments.push({
+        key: 'impl',
+        title: `Implement: ${main.title}`,
+        description: main.description
+          ? `Implement the core change. Source description:\n\n${main.description}`
+          : `Implement: ${main.title}`,
+        priority: main.priority || 'normal',
+        assigneeHint: wantRefactor ? 'tyr' : 'tyr',
+        tags: [...(main.tags || []), 'implementation'],
+      });
+    }
+    if (wantTest) {
+      fragments.push({
+        key: 'test',
+        title: `Test: ${main.title}`,
+        description: `Write tests and verify: ${main.title}`,
+        priority: 'normal',
+        assigneeHint: 'thor',
+        tags: [...(main.tags || []), 'testing'],
+      });
+    }
+    if (wantDocs) {
+      fragments.push({
+        key: 'docs',
+        title: `Document: ${main.title}`,
+        description: `Write documentation for: ${main.title}`,
+        priority: 'low',
+        assigneeHint: 'heimdall',
+        tags: [...(main.tags || []), 'docs'],
+      });
+    }
+    if (wantDesign) {
+      fragments.push({
+        key: 'design',
+        title: `Design: ${main.title}`,
+        description: `Design work for: ${main.title}`,
+        priority: main.priority || 'normal',
+        assigneeHint: 'baldr',
+        tags: [...(main.tags || []), 'design'],
+      });
+    }
+    if (wantResearch) {
+      fragments.push({
+        key: 'research',
+        title: `Research: ${main.title}`,
+        description: `Research and summarize: ${main.title}`,
+        priority: 'normal',
+        assigneeHint: 'mimir',
+        tags: [...(main.tags || []), 'research'],
+      });
+    }
+
+    // Fallback when nothing matched: a single "do it" subtask.
+    if (fragments.length === 0) {
+      fragments.push({
+        key: 'work',
+        title: `Work on: ${main.title}`,
+        description: main.description || main.title,
+        priority: main.priority || 'normal',
+        assigneeHint: 'tyr',
+        tags: [...(main.tags || [])],
+      });
+    }
+
+    // Hard cap at 5 subtasks — keep the board tidy.
+    const limited = fragments.slice(0, 5);
+
+    const subtasks = [];
+    for (const f of limited) {
+      const t = await tasksStore.create(projectId, {
+        title: f.title,
+        description: f.description,
+        status: 'queued',
+        priority: f.priority,
+        tags: f.tags,
+        assignee: f.assigneeHint,
+        parent: main.id,
+      });
+      broadcast({ type: 'tasks:change', task: t });
+      subtasks.push(t);
+    }
+    return subtasks;
+  },
+
+  /**
+   * Match a subtask to the best agent. Returns a fallback agent if
+   * nothing matches (never null).
+   */
+  matchAgent(task, agents) {
+    const text = `${task.title || ''} ${task.description || ''}`.toLowerCase();
+    const tags = (task.tags || []).map((t) => t.toLowerCase());
+
+    // Priority rules. First match wins. Order matters.
+    const rules = [
+      { match: ['git', 'commit', 'pr', 'merge', 'branch', 'push'], agent: 'hermod' },
+      { match: ['design', 'ui', 'ux', 'style', 'theme', 'visual', 'layout'], agent: 'baldr' },
+      { match: ['research', 'find', 'explore', 'search', 'investigate'], agent: 'mimir' },
+      { match: ['clarify', 'question', 'ask'], agent: 'vor' },
+      { match: ['explain', 'how', 'why'], agent: 'frigg' },
+      { match: ['test', 'verify', 'validate', 'check', 'qa'], agent: 'thor' },
+      { match: ['document', 'doc', 'readme'], agent: 'heimdall' },
+      { match: ['refactor', 'rework', 'restructure', 'cleanup'], agent: 'tyr' },
+      { match: ['implement', 'build', 'create', 'add', 'code', 'fix'], agent: 'tyr' },
+      { match: ['security', 'audit', 'review'], agent: 'forseti' },
+      { match: ['simple', 'quick', 'small', 'easy'], agent: 'heimdall' },
+      { match: ['complex', 'architect'], agent: 'tyr' },
+    ];
+
+    for (const rule of rules) {
+      const hit =
+        rule.match.some((m) => text.includes(m)) ||
+        rule.match.some((m) => tags.includes(m));
+      if (hit) {
+        const agent = agents.find((a) => a.name === rule.agent);
+        if (agent) return agent;
+      }
+    }
+
+    // Honor any explicit assignee stored on the task.
+    if (task.assignee) {
+      const found = agents.find((a) => a.name === task.assignee);
+      if (found) return found;
+    }
+
+    return agents.find((a) => a.name === 'tyr') || agents[0] || { name: 'tyr' };
+  },
+
+  /**
+   * v6.3.0 — Best-effort dispatch to the Claude Code runtime.
+   * Replaces the v3.5.4 Cline HTTP-serve path. Spawns one
+   * `claude -p "<prompt>"` subprocess per subtask via
+   * `claude-runner.mjs` (or, when the SDK is available,
+   * `claude-bg-spawner.mjs`'s SDK-backed path).
+   *
+   * The runner writes its output to the LogWriter's log file under
+   * `~/.cache/bizar/logs/<sessionId>.log`. The dashboard's
+   * `backgroundStore.list()` and `kill()` paths find the instance
+   * via the per-instance state file at
+   * `~/.cache/bizar/bg/<instanceId>.json`.
+   *
+   * Returns a structured `{ dispatched: string[], errors: Array<…>, warnings: Array<…> }`
+   * so the caller (and `/api/tasks/submit`) can surface failures to
+   * the user instead of swallowing them.
+   *
+   * v3.5.1 — Respects agents.maxParallel: caps concurrent dispatches
+   * to the configured limit; overflow subtasks are queued until a
+   * slot frees up.
+   *
+   * @returns {Promise<{ dispatched: string[], errors: Array<{ subtaskId: string, kind: string, message: string }>, warnings: string[] }>}
+   */
+  async dispatchToBackground(main, subtasks, ctx, broadcast) {
+    const projectRoot = ctx.projectRoot || process.cwd();
+    const projectId = ctx.projectId || null;
+    const bgDir = pickBgDir();
+    const result = { dispatched: [], errors: [], warnings: [] };
+
+    // v3.5.1 — Read agents.maxParallel from settings (default 6).
+    const SETTINGS_FILE = join(HOME, '.config', 'bizar', 'settings.json');
+    let maxParallel = 6;
+    try {
+      if (existsSync(SETTINGS_FILE)) {
+        const raw = readFileSync(SETTINGS_FILE, 'utf8');
+        const settings = JSON.parse(raw);
+        maxParallel = settings?.agents?.maxParallel ?? 6;
+      }
+    } catch {
+      maxParallel = 6;
+    }
+
+    // v3.22 — Reuse the shared runningBgCount helper.
+    const runningCount = await runningBgCount();
+    const slotsAvailable = Math.max(0, maxParallel - runningCount);
+
+    // v6.3.0 — Verify the Claude Code runtime is reachable. We
+    // accept either the in-process SDK or the `claude` binary on
+    // PATH. `pingClaudeSdk()` probes the SDK; `claude -v` on PATH
+    // is the subprocess fallback. When neither is available we
+    // mark subtasks as `dispatchPending: true` so the UI surfaces
+    // "Awaiting dispatch" and `/api/tasks/:id/start` can retry
+    // after the user installs Claude Code.
+    let claudeAvailable = false;
+    try {
+      const { pingClaudeSdk } = await import('./claude-sdk.mjs');
+      claudeAvailable = await pingClaudeSdk();
+    } catch {
+      claudeAvailable = false;
+    }
+    if (!claudeAvailable) {
+      try {
+        const { spawnSync } = await import('node:child_process');
+        const probe = spawnSync('claude', ['-v'], { stdio: 'ignore', timeout: 1500 });
+        claudeAvailable = probe.status === 0;
+      } catch {
+        claudeAvailable = false;
+      }
+    }
+    if (!claudeAvailable) {
+      result.warnings.push('claude runtime not reachable — neither the @anthropic-ai/claude-agent-sdk nor the `claude` binary on PATH. Tasks will be marked queued; retry via POST /api/tasks/:id/start once Claude Code is installed.');
+      console.warn('[task-delegator] claude runtime unreachable — dispatch will be deferred.');
+    }
+
+    // Split: first N get dispatched now, rest are queued.
+    const toDispatch = subtasks.slice(0, slotsAvailable);
+    const toQueue = subtasks.slice(slotsAvailable);
+
+    for (const sub of toQueue) {
+      const metadata = {
+        ...(sub.metadata || {}),
+        waitingForSlot: true,
+        queuedAt: new Date().toISOString(),
+        maxParallel,
+      };
+      await tasksStore.update(projectId, sub.id, {
+        status: 'queued',
+        metadata,
+      });
+      broadcast({
+        type: 'tasks:change',
+        task: { id: sub.id, status: 'queued', metadata },
+      });
+    }
+
+    // v6.3.0 — Per-subtask dispatch path. We collect errors instead
+    // of swallowing them. Two failure modes:
+    //   - claudeAvailable=false: mark dispatchPending so the UI
+    //     shows "Awaiting dispatch" and `/api/tasks/:id/start` can
+    //     retry.
+    //   - spawn failure: record error message so the API response
+    //     carries it.
+    for (const sub of toDispatch) {
+      const startedAt = new Date().toISOString();
+      let bgInstanceId = null;
+      let sessionId = null;
+      let dispatchError = null;
+      let dispatchPending = false;
+
+      // v6.3.0 — Active dispatch path. Spawn one `claude -p` (or
+      // `claude --bg` for long-running sessions) subprocess per
+      // subtask via claude-runner.mjs. Capture the sessionId from
+      // the runner's JSON-line stream.
+      if (claudeAvailable) {
+        try {
+          const { spawnAgent } = await import('./claude-runner.mjs');
+          // v6.3.0 — Prefer the bg-spawner's SDK-backed path when
+          // the SDK is reachable; fall back to the print-mode
+          // subprocess otherwise. We always pass `background: false`
+          // here so the runner returns a sessionId synchronously;
+          // the bg-spawner is used separately by the Active tab.
+          const dispatchWorktree = projectRoot || '';
+          const promptText = buildPromptText(sub);
+
+          // Predict the bg instance id (deterministic, derived from
+          // a short hex so the dashboard state file and the tmux
+          // session name match what the runner reports). The
+          // sessionId is generated by the subprocess; we'll learn
+          // it from the runner's structured-log stream.
+          const predictedInstanceId = `bg_${genShortHex(8)}`;
+          const logFile = getActualBgLogPath({ sessionId: predictedInstanceId });
+
+          const spawnRes = await spawnAgent({
+            prompt: promptText,
+            agent: sub.assignee || 'tyr',
+            worktree: dispatchWorktree,
+            logPath: logFile,
+            title: `bgr:${sub.assignee || 'tyr'}:${predictedInstanceId}:${sub.id}`,
+          });
+
+          if (!spawnRes.ok || !spawnRes.sessionId) {
+            dispatchError = spawnRes.error || 'claude -p failed before reporting session id';
+          } else {
+            sessionId = spawnRes.sessionId;
+            bgInstanceId = predictedInstanceId;
+
+            // v3.5.5 — Wrap the agent run in a tmux session so
+            // operators can `tmux attach -t bizar-bg-<id>` and watch
+            // the claude process in real time.
+            try {
+              const tmuxRes = backgroundStore.spawnTmuxFor(
+                `bg_${sessionId.slice(0, 16)}`,
+                { command: 'tail', args: ['-n', '200', '-F', logFile] },
+                dispatchWorktree,
+              );
+              // We do not fail the dispatch when tmux is missing.
+              if (tmuxRes.note) {
+                // pre-existing session, no log
+              }
+            } catch (err) {
+              console.warn(`[task-delegator] tmux wrap failed: ${err.message}`);
+            }
+          }
+        } catch (err) {
+          dispatchError = err instanceof Error ? err.message : String(err);
+        }
+      } else {
+        // Claude Code not available — leave the subtask marked
+        // queued with a dispatchPending flag. The UI surfaces this
+        // and the user can retry via POST /api/tasks/:id/start.
+        dispatchPending = true;
+      }
+
+      // v3.5.4 (bug: dispatch stuck) — Generate a bg instance ID even on
+      // failure so the dashboard can track attempts. Successful dispatches
+      // get a deterministic id derived from the cline session ID.
+      bgInstanceId = sessionId
+        ? `bg_${sessionId.slice(0, 16)}`
+        : `bg_${genShortHex(8)}`;
+
+      // 3. Always write the bg state file so the dashboard's background
+      //    list reflects every dispatch attempt (success or failure).
+      writeBgStateFile(bgInstanceId, {
+        instanceId: bgInstanceId,
+        sessionId: sessionId || null,
+        projectId,
+        worktree: serveInfo?.worktree || projectRoot || null,
+        agent: sub.assignee || 'tyr',
+        parentAgent: 'odin',
+        status: dispatchError ? 'failed' : 'pending',
+        startedAt: Date.now(),
+        lastActivityAt: Date.now(),
+        toolCallCount: 0,
+        promptPreview: (sub.title || '').slice(0, 200),
+        taskId: sub.id,
+        mainTaskId: main?.id || null,
+        dispatchPending,
+        error: dispatchError || null,
+      });
+
+      const metadata = { ...(sub.metadata || {}) };
+      if (bgInstanceId) metadata.bgInstanceId = bgInstanceId;
+      metadata.dispatchedAt = startedAt;
+      metadata.progress = dispatchError ? 0 : 5;
+      metadata.currentStep = dispatchError
+        ? `Dispatch failed: ${dispatchError}`
+        : (dispatchPending ? 'Awaiting dispatch (plugin offline)' : `Dispatched (${bgInstanceId})`);
+      metadata.progressHistory = [
+        ...(metadata.progressHistory || []),
+        {
+          ts: startedAt,
+          progress: metadata.progress,
+          step: metadata.currentStep,
+          agent: sub.assignee || null,
+          ...(dispatchError ? { error: dispatchError } : {}),
+        },
+      ];
+      metadata.startedAt = metadata.startedAt || startedAt;
+      if (dispatchError) metadata.dispatchError = dispatchError;
+      if (dispatchPending) metadata.dispatchPending = true;
+
+      // v3.5.4 (bug: dispatch stuck) — Mark as queued (not doing) when
+      // dispatch failed or is pending, so the task doesn't sit forever
+      // at 5% doing. The UI can still show "Dispatch pending" via the
+      // metadata flag.
+      const newStatus = dispatchError || dispatchPending ? 'queued' : 'doing';
+      const updated = await tasksStore.update(projectId, sub.id, {
+        status: newStatus,
+        metadata,
+      });
+      if (updated) {
+        broadcast({ type: 'tasks:change', task: updated });
+        if (!dispatchError && !dispatchPending) {
+          broadcast({
+            type: 'task:progress',
+            taskId: sub.id,
+            progress: 5,
+            step: metadata.currentStep,
+            agent: sub.assignee || null,
+          });
+        }
+      }
+
+      if (dispatchError) {
+        result.errors.push({ subtaskId: sub.id, kind: 'spawn_failed', message: dispatchError });
+        console.error(`[task-delegator] dispatch ${sub.id} failed:`, dispatchError);
+      } else if (dispatchPending) {
+        // Pending is not an error — just record which subtasks are
+        // waiting for the plugin to come up.
+        result.warnings.push(`subtask ${sub.id} awaiting plugin (${sub.assignee || 'tyr'})`);
+      } else {
+        result.dispatched.push(bgInstanceId);
+      }
+    }
+
+    // Note the bg dir in activity so the dashboard can link to it.
+    broadcast({
+      type: 'tasks:change',
+      task: { id: main.id, _bgDir: bgDir },
+    });
+
+    return result;
+  },
+
+  /**
+   * v3.5.4 — Dispatch a single queued task. Used by POST /api/tasks/:id/start
+   * to retry dispatch after the plugin comes up. Resolves to the same
+   * structured result as `dispatchToBackground`. Loads the task first so
+   * the caller doesn't need to know the storage layer.
+   *
+   * @param {string} taskId
+   * @param {object} ctx - { projectId, projectRoot, broadcast }
+   * @returns {Promise<{ ok: boolean, task?: object, errors: Array<…>, warnings: Array<…> }>}
+   */
+  async dispatchSingleTask(taskId, ctx = {}) {
+    const projectId = ctx.projectId || null;
+    const broadcast = ctx.broadcast || (() => {});
+    const all = await tasksStore.loadTasks(projectId, { includeArchived: false });
+    const task = all.find((t) => t.id === taskId);
+    if (!task) {
+      return { ok: false, errors: [{ subtaskId: taskId, kind: 'not_found', message: 'task not found' }], warnings: [] };
+    }
+    if (task.status !== 'queued') {
+      return {
+        ok: false,
+        task,
+        errors: [{ subtaskId: taskId, kind: 'invalid_status', message: `task is '${task.status}', must be 'queued' to start` }],
+        warnings: [],
+      };
+    }
+
+    // The task may be a subtask (has parent) or a top-level delegated
+    // task. We dispatch as a single-item subtask list so the same code
+    // path handles both.
+    const asSubtask = {
+      id: task.id,
+      title: task.title,
+      description: task.description,
+      assignee: task.assignee || 'tyr',
+      parent: task.parent || null,
+    };
+    const synthMain = { id: task.id };
+    const result = await this.dispatchToBackground(synthMain, [asSubtask], ctx, broadcast);
+    const reloaded = await tasksStore.loadTasks(projectId, { includeArchived: false });
+    const refreshed = reloaded.find((t) => t.id === taskId) || task;
+    return {
+      ok: result.errors.length === 0,
+      task: refreshed,
+      dispatched: result.dispatched,
+      errors: result.errors,
+      warnings: result.warnings,
+    };
+  },
+
+  /** For tests / introspection. */
+  _BG_DIRS: BG_DIRS,
+
+  // v3.22 — Expose runningBgCount so callers can check dispatch capacity.
+  async runningBgCount() {
+    return runningBgCount();
+  },
+
+  /**
+   * Odin-pick: drain backlog into queued slots.
+   *
+   * Algorithm:
+   *  1. Determine active project. If none, return zeros + warning.
+   *  2. Read agents.maxParallel (default 6).
+   *  3. Compute running bg count via runningBgCount().
+   *  4. Compute slotsAvailable = max(0, maxParallel - runningCount). If 0, bail.
+   *  5. Load all non-archived tasks. Collect queued (parent or subtask, not yet
+   *     dispatched) and backlog items as candidates.
+   *  6. Sort: priority high>normal>low; tiebreak createdAt ASC; backlog items
+   *     sort after queued at the same priority (drain queue first).
+   *  7. Promote backlog items to fill candidate pool up to slotsAvailable.
+   *  8. Dispatch each candidate via dispatchToBackground.
+   *
+   * @param {object} ctx - { logLine?, broadcast? }
+   * @returns {{ promoted: number, dispatched: number, skipped: string[], warnings: string[] }}
+   */
+  async tickBacklog(ctx = {}) {
+    const logLine = ctx.logLine || (() => {});
+    const broadcast = ctx.broadcast || (() => {});
+    const warnings = [];
+    const skipped = [];
+
+    // 1. Active project or bail.
+    const active = projectsStore.active();
+    if (!active) {
+      warnings.push('no active project — tickBacklog skipped');
+      return { promoted: 0, dispatched: 0, skipped, warnings };
+    }
+    const projectId = active.id;
+    const projectRoot = active.path || process.cwd();
+
+    // 2. Read maxParallel.
+    const SETTINGS_FILE = join(HOME, '.config', 'bizar', 'settings.json');
+    let maxParallel = 6;
+    try {
+      if (existsSync(SETTINGS_FILE)) {
+        const raw = readFileSync(SETTINGS_FILE, 'utf8');
+        const settings = JSON.parse(raw);
+        maxParallel = settings?.agents?.maxParallel ?? 6;
+      }
+    } catch {
+      maxParallel = 6;
+    }
+
+    // 3 & 4. Running count and slots check.
+    const runningCount = await runningBgCount();
+    const slotsAvailable = Math.max(0, maxParallel - runningCount);
+    if (slotsAvailable === 0) {
+      skipped.push('no slots available');
+      return { promoted: 0, dispatched: 0, skipped, warnings };
+    }
+
+    // 5. Collect candidates.
+    const allTasks = tasksStore.loadTasks(projectId, { includeArchived: false });
+
+    const queuedCandidates = allTasks.filter((t) => {
+      if (t.status !== 'queued' || t.archived) return false;
+      // Parent tasks need subtasks; subtasks need a parent; both need to NOT already be dispatched.
+      const isSubtask = !!t.parent;
+      const hasSubtasks = Array.isArray(t.subtasks) && t.subtasks.length > 0;
+      if (isSubtask && !hasSubtasks) return false;
+      if (!isSubtask && hasSubtasks) return false;
+      const meta = t.metadata || {};
+      if (meta.bgInstanceId || meta.dispatchPending) return false;
+      return true;
+    });
+
+    const backlogItems = allTasks.filter((t) => t.status === 'backlog' && !t.archived);
+
+    // 6. Sort: priority ASC, createdAt ASC. Backlog items go after queued at same priority.
+    const priorityWeight = { high: 0, normal: 1, low: 2 };
+    const sortKey = (t, source) => {
+      const pw = priorityWeight[t.priority] ?? 1;
+      const src = source === 'backlog' ? 1 : 0;
+      return [pw, src, t.createdAt];
+    };
+    const allCandidates = [
+      ...queuedCandidates.map((t) => ({ task: t, source: 'queued' })),
+      ...backlogItems.map((t) => ({ task: t, source: 'backlog' })),
+    ];
+    allCandidates.sort((a, b) => {
+      const [pwA, srcA, ca] = sortKey(a.task, a.source);
+      const [pwB, srcB, cb] = sortKey(b.task, b.source);
+      if (pwA !== pwB) return pwA - pwB;
+      if (srcA !== srcB) return srcA - srcB;
+      return new Date(ca).getTime() - new Date(cb).getTime();
+    });
+
+    // 7. Promote backlog items to fill slots.
+    let promoted = 0;
+    const toPromote = allCandidates.filter((c) => c.source === 'backlog');
+    const toDispatch = [
+      ...allCandidates.filter((c) => c.source === 'queued'),
+      ...toPromote,
+    ].slice(0, slotsAvailable);
+
+    for (const c of toPromote) {
+      if (toDispatch.includes(c)) {
+        const updated = await tasksStore.promote(projectId, c.task.id);
+        if (updated) {
+          broadcast({ type: 'tasks:change', task: updated });
+          promoted++;
+        }
+      }
+    }
+
+    // 8. Dispatch each candidate.
+    let dispatched = 0;
+    for (const c of toDispatch) {
+      if (c.source === 'backlog') {
+        // Already promoted above.
+        continue;
+      }
+      const asSubtask = {
+        id: c.task.id,
+        title: c.task.title,
+        description: c.task.description,
+        assignee: c.task.assignee || 'tyr',
+        parent: c.task.parent || null,
+      };
+      const synthMain = { id: c.task.id };
+      try {
+        const result = await this.dispatchToBackground(synthMain, [asSubtask], { projectRoot, projectId, state: {}, broadcast }, broadcast);
+        if (result && Array.isArray(result.dispatched) && result.dispatched.length > 0) {
+          dispatched++;
+        } else if (result && result.warnings?.length) {
+          warnings.push(...result.warnings);
+        }
+      } catch (err) {
+        skipped.push(c.task.id);
+        warnings.push(`dispatch failed for ${c.task.id}: ${err.message}`);
+      }
+    }
+
+    return { promoted, dispatched, skipped, warnings };
+  },
+};
+
+// ── Public helpers for routes that need to walk bg state ─────────────
+
+/**
+ * Read a bg instance file from any of the candidate bg dirs. Returns
+ * null if not found.
+ */
+export function readBgInstance(instanceId) {
+  for (const dir of BG_DIRS) {
+    const file = join(dir, `${instanceId}.json`);
+    if (existsSync(file)) {
+      try {
+        const raw = readFileSync(file, 'utf8');
+        return { ...JSON.parse(raw), _bgDir: dir };
+      } catch {
+        return null;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * List all bg instances across the candidate dirs.
+ */
+export function listBgInstances() {
+  const out = [];
+  for (const dir of BG_DIRS) {
+    if (!existsSync(dir)) continue;
+    let files;
+    try {
+      files = readdirSync(dir).filter((f) => f.endsWith('.json'));
+    } catch {
+      continue;
+    }
+    for (const f of files) {
+      try {
+        const full = join(dir, f);
+        const st = statSync(full);
+        const data = JSON.parse(readFileSync(full, 'utf8'));
+        out.push({ ...data, _bgDir: dir, _mtime: st.mtimeMs });
+      } catch {
+        /* skip corrupt */
+      }
+    }
+  }
+  out.sort((a, b) => (b.startedAt || b._mtime || 0) - (a.startedAt || a._mtime || 0));
+  return out;
+}
+
+export { pickBgDir, BG_DIRS };