orbital-command 0.2.0 → 1.0.0

package/server/services/scope-service.ts

@@ -1,9 +1,9 @@
 import fs from 'fs';
 import path from 'path';
 import matter from 'gray-matter';
-import type { Server } from 'socket.io';
+import type { Emitter } from '../project-emitter.js';
 import type { ParsedScope } from '../parsers/scope-parser.js';
-import { normalizeStatus, parseAllScopes, parseScopeFile, setValidStatuses } from '../parsers/scope-parser.js';
+import { parseAllScopes, parseScopeFile, setValidStatuses } from '../parsers/scope-parser.js';
 import type { WorkflowEngine } from '../../shared/workflow-engine.js';
 import type { TransitionContext, TransitionResult } from '../../shared/workflow-config.js';
 import type { ScopeCache } from './scope-cache.js';
@@ -20,7 +20,7 @@ export class ScopeService {
 
   constructor(
     private cache: ScopeCache,
-    private io: Server,
+    private io: Emitter,
     private scopesDir: string,
     private engine: WorkflowEngine,
   ) {}
@@ -46,6 +46,42 @@ export class ScopeService {
     return scopes.length;
   }
 
+  /** Reconcile files whose directory doesn't match their frontmatter status.
+   *  Frontmatter is the authoritative source — files are moved to match it.
+   *  Called once at startup after syncFromFilesystem(). */
+  reconcileDirectories(): number {
+    let moved = 0;
+    for (const scope of this.cache.getAll()) {
+      if (scope.id < 0) continue; // slug-only icebox items (negative IDs)
+      const currentDir = path.basename(path.dirname(scope.file_path));
+      if (currentDir === scope.status) continue;
+      if (!this.engine.isValidStatus(scope.status)) continue;
+
+      const targetDir = path.join(this.scopesDir, scope.status);
+      if (!fs.existsSync(targetDir)) fs.mkdirSync(targetDir, { recursive: true });
+      const newPath = path.join(targetDir, path.basename(scope.file_path));
+
+      this.suppressedPaths.add(scope.file_path);
+      this.suppressedPaths.add(newPath);
+      try {
+        fs.renameSync(scope.file_path, newPath);
+        this.updateFromFile(newPath);
+        this.removeByFilePath(scope.file_path);
+        moved++;
+        log.warn('Reconciled directory mismatch', {
+          id: scope.id, frontmatter: scope.status, directory: currentDir,
+        });
+      } catch (err) {
+        log.error('Failed to reconcile scope directory', { id: scope.id, error: String(err) });
+      }
+      setTimeout(() => {
+        this.suppressedPaths.delete(scope.file_path);
+        this.suppressedPaths.delete(newPath);
+      }, 2000);
+    }
+    return moved;
+  }
+
   /** Check if a path is suppressed from watcher processing (during programmatic moves) */
   isSuppressed(filePath: string): boolean {
     return this.suppressedPaths.has(filePath);
@@ -84,7 +120,7 @@ export class ScopeService {
     const id = this.cache.removeByFilePath(filePath);
     if (id !== undefined) {
       if (previous) this.recentlyRemoved.set(id, previous.status);
-      this.io.emit('scope:deleted', id);
+      this.io.emit('scope:deleted', { id });
       // Clean up stash after a short window (if add never fires, this was a real delete)
       setTimeout(() => this.recentlyRemoved.delete(id), 5000);
     }
@@ -102,6 +138,7 @@ export class ScopeService {
 
   /** Update a scope's status with transition validation.
    *  Writes the new status to the frontmatter file and updates the cache.
+   *  This is the SINGLE validation point — all status changes must flow through here.
    *  @param context - caller trust level: 'patch', 'dispatch', 'event', 'bulk-sync', 'rollback' */
   updateStatus(
     id: number,
@@ -131,12 +168,11 @@ export class ScopeService {
       if (!check.ok) return check;
     }
 
-    // Write to filesystem via updateScopeFrontmatter (which updates cache + emits)
-    const current = context === 'bulk-sync' || context === 'rollback'
-      ? this.cache.getById(id)
-      : this.cache.getById(id); // already fetched above for validation, but may be null in bulk-sync
+    // Fetch current scope for fromStatus logging. In bulk-sync/rollback contexts
+    // the validation block above is skipped, so this may be the first lookup.
+    const current = this.cache.getById(id);
     const fromStatus = current?.status ?? 'unknown';
-    const result = this.updateScopeFrontmatter(id, { status }, context);
+    const result = this._writeFrontmatter(id, { status });
     if (result.ok) {
       log.info('Status updated', { id, from: fromStatus, to: status, context });
       for (const cb of this.onStatusChangeCallbacks) cb(id, status);
@@ -144,8 +180,36 @@ export class ScopeService {
     return result;
   }
 
+  /** Update scope fields via a public API (e.g. PATCH route).
+   *  Status changes are routed through updateStatus for validation.
+   *  Non-status fields are written directly via _writeFrontmatter. */
+  updateFields(
+    id: number,
+    fields: Record<string, unknown>,
+  ): TransitionResult & { moved?: boolean } {
+    const { status, ...nonStatusFields } = fields as { status?: string; [k: string]: unknown };
+
+    // Status changes go through updateStatus (validates transition, fires callbacks)
+    if (status) {
+      const current = this.cache.getById(id);
+      if (!current) return { ok: false, error: 'Scope not found', code: 'NOT_FOUND' };
+      if (status !== current.status) {
+        const result = this.updateStatus(id, status);
+        if (!result.ok) return result;
+      }
+    }
+
+    // Non-status field updates written directly
+    if (Object.keys(nonStatusFields).length > 0) {
+      return this._writeFrontmatter(id, nonStatusFields);
+    }
+
+    return { ok: true, moved: !!status };
+  }
+
   /** Compute the next sequential scope ID by scanning all non-icebox scopes.
-   *  Checks both filesystem (all subdirs except icebox) and cache to prevent collisions. */
+   *  Checks both filesystem (all subdirs except icebox) and cache to prevent collisions.
+   *  Skips IDs >= 500 to handle legacy icebox-origin files during migration. */
   private getNextScopeId(): number {
     let maxId = 0;
 
@@ -156,7 +220,11 @@ export class ScopeService {
         const dirPath = path.join(this.scopesDir, dir.name);
         for (const file of fs.readdirSync(dirPath)) {
           const m = file.match(/^(\d+)-/);
-          if (m) maxId = Math.max(maxId, parseInt(m[1], 10));
+          if (!m) continue;
+          const id = parseInt(m[1], 10);
+          // Skip legacy icebox-origin IDs (500+) to prevent namespace pollution
+          if (id >= 500) continue;
+          maxId = Math.max(maxId, id);
         }
       }
     }
@@ -170,50 +238,62 @@ export class ScopeService {
 
   // ─── Idea CRUD (filesystem-backed icebox cards) ────────────
 
-  /** Get the next available icebox ID (starts at 501, increments from max found) */
-  getNextIceboxId(): number {
-    const iceboxDir = path.join(this.scopesDir, 'icebox');
-    if (!fs.existsSync(iceboxDir)) return 501;
-    let maxId = 500;
-    for (const file of fs.readdirSync(iceboxDir)) {
-      const m = file.match(/^(\d+)-/);
-      if (m) maxId = Math.max(maxId, parseInt(m[1], 10));
+  /** Normalize Date objects in gray-matter frontmatter to YYYY-MM-DD strings */
+  private normalizeFrontmatterDates(data: Record<string, unknown>): void {
+    for (const key of Object.keys(data)) {
+      if (data[key] instanceof Date) {
+        data[key] = (data[key] as Date).toISOString().split('T')[0];
+      }
     }
-    return maxId + 1;
   }
 
-  /** Find an icebox file by its ID prefix.
-   *  Matches both padded (091-) and unpadded (91-) filenames
-   *  since demoted scopes keep their 3-digit-padded names. */
-  private findIdeaFile(iceboxDir: string, id: number): string | null {
+  /** Generate a slug from a title */
+  private slugify(title: string): string {
+    const slug = title
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-|-$/g, '')
+      .slice(0, 60);
+    if (!slug) return 'untitled';
+    return slug;
+  }
+
+  /** Find an icebox file by its slug.
+   *  Matches slug-only files ({slug}.md) and legacy numeric-prefixed files ({NNN}-{slug}.md). */
+  private findIdeaFile(iceboxDir: string, slug: string): string | null {
     if (!fs.existsSync(iceboxDir)) return null;
     const match = fs.readdirSync(iceboxDir).find((f) => {
       if (!f.endsWith('.md')) return false;
-      const m = f.match(/^(\d+)-/);
-      return m != null && parseInt(m[1], 10) === id;
+      // Match slug-only: {slug}.md
+      if (f === `${slug}.md`) return true;
+      // Match legacy numeric-prefixed: {NNN}-{slug}.md
+      return f.match(/^\d+-/) && f.slice(f.indexOf('-') + 1) === `${slug}.md`;
     });
     return match ? path.join(iceboxDir, match) : null;
   }
 
-  /** Create an icebox idea as a markdown file. IDs start at 501. */
-  createIdeaFile(title: string, description: string): { id: number; title: string } {
+  /** Create an icebox idea as a slug-only markdown file. */
+  createIdeaFile(title: string, description: string): { slug: string; title: string } {
     const iceboxDir = path.join(this.scopesDir, 'icebox');
     if (!fs.existsSync(iceboxDir)) fs.mkdirSync(iceboxDir, { recursive: true });
 
-    const nextId = this.getNextIceboxId();
+    const slug = this.slugify(title);
+    let fileName = `${slug}.md`;
+    let filePath = path.join(iceboxDir, fileName);
 
-    const slug = title
-      .toLowerCase()
-      .replace(/[^a-z0-9]+/g, '-')
-      .replace(/^-|-$/g, '')
-      .slice(0, 60);
-    const fileName = `${nextId}-${slug}.md`;
-    const filePath = path.join(iceboxDir, fileName);
+    // Handle slug collisions by appending -2, -3, etc.
+    if (fs.existsSync(filePath)) {
+      let suffix = 2;
+      while (fs.existsSync(path.join(iceboxDir, `${slug}-${suffix}.md`))) suffix++;
+      fileName = `${slug}-${suffix}.md`;
+      filePath = path.join(iceboxDir, fileName);
+    }
+
+    const finalSlug = fileName.replace(/\.md$/, '');
     const now = new Date().toISOString().split('T')[0];
 
     const content = [
       '---',
-      `id: ${nextId}`,
       `title: "${title.replace(/"/g, '\\"')}"`,
       'status: icebox',
       `created: ${now}`,
@@ -231,116 +311,134 @@ export class ScopeService {
 
     // Eagerly sync to cache + emit scope:created
     this.updateFromFile(filePath);
-    log.info('Idea created', { id: nextId, title });
-    return { id: nextId, title };
+    log.info('Idea created', { slug: finalSlug, title });
+    return { slug: finalSlug, title };
   }
 
-  /** Update an icebox idea's title and description by rewriting its file */
-  updateIdeaFile(id: number, title: string, description: string): boolean {
+  /** Update an icebox idea's title and description in-place. Renames the file if the title slug changes. */
+  updateIdeaFile(slug: string, title: string, description: string): boolean {
     const iceboxDir = path.join(this.scopesDir, 'icebox');
-    const filePath = this.findIdeaFile(iceboxDir, id);
+    const filePath = this.findIdeaFile(iceboxDir, slug);
     if (!filePath) return false;
 
     // Preserve the original created date from existing frontmatter
     const existing = fs.readFileSync(filePath, 'utf-8');
-    const createdMatch = existing.match(/^created:\s*(.+)$/m);
-    const created = createdMatch?.[1]?.trim() ?? new Date().toISOString().split('T')[0];
+    const parsed = matter(existing);
+    const created = parsed.data.created ? String(parsed.data.created) : new Date().toISOString().split('T')[0];
     const now = new Date().toISOString().split('T')[0];
 
-    const content = [
-      '---',
-      `id: ${id}`,
-      `title: "${title.replace(/"/g, '\\"')}"`,
-      'status: icebox',
-      `created: ${created}`,
-      `updated: ${now}`,
-      'blocked_by: []',
-      'blocks: []',
-      'tags: []',
-      '---',
-      '',
-      description || '',
-      '',
-    ].join('\n');
+    // Update frontmatter fields while preserving other data (like ghost)
+    parsed.data.title = title;
+    parsed.data.updated = now;
+    parsed.data.created = created;
+    this.normalizeFrontmatterDates(parsed.data);
+
+    const newContent = matter.stringify(description ? `\n${description}\n` : '\n', parsed.data);
+    fs.writeFileSync(filePath, newContent, 'utf-8');
+
+    // If title changed, rename file to new slug
+    const newSlug = this.slugify(title);
+    if (newSlug !== slug) {
+      const newFileName = `${newSlug}.md`;
+      const newPath = path.join(iceboxDir, newFileName);
+      if (!fs.existsSync(newPath)) {
+        this.suppressedPaths.add(filePath);
+        this.suppressedPaths.add(newPath);
+        this.removeByFilePath(filePath);
+        fs.renameSync(filePath, newPath);
+        this.updateFromFile(newPath);
+        setTimeout(() => {
+          this.suppressedPaths.delete(filePath);
+          this.suppressedPaths.delete(newPath);
+        }, 2000);
+      } else {
+        // Collision with existing slug — keep old filename, still sync content changes
+        log.warn('Slug collision during rename, keeping old filename', { slug, newSlug });
+        this.updateFromFile(filePath);
+      }
+    } else {
+      // Eagerly sync content changes to cache
+      this.updateFromFile(filePath);
+    }
 
-    fs.writeFileSync(filePath, content, 'utf-8');
-    // Watcher handles cache sync + scope:updated event
     return true;
   }
 
   /** Delete an icebox idea by removing its file */
-  deleteIdeaFile(id: number): boolean {
+  deleteIdeaFile(slug: string): boolean {
     const iceboxDir = path.join(this.scopesDir, 'icebox');
-    const filePath = this.findIdeaFile(iceboxDir, id);
+    const filePath = this.findIdeaFile(iceboxDir, slug);
     if (!filePath) return false;
 
     fs.unlinkSync(filePath);
     // Eagerly remove from cache + emit scope:deleted
     this.removeByFilePath(filePath);
-    log.info('Idea deleted', { id });
+    log.info('Idea deleted', { slug });
     return true;
   }
 
   /** Promote an icebox idea to planning — assigns a proper sequential scope ID,
    *  moves the file, and syncs cache. Returns the new scope ID. */
-  promoteIdea(id: number): { id: number; filePath: string; title: string; description: string } | null {
+  promoteIdea(slug: string, targetStatus = 'planning'): { id: number; filePath: string; title: string; description: string } | null {
     const iceboxDir = path.join(this.scopesDir, 'icebox');
-    const oldPath = this.findIdeaFile(iceboxDir, id);
+    const oldPath = this.findIdeaFile(iceboxDir, slug);
     if (!oldPath) return null;
 
     // Read existing file for metadata
-    const content = fs.readFileSync(oldPath, 'utf-8');
-    const titleMatch = content.match(/^title:\s*"?([^"\n]+)"?\s*$/m);
-    const createdMatch = content.match(/^created:\s*(.+)$/m);
-    const title = titleMatch?.[1]?.trim() ?? 'Untitled';
-    const created = createdMatch?.[1]?.trim() ?? new Date().toISOString().split('T')[0];
-
-    // Extract body after frontmatter
-    const fmEnd = content.indexOf('---', content.indexOf('---') + 3);
-    const description = fmEnd !== -1 ? content.slice(fmEnd + 3).trim() : '';
+    const raw = fs.readFileSync(oldPath, 'utf-8');
+    const parsed = matter(raw);
+    const title = parsed.data.title ? String(parsed.data.title) : 'Untitled';
+    const created = parsed.data.created ? String(parsed.data.created) : new Date().toISOString().split('T')[0];
+    const description = parsed.content.trim();
 
     // Assign the next sequential scope ID (excludes icebox items)
     const newId = this.getNextScopeId();
     const paddedId = String(newId).padStart(3, '0');
 
-    // Build slug and new path
-    const slug = title
-      .toLowerCase()
-      .replace(/[^a-z0-9]+/g, '-')
-      .replace(/^-|-$/g, '')
-      .slice(0, 60);
-    const planningDir = path.join(this.scopesDir, 'planning');
-    if (!fs.existsSync(planningDir)) fs.mkdirSync(planningDir, { recursive: true });
-    const newFileName = `${paddedId}-${slug}.md`;
-    const newPath = path.join(planningDir, newFileName);
+    // Build new path
+    const titleSlug = this.slugify(title);
+    const targetDir = path.join(this.scopesDir, targetStatus);
+    if (!fs.existsSync(targetDir)) fs.mkdirSync(targetDir, { recursive: true });
+    const newFileName = `${paddedId}-${titleSlug}.md`;
+    const newPath = path.join(targetDir, newFileName);
     const now = new Date().toISOString().split('T')[0];
 
-    // Write new file with planning status and new sequential ID
-    const newContent = [
-      '---',
-      `id: ${paddedId}`,
-      `title: "${title.replace(/"/g, '\\"')}"`,
-      'status: planning',
-      `created: ${created}`,
-      `updated: ${now}`,
-      'blocked_by: []',
-      'blocks: []',
-      'tags: []',
-      '---',
-      '',
-      description || '',
-      '',
-    ].join('\n');
+    // Update frontmatter in-place: assign ID and change status (preserve other fields)
+    parsed.data.id = newId;
+    parsed.data.status = targetStatus;
+    parsed.data.updated = now;
+    parsed.data.created = created;
+    delete parsed.data.ghost;
+    this.normalizeFrontmatterDates(parsed.data);
 
-    fs.writeFileSync(newPath, newContent, 'utf-8');
+    const newContent = matter.stringify(parsed.content, parsed.data);
+
+    // Write updated content to old path, then rename/move (no intermediate missing state)
+    const originalContent = fs.readFileSync(oldPath, 'utf-8');
+    fs.writeFileSync(oldPath, newContent, 'utf-8');
 
-    // Sync cache before deleting old file (avoids window where scope is missing)
+    // Suppress watcher events during programmatic move
+    this.suppressedPaths.add(oldPath);
+    this.suppressedPaths.add(newPath);
+    try {
+      fs.renameSync(oldPath, newPath);
+    } catch (err) {
+      // Restore original content on rename failure
+      fs.writeFileSync(oldPath, originalContent, 'utf-8');
+      this.suppressedPaths.delete(oldPath);
+      this.suppressedPaths.delete(newPath);
+      log.error('Failed to rename during promote', { oldPath, newPath, error: String(err) });
+      return null;
+    }
     this.updateFromFile(newPath);
-    fs.unlinkSync(oldPath);
     this.removeByFilePath(oldPath);
+    setTimeout(() => {
+      this.suppressedPaths.delete(oldPath);
+      this.suppressedPaths.delete(newPath);
+    }, 2000);
 
     const relPath = path.relative(path.resolve(this.scopesDir, '..'), newPath);
-    log.info('Idea promoted', { oldId: id, newId, title });
+    log.info('Idea promoted', { slug, newId, title });
     return { id: newId, filePath: relPath, title, description };
   }
 
@@ -362,13 +460,13 @@ export class ScopeService {
     return null;
   }
 
-  /** Update a scope's frontmatter fields and write back to the .md file.
-   *  If status changes, validates the transition and moves the file to the new status directory.
-   *  @param context - transition context for validation (default 'patch') */
-  updateScopeFrontmatter(
+  /** Write frontmatter fields to a scope's .md file.
+   *  If the effective status differs from the current directory, moves the file.
+   *  This is a trusted write operation — callers must validate transitions
+   *  via updateStatus() before calling this method with status changes. */
+  private _writeFrontmatter(
     id: number,
     fields: Record<string, unknown>,
-    context: TransitionContext = 'patch',
   ): TransitionResult & { moved?: boolean } {
     const filePath = this.findScopeFile(id);
     if (!filePath) {
@@ -379,25 +477,21 @@ export class ScopeService {
     const parsed = matter(raw);
     const today = new Date().toISOString().split('T')[0];
 
-    // Validate status transition before any writes
+    // Determine if the file needs to move to a different directory.
+    // Compare against the DIRECTORY name (not frontmatter status) since the question
+    // is whether the physical file location matches the desired status.
     const newStatus = fields.status as string | undefined;
-    const rawOldStatus = String(parsed.data.status ?? 'planning');
-    const oldStatus = normalizeStatus(rawOldStatus);
-    let needsMove = false;
+    const dirName = path.basename(path.dirname(filePath));
+    const effectiveStatus = newStatus ?? String(parsed.data.status ?? dirName);
+    const needsMove = effectiveStatus !== dirName && this.engine.isValidStatus(effectiveStatus);
 
-    if (newStatus && newStatus !== oldStatus) {
-      if (!this.engine.isValidStatus(newStatus)) {
-        return { ok: false, error: `Invalid status: '${newStatus}'`, code: 'INVALID_STATUS' };
-      }
-      const check = this.engine.validateTransition(oldStatus, newStatus, context);
-      if (!check.ok) return check;
-      needsMove = true;
-      // Auto-unlock spec when reverting backlog → planning
-      if (newStatus === 'planning' && oldStatus === 'backlog') fields.spec_locked = false;
+    // Auto-unlock spec when reverting backlog → planning
+    if (newStatus === 'planning' && dirName === 'backlog') {
+      fields = { ...fields, spec_locked: false };
     }
 
     // Merge editable fields into frontmatter
-    const editableKeys = ['title', 'status', 'priority', 'effort_estimate', 'category', 'tags', 'blocked_by', 'blocks', 'spec_locked'];
+    const editableKeys = ['title', 'status', 'priority', 'effort_estimate', 'category', 'tags', 'blocked_by', 'blocks', 'spec_locked', 'favourite'];
     for (const key of editableKeys) {
       if (key in fields) {
         const val = fields[key];
@@ -429,8 +523,8 @@ export class ScopeService {
       return { ok: true };
     }
 
-    // Status change → move file to new directory
-    const targetDir = path.join(this.scopesDir, newStatus!);
+    // Status differs from directory → move file to correct directory
+    const targetDir = path.join(this.scopesDir, effectiveStatus);
     if (!fs.existsSync(targetDir)) fs.mkdirSync(targetDir, { recursive: true });
 
     const fileName = path.basename(filePath);
@@ -451,15 +545,15 @@ export class ScopeService {
     setTimeout(() => {
       this.suppressedPaths.delete(filePath);
       this.suppressedPaths.delete(newPath);
-    }, 500);
+    }, 2000);
 
     return { ok: true, moved: true };
   }
 
   /** Approve a ghost idea — removes ghost:true from frontmatter and refreshes cache */
-  approveGhostIdea(id: number): boolean {
+  approveGhostIdea(slug: string): boolean {
     const iceboxDir = path.join(this.scopesDir, 'icebox');
-    const filePath = this.findIdeaFile(iceboxDir, id);
+    const filePath = this.findIdeaFile(iceboxDir, slug);
     if (!filePath) return false;
 
     const content = fs.readFileSync(filePath, 'utf-8');
@@ -469,7 +563,7 @@ export class ScopeService {
 
     // Re-parse file to refresh cache with is_ghost=false
     this.updateFromFile(filePath);
-    log.info('Ghost approved', { id });
+    log.info('Ghost approved', { slug });
 
     return true;
   }

package/server/services/sprint-orchestrator.ts

@@ -1,11 +1,12 @@
 import type Database from 'better-sqlite3';
-import type { Server } from 'socket.io';
+import type { Emitter } from '../project-emitter.js';
 import { SprintService } from './sprint-service.js';
 import { ScopeService } from './scope-service.js';
-import { launchInCategorizedTerminal, escapeForAnsiC, buildSessionName, snapshotSessionPids, discoverNewSession, renameSession } from '../utils/terminal-launcher.js';
+import { launchInCategorizedTerminal, escapeForAnsiC, shellQuote, buildSessionName, snapshotSessionPids, discoverNewSession, renameSession } from '../utils/terminal-launcher.js';
 import { resolveDispatchEvent, linkPidToDispatch } from '../utils/dispatch-utils.js';
+import { buildClaudeFlags, buildEnvVarPrefix } from '../utils/flag-builder.js';
 import type { WorkflowEngine } from '../../shared/workflow-engine.js';
-import { getConfig } from '../config.js';
+import type { OrbitalConfig } from '../config.js';
 import { createLogger } from '../utils/logger.js';
 
 const log = createLogger('sprint');
@@ -20,10 +21,12 @@ function sleep(ms: number): Promise<void> {
 export class SprintOrchestrator {
   constructor(
     private db: Database.Database,
-    private io: Server,
+    private io: Emitter,
     private sprintService: SprintService,
     private scopeService: ScopeService,
     private engine: WorkflowEngine,
+    private projectRoot: string,
+    private config: OrbitalConfig,
   ) {}
 
   /** Build execution layers using Kahn's topological sort */
@@ -112,14 +115,16 @@ export class SprintOrchestrator {
   async onScopeReachedDev(scopeId: number): Promise<void> {
     const match = this.sprintService.findActiveSprintForScope(scopeId);
     if (!match) return;
-    log.debug('Scope reached dev', { scopeId, sprintId: match.sprint_id });
 
+    // Batches are managed by BatchOrchestrator — don't dispatch individual scopes
     const sprintId = match.sprint_id;
+    const sprint = this.sprintService.getById(sprintId);
+    if (!sprint || sprint.group_type === 'batch') return;
+
+    log.debug('Scope reached dev', { scopeId, sprintId });
     this.sprintService.updateScopeStatus(sprintId, scopeId, 'completed');
 
     // Ensure sprint is in 'in_progress' state
-    const sprint = this.sprintService.getById(sprintId);
-    if (!sprint) return;
     if (sprint.status === 'dispatched') {
       this.sprintService.updateStatus(sprintId, 'in_progress');
     }
@@ -196,7 +201,7 @@ export class SprintOrchestrator {
     const sprint = this.sprintService.getById(sprintId);
     if (!sprint) return null;
 
-    const layers = sprint.layers ?? [];
+    const layers = sprint.layers ?? this.buildExecutionLayers(sprint.scope_ids).layers;
     const sprintSet = new Set(sprint.scope_ids);
     const edges: Array<{ from: number; to: number }> = [];
 
@@ -225,9 +230,15 @@ export class SprintOrchestrator {
       const currentScope = this.scopeService.getById(scopeId);
       const previousStatus = currentScope?.status ?? 'implementing';
 
+      // Resolve command and target status from workflow engine
+      const sprint = this.sprintService.getById(sprintId);
+      const targetColumn = sprint?.target_column ?? 'backlog';
+      const edgeCommand = this.engine.getBatchCommand(targetColumn);
+      const targetStatus = this.engine.getBatchTargetStatus(targetColumn);
+
       // Record DISPATCH event
       const eventId = crypto.randomUUID();
-      const command = `/scope implement ${scopeId}`;
+      const command = edgeCommand ?? `/scope-implement ${scopeId}`;
       this.db.prepare(
         `INSERT INTO events (id, type, scope_id, session_id, agent, data, timestamp)
          VALUES (?, 'DISPATCH', ?, NULL, 'sprint-orchestrator', ?, ?)`,
@@ -241,26 +252,30 @@ export class SprintOrchestrator {
       });
 
       // Update scope + sprint_scope status
-      this.scopeService.updateStatus(scopeId, 'implementing', 'dispatch');
+      if (targetStatus) {
+        this.scopeService.updateStatus(scopeId, targetStatus, 'dispatch');
+      }
       this.sprintService.updateScopeStatus(sprintId, scopeId, 'dispatched');
 
       // Build scope-aware session name and snapshot PIDs
       const scopeRow = this.scopeService.getById(scopeId);
       const sessionName = buildSessionName({ scopeId, title: scopeRow?.title, command });
-      const beforePids = snapshotSessionPids(getConfig().projectRoot);
+      const beforePids = snapshotSessionPids(this.projectRoot);
 
-      // Launch in iTerm — interactive TUI mode (no -p) for full visibility
+      // Launch in iTerm — interactive TUI mode for full visibility
       const escaped = escapeForAnsiC(command);
-      const fullCmd = `cd '${getConfig().projectRoot}' && claude --dangerously-skip-permissions $'${escaped}'`;
+      const flagsStr = buildClaudeFlags(this.config.claude.dispatchFlags);
+      const envPrefix = buildEnvVarPrefix(this.config.dispatch.envVars);
+      const fullCmd = `cd '${shellQuote(this.projectRoot)}' && ${envPrefix}ORBITAL_DISPATCH_ID='${shellQuote(eventId)}' claude ${flagsStr} $'${escaped}'`;
       try {
         await launchInCategorizedTerminal(command, fullCmd, sessionName);
 
         // Fire-and-forget: discover session PID, link to dispatch, and rename
-        discoverNewSession(getConfig().projectRoot, beforePids)
+        discoverNewSession(this.projectRoot, beforePids)
           .then((session) => {
             if (!session) return;
             linkPidToDispatch(this.db, eventId, session.pid);
-            if (sessionName) renameSession(getConfig().projectRoot, session.sessionId, sessionName);
+            if (sessionName) renameSession(this.projectRoot, session.sessionId, sessionName);
           })
           .catch(err => log.error('PID discovery failed', { error: err.message }));
       } catch (err) {