@cleocode/core 2026.9.8 → 2026.9.10

package/dist/orchestrate/query-ops.js

@@ -19,7 +19,7 @@ import { analyzeEpic, getNextTask, getReadyTasks } from '../orchestration/index.
 import { computeEpicStatus, computeOverallStatus } from '../orchestration/status.js';
 import { validateSpawnReadiness } from '../orchestration/validate-spawn.js';
 import { getEnrichedWaves } from '../orchestration/waves.js';
-import { getProjectRoot } from '../paths.js';
+import { captureProjectScope, getProjectRoot, worktreeScope } from '../project-scope.js';
 import { isSagaShape } from '../sagas/enforcement.js';
 import { resolveSagaMemberIds } from '../sagas/storage.js';
 import { getTaskAccessor } from '../store/data-accessor.js';
@@ -84,20 +84,18 @@ export async function resolveSagaMembers(accessor, sagaId) {
  * Load all tasks from task data.
  *
  * @param projectRoot - Optional project root path. Defaults to resolved root.
- * @returns Array of all tasks, empty on error.
+ * @returns All matched tasks, including an empty array for an empty project.
+ * @throws Error when project identity or task storage cannot be read.
  */
 export async function loadTasks(projectRoot) {
-    const root = getProjectRoot(projectRoot);
-    try {
-        const accessor = await getTaskAccessor(root);
+    const scope = captureProjectScope(projectRoot ?? getProjectRoot(), worktreeScope.getStore());
+    return worktreeScope.run(scope, async () => {
+        const accessor = await getTaskAccessor(scope.worktreeRoot);
         const result = await accessor.queryTasks({
             status: [...TASK_STATUSES],
         });
-        return result?.tasks ?? [];
-    }
-    catch {
-        return [];
-    }
+        return result.tasks;
+    });
 }
 /**
  * orchestrate.status - Get orchestrator status
@@ -109,20 +107,23 @@ export async function loadTasks(projectRoot) {
  */
 export async function orchestrateStatus(epicId, projectRoot) {
     try {
-        const root = getProjectRoot(projectRoot);
-        const tasks = await loadTasks(root);
-        if (epicId) {
-            const epic = tasks.find((t) => t.id === epicId);
-            if (!epic) {
-                return engineError('E_NOT_FOUND', `Epic ${epicId} not found`);
+        const scope = captureProjectScope(projectRoot ?? getProjectRoot(), worktreeScope.getStore());
+        return await worktreeScope.run(scope, async () => {
+            const root = scope.worktreeRoot;
+            const tasks = await loadTasks(root);
+            if (epicId) {
+                const epic = tasks.find((t) => t.id === epicId);
+                if (!epic) {
+                    return engineError('E_NOT_FOUND', `Epic ${epicId} not found`);
+                }
+                const children = tasks.filter((t) => t.parentId === epicId);
+                const status = computeEpicStatus(epicId, epic.title, children);
+                return { success: true, data: status };
             }
-            const children = tasks.filter((t) => t.parentId === epicId);
-            const status = computeEpicStatus(epicId, epic.title, children);
+            // No epicId - return overall status
+            const status = computeOverallStatus(tasks);
             return { success: true, data: status };
-        }
-        // No epicId - return overall status
-        const status = computeOverallStatus(tasks);
-        return { success: true, data: status };
+        });
     }
     catch (err) {
         return engineError('E_GENERAL', err.message);
@@ -138,35 +139,38 @@ export async function orchestrateStatus(epicId, projectRoot) {
  * @task T4478
  */
 export async function orchestrateAnalyze(epicId, projectRoot, mode) {
-    // Mode: critical-path (delegates to critical path engine)
-    if (mode === 'critical-path') {
-        const { orchestrateCriticalPath } = await import('./lifecycle-ops.js');
-        return orchestrateCriticalPath(projectRoot);
-    }
-    // Default mode: analysis (requires epicId)
-    if (!epicId) {
-        return engineError('E_INVALID_INPUT', 'epicId is required for standard analysis');
-    }
     try {
-        const root = getProjectRoot(projectRoot);
-        const accessor = await getTaskAccessor(root);
-        const result = await analyzeEpic(epicId, root, accessor);
-        // Add dependency graph and circular dep detection via core analyze module
-        const tasks = await loadTasks(root);
-        const children = tasks.filter((t) => t.parentId === epicId);
-        const depAnalysis = analyzeDependencies(children, tasks);
-        return {
-            success: true,
-            data: {
-                epicId: result.epicId,
-                epicTitle: tasks.find((t) => t.id === epicId)?.title || epicId,
-                totalTasks: result.totalTasks,
-                waves: result.waves,
-                circularDependencies: depAnalysis.circularDependencies,
-                missingDependencies: depAnalysis.missingDependencies,
-                dependencyGraph: depAnalysis.dependencyGraph,
-            },
-        };
+        const scope = captureProjectScope(projectRoot ?? getProjectRoot(), worktreeScope.getStore());
+        return await worktreeScope.run(scope, async () => {
+            // Mode: critical-path (delegates to critical path engine)
+            if (mode === 'critical-path') {
+                const { orchestrateCriticalPath } = await import('./lifecycle-ops.js');
+                return orchestrateCriticalPath(scope.worktreeRoot);
+            }
+            // Default mode: analysis (requires epicId)
+            if (!epicId) {
+                return engineError('E_INVALID_INPUT', 'epicId is required for standard analysis');
+            }
+            const root = scope.worktreeRoot;
+            const accessor = await getTaskAccessor(root);
+            const result = await analyzeEpic(epicId, root, accessor);
+            // Add dependency graph and circular dep detection via core analyze module
+            const tasks = await loadTasks(root);
+            const children = tasks.filter((t) => t.parentId === epicId);
+            const depAnalysis = analyzeDependencies(children, tasks);
+            return {
+                success: true,
+                data: {
+                    epicId: result.epicId,
+                    epicTitle: tasks.find((t) => t.id === epicId)?.title || epicId,
+                    totalTasks: result.totalTasks,
+                    waves: result.waves,
+                    circularDependencies: depAnalysis.circularDependencies,
+                    missingDependencies: depAnalysis.missingDependencies,
+                    dependencyGraph: depAnalysis.dependencyGraph,
+                },
+            };
+        });
     }
     catch (err) {
         const code = err.code ?? 'E_GENERAL';
@@ -194,208 +198,211 @@ export async function orchestrateAnalyze(epicId, projectRoot, mode) {
  * @task T1858
  */
 export async function orchestrateReady(epicId, projectRoot, opts) {
-    if (!epicId) {
-        return engineError('E_INVALID_INPUT', 'epicId is required');
-    }
     try {
-        const root = getProjectRoot(projectRoot);
-        // T929: verify the epic exists before computing the ready-set so that a
-        // nonexistent epicId returns E_NOT_FOUND (exit 4) instead of success:{total:0}.
-        const tasks = await loadTasks(root);
-        const epic = tasks.find((t) => t.id === epicId);
-        if (!epic) {
-            return engineError('E_NOT_FOUND', `Epic ${epicId} not found`);
-        }
-        // ---------------------------------------------------------------------------
-        // T1858: dep-graph validation pre-step (shared between parent + saga modes)
-        // ---------------------------------------------------------------------------
-        const config = await loadConfig(root);
-        const lifecycleMode = config.lifecycle?.mode ?? 'strict';
-        let depsWarning;
-        // Helper: filter issues to only those that are actionable blockers for
-        // the epic ready-set check. Excludes:
-        //   - E_ORPHAN: project-level concern, not specific to the epic ready-check.
-        //   - E_MISSING_REF where the referenced task EXISTS project-wide (cross-epic
-        //     deps that are outside the scoped set are not truly missing).
-        const projectTaskIds = new Set(tasks.map((t) => t.id));
-        const toBlockerIssues = (issues) => issues.filter((i) => {
-            if (i.code === 'E_ORPHAN')
-                return false;
-            if (i.code === 'E_MISSING_REF') {
-                // relatedIds contains the dep ID that was reported missing in the scope.
-                // If it actually exists project-wide, it's just a cross-epic dep — not a
-                // true missing reference.
-                return (i.relatedIds ?? []).some((depId) => !projectTaskIds.has(depId));
+        const scope = captureProjectScope(projectRoot ?? getProjectRoot(), worktreeScope.getStore());
+        return await worktreeScope.run(scope, async () => {
+            if (!epicId) {
+                return engineError('E_INVALID_INPUT', 'epicId is required');
             }
-            return true;
-        });
-        if (opts?.ignoreDepsValidate) {
-            // Bypass requested — audit-log it regardless of mode, then skip check.
-            const validation = runValidation(tasks, { epicId });
-            const blockerIssues = toBlockerIssues(validation.issues);
-            appendDepsValidateBypassAudit(root, {
-                ts: new Date().toISOString(),
-                epicId,
-                source: 'cli',
-                issueCount: blockerIssues.length,
-                issues: blockerIssues.map(({ code, taskId, epicA, epicB }) => ({
-                    code,
-                    taskId,
-                    epicA,
-                    epicB,
-                })),
-            });
-        }
-        else if (lifecycleMode !== 'off') {
-            const validation = runValidation(tasks, { epicId });
-            const blockerIssues = toBlockerIssues(validation.issues);
-            const isValid = blockerIssues.length === 0;
-            if (!isValid) {
-                const summary = `Dep graph has ${blockerIssues.length} issue(s): ${[...new Set(blockerIssues.map((i) => i.code))].join(', ')}`;
-                if (lifecycleMode === 'strict') {
-                    return engineError('E_DEP_GRAPH_INVALID', summary, {
-                        details: { issueCount: blockerIssues.length, issues: blockerIssues },
-                    });
+            const root = scope.worktreeRoot;
+            // T929: verify the epic exists before computing the ready-set so that a
+            // nonexistent epicId returns E_NOT_FOUND (exit 4) instead of success:{total:0}.
+            const tasks = await loadTasks(root);
+            const epic = tasks.find((t) => t.id === epicId);
+            if (!epic) {
+                return engineError('E_NOT_FOUND', `Epic ${epicId} not found`);
+            }
+            // ---------------------------------------------------------------------------
+            // T1858: dep-graph validation pre-step (shared between parent + saga modes)
+            // ---------------------------------------------------------------------------
+            const config = await loadConfig(root);
+            const lifecycleMode = config.lifecycle?.mode ?? 'strict';
+            let depsWarning;
+            // Helper: filter issues to only those that are actionable blockers for
+            // the epic ready-set check. Excludes:
+            //   - E_ORPHAN: project-level concern, not specific to the epic ready-check.
+            //   - E_MISSING_REF where the referenced task EXISTS project-wide (cross-epic
+            //     deps that are outside the scoped set are not truly missing).
+            const projectTaskIds = new Set(tasks.map((t) => t.id));
+            const toBlockerIssues = (issues) => issues.filter((i) => {
+                if (i.code === 'E_ORPHAN')
+                    return false;
+                if (i.code === 'E_MISSING_REF') {
+                    // relatedIds contains the dep ID that was reported missing in the scope.
+                    // If it actually exists project-wide, it's just a cross-epic dep — not a
+                    // true missing reference.
+                    return (i.relatedIds ?? []).some((depId) => !projectTaskIds.has(depId));
                 }
-                // advisory: warn + proceed
-                depsWarning = summary;
+                return true;
+            });
+            if (opts?.ignoreDepsValidate) {
+                // Bypass requested — audit-log it regardless of mode, then skip check.
+                const validation = runValidation(tasks, { epicId });
+                const blockerIssues = toBlockerIssues(validation.issues);
+                appendDepsValidateBypassAudit(root, {
+                    ts: new Date().toISOString(),
+                    epicId,
+                    source: 'cli',
+                    issueCount: blockerIssues.length,
+                    issues: blockerIssues.map(({ code, taskId, epicA, epicB }) => ({
+                        code,
+                        taskId,
+                        epicA,
+                        epicB,
+                    })),
+                });
             }
-        }
-        // mode === 'off': skip validation entirely
-        // ---------------------------------------------------------------------------
-        // -------------------------------------------------------------------------
-        // T10966: Saga-aware traversal — always auto-detect saga shape.
-        //
-        // After T10638, sagas use `type='saga'` with `parent_id` containment.
-        // The `via` parameter is deprecated (T10968); all callers get the same
-        // auto-detect behavior. Saga members are recursed into per-member; the
-        // result is the deduplicated union of ready tasks across all members.
-        // -------------------------------------------------------------------------
-        // T10331 (Saga T10326 W2.B): dual-shape saga detection via isSagaShape.
-        const sagaShaped = isSagaShape(epic);
-        const accessor = await getTaskAccessor(root);
-        if (sagaShaped) {
-            // T10966: use canonical resolveSagaMemberIds (with type-checking).
-            const memberIds = await resolveSagaMemberIds(accessor, epicId);
-            const members = memberIds ?? [];
-            const seenIds = new Set();
-            const aggregated = [];
-            let aggregatedAllCount = 0;
-            let aggregatedBlockedCount = 0;
-            const skippedNested = [];
-            for (const memberId of members) {
-                // Recursion safety: sagas SHOULD NOT nest (ADR-073). If a member is
-                // itself saga-shaped, skip it and surface the anomaly in meta rather
-                // than recursing — preserves O(N) aggregation.
-                const memberTask = tasks.find((t) => t.id === memberId);
-                if (memberTask && isSagaShape(memberTask)) {
-                    skippedNested.push(memberId);
-                    continue;
+            else if (lifecycleMode !== 'off') {
+                const validation = runValidation(tasks, { epicId });
+                const blockerIssues = toBlockerIssues(validation.issues);
+                const isValid = blockerIssues.length === 0;
+                if (!isValid) {
+                    const summary = `Dep graph has ${blockerIssues.length} issue(s): ${[...new Set(blockerIssues.map((i) => i.code))].join(', ')}`;
+                    if (lifecycleMode === 'strict') {
+                        return engineError('E_DEP_GRAPH_INVALID', summary, {
+                            details: { issueCount: blockerIssues.length, issues: blockerIssues },
+                        });
+                    }
+                    // advisory: warn + proceed
+                    depsWarning = summary;
                 }
-                const memberReady = await getReadyTasks(memberId, root, accessor);
-                aggregatedAllCount += memberReady.length;
-                aggregatedBlockedCount += memberReady.filter((t) => !t.ready && t.blockers.length > 0).length;
-                for (const t of memberReady) {
-                    if (!t.ready)
-                        continue;
-                    if (seenIds.has(t.taskId))
+            }
+            // mode === 'off': skip validation entirely
+            // ---------------------------------------------------------------------------
+            // -------------------------------------------------------------------------
+            // T10966: Saga-aware traversal — always auto-detect saga shape.
+            //
+            // After T10638, sagas use `type='saga'` with `parent_id` containment.
+            // The `via` parameter is deprecated (T10968); all callers get the same
+            // auto-detect behavior. Saga members are recursed into per-member; the
+            // result is the deduplicated union of ready tasks across all members.
+            // -------------------------------------------------------------------------
+            // T10331 (Saga T10326 W2.B): dual-shape saga detection via isSagaShape.
+            const sagaShaped = isSagaShape(epic);
+            const accessor = await getTaskAccessor(root);
+            if (sagaShaped) {
+                // T10966: use canonical resolveSagaMemberIds (with type-checking).
+                const memberIds = await resolveSagaMemberIds(accessor, epicId);
+                const members = memberIds ?? [];
+                const seenIds = new Set();
+                const aggregated = [];
+                let aggregatedAllCount = 0;
+                let aggregatedBlockedCount = 0;
+                const skippedNested = [];
+                for (const memberId of members) {
+                    // Recursion safety: sagas SHOULD NOT nest (ADR-073). If a member is
+                    // itself saga-shaped, skip it and surface the anomaly in meta rather
+                    // than recursing — preserves O(N) aggregation.
+                    const memberTask = tasks.find((t) => t.id === memberId);
+                    if (memberTask && isSagaShape(memberTask)) {
+                        skippedNested.push(memberId);
                         continue;
-                    seenIds.add(t.taskId);
-                    aggregated.push({
-                        id: t.taskId,
-                        title: t.title,
-                        priority: t.priority,
-                        depends: t.depends,
-                    });
+                    }
+                    const memberReady = await getReadyTasks(memberId, root, accessor);
+                    aggregatedAllCount += memberReady.length;
+                    aggregatedBlockedCount += memberReady.filter((t) => !t.ready && t.blockers.length > 0).length;
+                    for (const t of memberReady) {
+                        if (!t.ready)
+                            continue;
+                        if (seenIds.has(t.taskId))
+                            continue;
+                        seenIds.add(t.taskId);
+                        aggregated.push({
+                            id: t.taskId,
+                            title: t.title,
+                            priority: t.priority,
+                            depends: t.depends,
+                        });
+                    }
+                }
+                // Preserve priority ordering (critical → high → medium → low) then ID.
+                const priorityWeight = {
+                    critical: 4,
+                    high: 3,
+                    medium: 2,
+                    low: 1,
+                };
+                aggregated.sort((a, b) => {
+                    const wa = priorityWeight[a.priority] ?? 0;
+                    const wb = priorityWeight[b.priority] ?? 0;
+                    if (wa !== wb)
+                        return wb - wa;
+                    return a.id.localeCompare(b.id);
+                });
+                let reason;
+                if (aggregated.length === 0) {
+                    if (members.length === 0) {
+                        reason = 'saga has no member epics';
+                    }
+                    else if (aggregatedAllCount === 0) {
+                        reason = 'saga members have no children';
+                    }
+                    else if (aggregatedBlockedCount === aggregatedAllCount) {
+                        reason = 'all saga-member tasks have unmet dependencies';
+                    }
+                    else {
+                        reason = 'no saga-member tasks with unmet dependencies found';
+                    }
                 }
+                // T12000: annotate which ready tasks are admittable now vs deferred so
+                // orchestrators size their fan-out to host capacity (Never-OOM).
+                const admission = await computeAgentAdmission(aggregated.map((t) => t.id));
+                return {
+                    success: true,
+                    data: {
+                        epicId,
+                        readyTasks: aggregated,
+                        total: aggregated.length,
+                        via: 'saga',
+                        sagaMembers: members,
+                        admission,
+                        ...(skippedNested.length > 0 && { sagaNestedSkipped: skippedNested }),
+                        ...(reason !== undefined && { reason }),
+                        ...(depsWarning !== undefined && { depsWarning }),
+                    },
+                };
             }
-            // Preserve priority ordering (critical → high → medium → low) then ID.
-            const priorityWeight = {
-                critical: 4,
-                high: 3,
-                medium: 2,
-                low: 1,
-            };
-            aggregated.sort((a, b) => {
-                const wa = priorityWeight[a.priority] ?? 0;
-                const wb = priorityWeight[b.priority] ?? 0;
-                if (wa !== wb)
-                    return wb - wa;
-                return a.id.localeCompare(b.id);
-            });
+            // Regular epic: walk parentId.
+            const readyTasks = await getReadyTasks(epicId, root, accessor);
+            const ready = readyTasks.filter((t) => t.ready);
+            // T929: when no tasks are ready, include a diagnostic reason so callers
+            // can distinguish "all done" from "all blocked" without a second query.
             let reason;
-            if (aggregated.length === 0) {
-                if (members.length === 0) {
-                    reason = 'saga has no member epics';
-                }
-                else if (aggregatedAllCount === 0) {
-                    reason = 'saga members have no children';
+            if (ready.length === 0) {
+                const all = readyTasks;
+                const blockedCount = all.filter((t) => !t.ready && t.blockers.length > 0).length;
+                if (all.length === 0) {
+                    reason = 'epic has no children';
                 }
-                else if (aggregatedBlockedCount === aggregatedAllCount) {
-                    reason = 'all saga-member tasks have unmet dependencies';
+                else if (blockedCount === all.length) {
+                    reason = 'all children have unmet dependencies';
                 }
                 else {
-                    reason = 'no saga-member tasks with unmet dependencies found';
+                    reason = 'no tasks with unmet dependencies found; check child task statuses';
                 }
             }
+            const readyOut = ready.map((t) => ({
+                id: t.taskId,
+                title: t.title,
+                priority: t.priority,
+                depends: t.depends,
+            }));
             // T12000: annotate which ready tasks are admittable now vs deferred so
             // orchestrators size their fan-out to host capacity (Never-OOM).
-            const admission = await computeAgentAdmission(aggregated.map((t) => t.id));
+            const admission = await computeAgentAdmission(readyOut.map((t) => t.id));
             return {
                 success: true,
                 data: {
                     epicId,
-                    readyTasks: aggregated,
-                    total: aggregated.length,
-                    via: 'saga',
-                    sagaMembers: members,
+                    readyTasks: readyOut,
+                    total: readyOut.length,
+                    via: 'parent',
                     admission,
-                    ...(skippedNested.length > 0 && { sagaNestedSkipped: skippedNested }),
                     ...(reason !== undefined && { reason }),
                     ...(depsWarning !== undefined && { depsWarning }),
                 },
             };
-        }
-        // Regular epic: walk parentId.
-        const readyTasks = await getReadyTasks(epicId, root, accessor);
-        const ready = readyTasks.filter((t) => t.ready);
-        // T929: when no tasks are ready, include a diagnostic reason so callers
-        // can distinguish "all done" from "all blocked" without a second query.
-        let reason;
-        if (ready.length === 0) {
-            const all = readyTasks;
-            const blockedCount = all.filter((t) => !t.ready && t.blockers.length > 0).length;
-            if (all.length === 0) {
-                reason = 'epic has no children';
-            }
-            else if (blockedCount === all.length) {
-                reason = 'all children have unmet dependencies';
-            }
-            else {
-                reason = 'no tasks with unmet dependencies found; check child task statuses';
-            }
-        }
-        const readyOut = ready.map((t) => ({
-            id: t.taskId,
-            title: t.title,
-            priority: t.priority,
-            depends: t.depends,
-        }));
-        // T12000: annotate which ready tasks are admittable now vs deferred so
-        // orchestrators size their fan-out to host capacity (Never-OOM).
-        const admission = await computeAgentAdmission(readyOut.map((t) => t.id));
-        return {
-            success: true,
-            data: {
-                epicId,
-                readyTasks: readyOut,
-                total: readyOut.length,
-                via: 'parent',
-                admission,
-                ...(reason !== undefined && { reason }),
-                ...(depsWarning !== undefined && { depsWarning }),
-            },
-        };
+        });
     }
     catch (err) {
         const code = err.code ?? 'E_GENERAL';
@@ -411,37 +418,40 @@ export async function orchestrateReady(epicId, projectRoot, opts) {
  * @task T4478
  */
 export async function orchestrateNext(epicId, projectRoot) {
-    if (!epicId) {
-        return engineError('E_INVALID_INPUT', 'epicId is required');
-    }
     try {
-        const root = getProjectRoot(projectRoot);
-        const accessor = await getTaskAccessor(root);
-        const nextTask = await getNextTask(epicId, root, accessor);
-        if (!nextTask) {
+        const scope = captureProjectScope(projectRoot ?? getProjectRoot(), worktreeScope.getStore());
+        return await worktreeScope.run(scope, async () => {
+            if (!epicId) {
+                return engineError('E_INVALID_INPUT', 'epicId is required');
+            }
+            const root = scope.worktreeRoot;
+            const accessor = await getTaskAccessor(root);
+            const nextTask = await getNextTask(epicId, root, accessor);
+            if (!nextTask) {
+                return {
+                    success: true,
+                    data: {
+                        epicId,
+                        nextTask: null,
+                        message: 'No tasks ready to spawn. All pending tasks may have unmet dependencies.',
+                    },
+                };
+            }
+            // Get all ready tasks for alternatives
+            const readyTasks = await getReadyTasks(epicId, root, accessor);
+            const ready = readyTasks.filter((t) => t.ready);
             return {
                 success: true,
                 data: {
                     epicId,
-                    nextTask: null,
-                    message: 'No tasks ready to spawn. All pending tasks may have unmet dependencies.',
+                    nextTask: { id: nextTask.taskId, title: nextTask.title, priority: nextTask.priority },
+                    alternatives: ready
+                        .slice(1, 4)
+                        .map((t) => ({ id: t.taskId, title: t.title, priority: t.priority })),
+                    totalReady: ready.length,
                 },
             };
-        }
-        // Get all ready tasks for alternatives
-        const readyTasks = await getReadyTasks(epicId, root, accessor);
-        const ready = readyTasks.filter((t) => t.ready);
-        return {
-            success: true,
-            data: {
-                epicId,
-                nextTask: { id: nextTask.taskId, title: nextTask.title, priority: nextTask.priority },
-                alternatives: ready
-                    .slice(1, 4)
-                    .map((t) => ({ id: t.taskId, title: t.title, priority: t.priority })),
-                totalReady: ready.length,
-            },
-        };
+        });
     }
     catch (err) {
         const code = err.code ?? 'E_GENERAL';
@@ -451,12 +461,10 @@ export async function orchestrateNext(epicId, projectRoot) {
 /**
  * orchestrate.waves - Compute dependency waves
  *
- * For regular epics the wave plan is `getEnrichedWaves(epicId)`. For sagas
- * (Epics labeled `'saga'`, ADR-073), per-member wave plans are computed and
- * merged by wave index: wave N across all members becomes one unified wave N.
- * Members of unequal depth contribute to the trailing waves (longest tail
- * wins). Task IDs are deduplicated; per-wave order preserves the per-member
- * sort.
+ * For regular epics the wave plan is `getEnrichedWaves(epicId)`. Sagas select
+ * their member epics' children and compute one dependency graph across them.
+ * Containment controls selection; explicit hard dependencies control ordering
+ * and current readiness, including dependencies outside the selected population.
  *
  * @param epicId - Epic to compute waves for.
  * @param projectRoot - Optional project root path.
@@ -467,106 +475,64 @@ export async function orchestrateNext(epicId, projectRoot) {
  * @adr ADR-073
  */
 export async function orchestrateWaves(epicId, projectRoot, _opts) {
-    if (!epicId) {
-        return engineError('E_INVALID_INPUT', 'epicId is required');
-    }
     try {
-        const root = getProjectRoot(projectRoot);
-        const accessor = await getTaskAccessor(root);
-        // gh-390 / ADR-073: detect saga shape so we walk the groups relation.
-        const epic = await accessor.loadSingleTask(epicId);
-        if (!epic) {
-            return engineError('E_NOT_FOUND', `Epic ${epicId} not found`);
-        }
-        // T10966: Saga-aware traversal — always auto-detect saga shape.
-        // After T10638, sagas use `type='saga'` with `parent_id` containment.
-        // T10331 (Saga T10326 W2.B): dual-shape saga detection via isSagaShape.
-        const sagaShaped = isSagaShape(epic);
-        if (!sagaShaped) {
-            const result = await getEnrichedWaves(epicId, root, accessor);
-            // T12000: admission over the first actionable (non-completed) wave —
-            // the tasks an orchestrator would spawn next — so the fan-out is sized
-            // to host capacity (Never-OOM).
-            const admission = await computeAgentAdmission(firstActionableWaveTaskIds(result.waves));
-            return {
-                success: true,
-                data: { ...result, via: 'parent', admission },
-            };
-        }
-        // Saga walk: compute per-member waves and merge by index.
-        const memberIds = await resolveSagaMemberIds(accessor, epicId);
-        const members = memberIds ?? [];
-        const skippedNested = [];
-        const perMemberWaves = [];
-        let totalChildren = 0;
-        for (const memberId of members) {
-            const memberTask = await accessor.loadSingleTask(memberId);
+        const scope = captureProjectScope(projectRoot ?? getProjectRoot(), worktreeScope.getStore());
+        return await worktreeScope.run(scope, async () => {
+            if (!epicId) {
+                return engineError('E_INVALID_INPUT', 'epicId is required');
+            }
+            const root = scope.worktreeRoot;
+            const accessor = await getTaskAccessor(root);
+            // gh-390 / ADR-073: detect saga shape so we walk the groups relation.
+            const epic = await accessor.loadSingleTask(epicId);
+            if (!epic) {
+                return engineError('E_NOT_FOUND', `Epic ${epicId} not found`);
+            }
+            // T10966: Saga-aware traversal — always auto-detect saga shape.
+            // After T10638, sagas use `type='saga'` with `parent_id` containment.
             // T10331 (Saga T10326 W2.B): dual-shape saga detection via isSagaShape.
-            if (memberTask && isSagaShape(memberTask)) {
-                skippedNested.push(memberId);
-                continue;
+            const sagaShaped = isSagaShape(epic);
+            if (!sagaShaped) {
+                const result = await getEnrichedWaves(epicId, root, accessor);
+                // T12000: admission over the first actionable (non-completed) wave —
+                // the tasks an orchestrator would spawn next — so the fan-out is sized
+                // to host capacity (Never-OOM).
+                const admission = await computeAgentAdmission(firstActionableWaveTaskIds(result.waves));
+                return {
+                    success: true,
+                    data: { ...result, via: 'parent', admission },
+                };
             }
-            const memberResult = await getEnrichedWaves(memberId, root, accessor);
-            perMemberWaves.push(memberResult.waves);
-            totalChildren += memberResult.totalTasks;
-        }
-        const maxWaves = perMemberWaves.reduce((m, w) => Math.max(m, w.length), 0);
-        const mergedWaves = [];
-        for (let i = 0; i < maxWaves; i++) {
-            const seen = new Set();
-            const mergedTasks = [];
-            let anyInProgress = false;
-            let allCompleted = true;
-            let latestCompletedAt;
-            for (const memberWaves of perMemberWaves) {
-                const wave = memberWaves[i];
-                if (!wave)
+            // Saga containment selects tasks; one graph preserves cross-member dependencies.
+            const memberIds = await resolveSagaMemberIds(accessor, epicId);
+            const members = memberIds ?? [];
+            const skippedNested = [];
+            const selectedMembers = [];
+            for (const memberId of members) {
+                const memberTask = await accessor.loadSingleTask(memberId);
+                // T10331 (Saga T10326 W2.B): dual-shape saga detection via isSagaShape.
+                if (memberTask && isSagaShape(memberTask)) {
+                    skippedNested.push(memberId);
                     continue;
-                if (wave.status === 'in_progress')
-                    anyInProgress = true;
-                if (wave.status !== 'completed')
-                    allCompleted = false;
-                if (wave.completedAt && (!latestCompletedAt || wave.completedAt > latestCompletedAt)) {
-                    latestCompletedAt = wave.completedAt;
-                }
-                for (const t of wave.tasks) {
-                    if (seen.has(t.id))
-                        continue;
-                    seen.add(t.id);
-                    mergedTasks.push(t);
                 }
+                selectedMembers.push(memberId);
             }
-            const mergedStatus = allCompleted
-                ? 'completed'
-                : anyInProgress
-                    ? 'in_progress'
-                    : 'pending';
-            const merged = {
-                waveNumber: i + 1,
-                status: mergedStatus,
-                tasks: mergedTasks,
-                taskIds: mergedTasks.map((t) => t.id),
+            const result = await getEnrichedWaves(epicId, root, accessor, selectedMembers);
+            const admission = await computeAgentAdmission(firstActionableWaveTaskIds(result.waves));
+            return {
+                success: true,
+                data: {
+                    epicId,
+                    waves: result.waves,
+                    totalWaves: result.totalWaves,
+                    totalTasks: result.totalTasks,
+                    via: 'saga',
+                    sagaMembers: members,
+                    admission,
+                    ...(skippedNested.length > 0 && { sagaNestedSkipped: skippedNested }),
+                },
             };
-            if (mergedStatus === 'completed' && latestCompletedAt) {
-                merged.completedAt = latestCompletedAt;
-            }
-            mergedWaves.push(merged);
-        }
-        // T12000: admission over the first actionable merged wave (Never-OOM).
-        const admission = await computeAgentAdmission(firstActionableWaveTaskIds(mergedWaves));
-        return {
-            success: true,
-            data: {
-                epicId,
-                waves: mergedWaves,
-                totalWaves: mergedWaves.length,
-                totalTasks: totalChildren,
-                via: 'saga',
-                sagaMembers: members,
-                admission,
-                ...(skippedNested.length > 0 && { sagaNestedSkipped: skippedNested }),
-            },
-        };
+        });
     }
     catch (err) {
         const code = err.code ?? 'E_GENERAL';
@@ -583,7 +549,7 @@ export async function orchestrateWaves(epicId, projectRoot, _opts) {
  */
 function firstActionableWaveTaskIds(waves) {
     const actionable = waves.find((w) => w.status !== 'completed');
-    return actionable ? [...actionable.taskIds] : [];
+    return actionable ? actionable.tasks.filter((task) => task.ready).map((task) => task.id) : [];
 }
 /**
  * orchestrate.context - Context usage check
@@ -595,14 +561,17 @@ function firstActionableWaveTaskIds(waves) {
  */
 export async function orchestrateContext(epicId, projectRoot) {
     try {
-        const root = getProjectRoot(projectRoot);
-        const tasks = await loadTasks(root);
-        let taskCount = tasks.length;
-        if (epicId) {
-            taskCount = tasks.filter((t) => t.parentId === epicId).length;
-        }
-        const contextData = estimateContext(taskCount, root, epicId);
-        return { success: true, data: contextData };
+        const scope = captureProjectScope(projectRoot ?? getProjectRoot(), worktreeScope.getStore());
+        return await worktreeScope.run(scope, async () => {
+            const root = scope.worktreeRoot;
+            const tasks = await loadTasks(root);
+            let taskCount = tasks.length;
+            if (epicId) {
+                taskCount = tasks.filter((t) => t.parentId === epicId).length;
+            }
+            const contextData = estimateContext(taskCount, root, epicId);
+            return { success: true, data: contextData };
+        });
     }
     catch (err) {
         return engineError('E_GENERAL', err.message);
@@ -617,14 +586,17 @@ export async function orchestrateContext(epicId, projectRoot) {
  * @task T4478
  */
 export async function orchestrateValidate(taskId, projectRoot) {
-    if (!taskId) {
-        return engineError('E_INVALID_INPUT', 'taskId is required');
-    }
     try {
-        const root = getProjectRoot(projectRoot);
-        const accessor = await getTaskAccessor(root);
-        const result = await validateSpawnReadiness(taskId, root, accessor);
-        return { success: true, data: result };
+        const scope = captureProjectScope(projectRoot ?? getProjectRoot(), worktreeScope.getStore());
+        return await worktreeScope.run(scope, async () => {
+            if (!taskId) {
+                return engineError('E_INVALID_INPUT', 'taskId is required');
+            }
+            const root = scope.worktreeRoot;
+            const accessor = await getTaskAccessor(root);
+            const result = await validateSpawnReadiness(taskId, root, accessor);
+            return { success: true, data: result };
+        });
     }
     catch (err) {
         return engineError('E_VALIDATION', err.message);
@@ -656,184 +628,189 @@ const MAX_REPORT_PAGE_SIZE = 200;
  * @task T10631
  */
 export async function orchestrateReport(epicId, projectRoot, params) {
-    if (!epicId) {
-        return engineError('E_INVALID_INPUT', 'epicId is required');
-    }
     try {
-        const root = getProjectRoot(projectRoot);
-        const tasks = await loadTasks(root);
-        const epic = tasks.find((t) => t.id === epicId);
-        if (!epic) {
-            return engineError('E_NOT_FOUND', `Epic ${epicId} not found`);
-        }
-        const children = tasks.filter((t) => t.parentId === epicId);
-        const completedIds = new Set(tasks.filter((t) => t.status === 'done').map((t) => t.id));
-        // Classification buckets
-        const ready = [];
-        const blocked = [];
-        const blockedBy = [];
-        const gateBlocked = [];
-        const invalid = [];
-        // Dependency analysis for invalid detection — swallow errors gracefully
-        let depAnalysis = { missingDependencies: [], circularDependencies: [] };
-        try {
-            depAnalysis = analyzeDependencies(children, tasks);
-        }
-        catch {
-            // Non-fatal: dependency analysis failed, skip invalid classification
-        }
-        const missingDepIds = new Set(depAnalysis.missingDependencies.map((m) => m.missingDep));
-        const circularInvolved = new Set();
-        for (const chain of depAnalysis.circularDependencies) {
-            for (const id of chain)
-                circularInvolved.add(id);
-        }
-        for (const task of children) {
-            // Skip terminal states
-            if (task.status === 'done' || task.status === 'cancelled')
-                continue;
-            const deps = task.depends ?? [];
-            const unmetDeps = deps.filter((d) => !completedIds.has(d));
-            const gates = task.gates ?? {};
-            // --- Invalid classification ---
-            const hasMissingDeps = deps.some((d) => missingDepIds.has(d));
-            const isCircular = circularInvolved.has(task.id);
-            if (hasMissingDeps || isCircular) {
-                const reasons = [];
-                if (hasMissingDeps)
-                    reasons.push('missing-dep');
-                if (isCircular)
-                    reasons.push('circular-dep');
-                invalid.push({
-                    id: task.id,
-                    title: task.title,
-                    priority: task.priority ?? 'medium',
-                    status: task.status,
-                    reason: reasons.join(', '),
-                });
-                continue;
+        const scope = captureProjectScope(projectRoot ?? getProjectRoot(), worktreeScope.getStore());
+        return await worktreeScope.run(scope, async () => {
+            if (!epicId) {
+                return engineError('E_INVALID_INPUT', 'epicId is required');
             }
-            // --- Gate-blocked classification ---
-            const requiredGates = ['implemented', 'testsPassed', 'qaPassed'];
-            const failedGates = requiredGates.filter((g) => gates[g] === false);
-            // A task is gate-blocked only if at least one required gate is explicitly false.
-            // Missing/undefined gates (common for pending tasks) do NOT classify as gate-blocked.
-            if (failedGates.length > 0) {
-                const gateSummary = {};
-                for (const g of requiredGates) {
-                    gateSummary[g] = gates[g] === true;
-                }
-                gateBlocked.push({
-                    id: task.id,
-                    title: task.title,
-                    priority: task.priority ?? 'medium',
-                    status: task.status,
-                    reason: failedGates.length > 0 ? `gates-failed: ${failedGates.join(',')}` : 'gates-incomplete',
-                    gates: gateSummary,
-                });
-                continue;
+            const root = scope.worktreeRoot;
+            const tasks = await loadTasks(root);
+            const epic = tasks.find((t) => t.id === epicId);
+            if (!epic) {
+                return engineError('E_NOT_FOUND', `Epic ${epicId} not found`);
             }
-            // --- Blocked-by classification ---
-            if (unmetDeps.length > 0) {
-                blockedBy.push({
-                    id: task.id,
-                    title: task.title,
-                    priority: task.priority ?? 'medium',
-                    status: task.status,
-                    reason: unmetDeps.join(', '),
-                });
-                // Also add to plain "blocked" for the broader blocked group
-                blocked.push({
+            const children = tasks.filter((t) => t.parentId === epicId);
+            const completedIds = new Set(tasks.filter((t) => t.status === 'done').map((t) => t.id));
+            // Classification buckets
+            const ready = [];
+            const blocked = [];
+            const blockedBy = [];
+            const gateBlocked = [];
+            const invalid = [];
+            // Dependency analysis for invalid detection — swallow errors gracefully
+            let depAnalysis = { missingDependencies: [], circularDependencies: [] };
+            try {
+                depAnalysis = analyzeDependencies(children, tasks);
+            }
+            catch {
+                // Non-fatal: dependency analysis failed, skip invalid classification
+            }
+            const missingDepIds = new Set(depAnalysis.missingDependencies.map((m) => m.missingDep));
+            const circularInvolved = new Set();
+            for (const chain of depAnalysis.circularDependencies) {
+                for (const id of chain)
+                    circularInvolved.add(id);
+            }
+            for (const task of children) {
+                // Skip terminal states
+                if (task.status === 'done' || task.status === 'cancelled')
+                    continue;
+                const deps = task.depends ?? [];
+                const unmetDeps = deps.filter((d) => !completedIds.has(d));
+                const gates = task.gates ?? {};
+                // --- Invalid classification ---
+                const hasMissingDeps = deps.some((d) => missingDepIds.has(d));
+                const isCircular = circularInvolved.has(task.id);
+                if (hasMissingDeps || isCircular) {
+                    const reasons = [];
+                    if (hasMissingDeps)
+                        reasons.push('missing-dep');
+                    if (isCircular)
+                        reasons.push('circular-dep');
+                    invalid.push({
+                        id: task.id,
+                        title: task.title,
+                        priority: task.priority ?? 'medium',
+                        status: task.status,
+                        reason: reasons.join(', '),
+                    });
+                    continue;
+                }
+                // --- Gate-blocked classification ---
+                const requiredGates = ['implemented', 'testsPassed', 'qaPassed'];
+                const failedGates = requiredGates.filter((g) => gates[g] === false);
+                // A task is gate-blocked only if at least one required gate is explicitly false.
+                // Missing/undefined gates (common for pending tasks) do NOT classify as gate-blocked.
+                if (failedGates.length > 0) {
+                    const gateSummary = {};
+                    for (const g of requiredGates) {
+                        gateSummary[g] = gates[g] === true;
+                    }
+                    gateBlocked.push({
+                        id: task.id,
+                        title: task.title,
+                        priority: task.priority ?? 'medium',
+                        status: task.status,
+                        reason: failedGates.length > 0
+                            ? `gates-failed: ${failedGates.join(',')}`
+                            : 'gates-incomplete',
+                        gates: gateSummary,
+                    });
+                    continue;
+                }
+                // --- Blocked-by classification ---
+                if (unmetDeps.length > 0) {
+                    blockedBy.push({
+                        id: task.id,
+                        title: task.title,
+                        priority: task.priority ?? 'medium',
+                        status: task.status,
+                        reason: unmetDeps.join(', '),
+                    });
+                    // Also add to plain "blocked" for the broader blocked group
+                    blocked.push({
+                        id: task.id,
+                        title: task.title,
+                        priority: task.priority ?? 'medium',
+                        status: task.status,
+                        reason: `${unmetDeps.length} unmet dep(s)`,
+                    });
+                    continue;
+                }
+                // --- Ready classification ---
+                ready.push({
                     id: task.id,
                     title: task.title,
                     priority: task.priority ?? 'medium',
                     status: task.status,
-                    reason: `${unmetDeps.length} unmet dep(s)`,
+                    reason: 'ready',
                 });
-                continue;
             }
-            // --- Ready classification ---
-            ready.push({
-                id: task.id,
-                title: task.title,
-                priority: task.priority ?? 'medium',
-                status: task.status,
-                reason: 'ready',
-            });
-        }
-        // Build groups
-        const groups = [
-            {
-                group: 'ready',
-                label: 'Ready — parallel-safe, actionable now',
-                count: ready.length,
-                tasks: ready,
-            },
-            {
-                group: 'blocked',
-                label: 'Blocked — has unmet dependency counts',
-                count: blocked.length,
-                tasks: blocked,
-            },
-            {
-                group: 'blockedBy',
-                label: 'Blocked-by — lists specific blocker task IDs',
-                count: blockedBy.length,
-                tasks: blockedBy,
-            },
-            {
-                group: 'gateBlocked',
-                label: 'Gate-blocked — gates (implemented/testsPassed/qaPassed) not satisfied',
-                count: gateBlocked.length,
-                tasks: gateBlocked,
-            },
-            {
-                group: 'invalid',
-                label: 'Invalid — missing or circular dependencies',
-                count: invalid.length,
-                tasks: invalid,
-            },
-        ];
-        // Pagination
-        const pageSize = Math.min(params?.pageSize ?? DEFAULT_REPORT_PAGE_SIZE, MAX_REPORT_PAGE_SIZE);
-        const page = Math.max(params?.page ?? 1, 1);
-        const totalEntries = groups.reduce((sum, g) => sum + g.count, 0);
-        const totalPages = Math.max(1, Math.ceil(totalEntries / pageSize));
-        // Apply pagination — slice tasks across all groups
-        if (totalEntries > pageSize) {
-            const startIdx = (page - 1) * pageSize;
-            const endIdx = startIdx + pageSize;
-            let globalIdx = 0;
-            for (const group of groups) {
-                const groupStart = globalIdx;
-                const groupEnd = globalIdx + group.tasks.length;
-                if (groupEnd <= startIdx || groupStart >= endIdx) {
-                    // Group entirely outside the current page
-                    group.tasks = [];
-                }
-                else {
-                    const sliceStart = Math.max(0, startIdx - groupStart);
-                    const sliceEnd = Math.min(group.tasks.length, endIdx - groupStart);
-                    group.tasks = group.tasks.slice(sliceStart, sliceEnd);
+            // Build groups
+            const groups = [
+                {
+                    group: 'ready',
+                    label: 'Ready — parallel-safe, actionable now',
+                    count: ready.length,
+                    tasks: ready,
+                },
+                {
+                    group: 'blocked',
+                    label: 'Blocked — has unmet dependency counts',
+                    count: blocked.length,
+                    tasks: blocked,
+                },
+                {
+                    group: 'blockedBy',
+                    label: 'Blocked-by — lists specific blocker task IDs',
+                    count: blockedBy.length,
+                    tasks: blockedBy,
+                },
+                {
+                    group: 'gateBlocked',
+                    label: 'Gate-blocked — gates (implemented/testsPassed/qaPassed) not satisfied',
+                    count: gateBlocked.length,
+                    tasks: gateBlocked,
+                },
+                {
+                    group: 'invalid',
+                    label: 'Invalid — missing or circular dependencies',
+                    count: invalid.length,
+                    tasks: invalid,
+                },
+            ];
+            // Pagination
+            const pageSize = Math.min(params?.pageSize ?? DEFAULT_REPORT_PAGE_SIZE, MAX_REPORT_PAGE_SIZE);
+            const page = Math.max(params?.page ?? 1, 1);
+            const totalEntries = groups.reduce((sum, g) => sum + g.count, 0);
+            const totalPages = Math.max(1, Math.ceil(totalEntries / pageSize));
+            // Apply pagination — slice tasks across all groups
+            if (totalEntries > pageSize) {
+                const startIdx = (page - 1) * pageSize;
+                const endIdx = startIdx + pageSize;
+                let globalIdx = 0;
+                for (const group of groups) {
+                    const groupStart = globalIdx;
+                    const groupEnd = globalIdx + group.tasks.length;
+                    if (groupEnd <= startIdx || groupStart >= endIdx) {
+                        // Group entirely outside the current page
+                        group.tasks = [];
+                    }
+                    else {
+                        const sliceStart = Math.max(0, startIdx - groupStart);
+                        const sliceEnd = Math.min(group.tasks.length, endIdx - groupStart);
+                        group.tasks = group.tasks.slice(sliceStart, sliceEnd);
+                    }
+                    globalIdx = groupEnd;
                 }
-                globalIdx = groupEnd;
             }
-        }
-        return {
-            success: true,
-            data: {
-                epicId,
-                epicTitle: epic.title,
-                totalTasks: children.length,
-                groups,
-                pagination: {
-                    page,
-                    pageSize,
-                    totalPages,
-                    totalEntries,
+            return {
+                success: true,
+                data: {
+                    epicId,
+                    epicTitle: epic.title,
+                    totalTasks: children.length,
+                    groups,
+                    pagination: {
+                        page,
+                        pageSize,
+                        totalPages,
+                        totalEntries,
+                    },
                 },
-            },
-        };
+            };
+        });
     }
     catch (err) {
         const code = err.code ?? 'E_GENERAL';