@yemi33/minions 0.1.2424 → 0.1.2426

package/engine/pipeline.js

@@ -6,9 +6,10 @@
 
 const fs = require('fs');
 const path = require('path');
+const crypto = require('crypto');
 const shared = require('./shared');
 const queries = require('./queries');
-const { safeJson, safeJsonArr, safeJsonNoRestore, safeWrite, safeRead, safeReadDir, uid, log, ts, dateStamp, mutateJsonFileLocked, mutateWorkItems, mutatePipelineRuns, slugify, formatTranscriptEntry, WI_STATUS, WORK_TYPE, PLAN_STATUS, PR_STATUS, PIPELINE_STATUS, STAGE_TYPE, MEETING_STATUS, READ_ONLY_ROOT_TASK_TYPES, ENGINE_DEFAULTS, MINIONS_DIR, isPrdArchived } = shared;
+const { safeJson, safeJsonArr, safeJsonNoRestore, safeWrite, safeRead, safeReadDir, uid, log, ts, dateStamp, mutateJsonFileLocked, mutateWorkItems, mutateScheduleRuns, mutatePipelineRuns, slugify, formatTranscriptEntry, WI_STATUS, WORK_TYPE, WORK_ITEM_PRIORITY, PLAN_STATUS, PR_STATUS, PIPELINE_STATUS, STAGE_TYPE, MEETING_STATUS, READ_ONLY_ROOT_TASK_TYPES, ENGINE_DEFAULTS, MINIONS_DIR, isPrdArchived } = shared;
 const routing = require('./routing');
 const http = require('http');
 const { shouldRunNow } = require('./scheduler');
@@ -19,6 +20,8 @@ const {
   FENCE_CLOSE,
 } = require('./untrusted-fence');
 const smallStateStore = require('./small-state-store');
+const apiValidation = require('./api-validation');
+const scheduler = require('./scheduler');
 
 // All module-relative paths flow through MINIONS_DIR so MINIONS_TEST_DIR
 // (set by test/unit.test.js createTestMinionsDir) consistently redirects
@@ -30,6 +33,668 @@ const NOTES_INBOX_DIR = path.join(MINIONS_DIR, 'notes', 'inbox');
 const NOTES_ARCHIVE_DIR = path.join(MINIONS_DIR, 'notes', 'archive');
 const CONFIG_PATH = path.join(MINIONS_DIR, 'config.json');
 
+const PIPELINE_LIMITS = Object.freeze({
+  id: 64,
+  title: 300,
+  description: 20000,
+  stages: 100,
+  depth: 12,
+  nodes: 2000,
+  collection: 200,
+  resources: 100,
+  endpoint: 2048,
+});
+const PIPELINE_ID_PATTERN = /^[A-Za-z0-9_][A-Za-z0-9._-]*$/;
+const PIPELINE_STAGE_TYPES = Object.freeze(Object.values(STAGE_TYPE));
+const PIPELINE_CONDITION_CHECKS = Object.freeze([
+  'runSucceeded',
+  'noFailedItems',
+  'maxRuns',
+  'allBuildsGreen',
+]);
+const PIPELINE_CONDITION_ACTIONS = Object.freeze([
+  'complete',
+  'continue',
+  'fail',
+  'stop-pipeline',
+]);
+const PIPELINE_API_METHODS = Object.freeze(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
+const PIPELINE_WORK_TYPES = Object.freeze(Object.values(WORK_TYPE));
+
+function _pipelineInputError(message, options = {}) {
+  throw new apiValidation.ApiInputError(message, {
+    code: options.code || 'invalid-pipeline',
+    statusCode: options.statusCode,
+    path: options.path,
+    rejectedValue: options.rejectedValue,
+    allowedValues: options.allowedValues,
+    expected: options.expected,
+  });
+}
+
+function _childPath(pathValue, child) {
+  const base = Array.isArray(pathValue) ? pathValue : [pathValue];
+  return [...base.filter(Boolean), child];
+}
+
+function _validatePlainTree(value, pathValue = 'pipeline', state = null, depth = 0) {
+  const context = state || { nodes: 0, ancestors: new WeakSet() };
+  context.nodes += 1;
+  if (context.nodes > PIPELINE_LIMITS.nodes || depth > PIPELINE_LIMITS.depth) {
+    _pipelineInputError('Pipeline definition is too deeply nested or complex', {
+      code: 'pipeline-too-complex',
+      path: pathValue,
+      rejectedValue: value,
+    });
+  }
+  if (value === undefined || value === null
+      || typeof value === 'string' || typeof value === 'boolean') return;
+  if (typeof value === 'number' && Number.isFinite(value)) return;
+  if (typeof value !== 'object') {
+    _pipelineInputError('Pipeline values must be JSON-compatible', {
+      code: 'invalid-pipeline-value',
+      path: pathValue,
+      rejectedValue: value,
+    });
+  }
+  if (context.ancestors.has(value)) {
+    _pipelineInputError('Pipeline definition must not contain object cycles', {
+      code: 'pipeline-object-cycle',
+      path: pathValue,
+      rejectedValue: value,
+    });
+  }
+  context.ancestors.add(value);
+  try {
+    if (Array.isArray(value)) {
+      if (value.length > PIPELINE_LIMITS.collection) {
+        _pipelineInputError('Pipeline collection is too large', {
+          code: 'pipeline-too-complex',
+          path: pathValue,
+          rejectedValue: value,
+        });
+      }
+      value.forEach((entry, index) => {
+        _validatePlainTree(entry, _childPath(pathValue, index), context, depth + 1);
+      });
+      return;
+    }
+    apiValidation.validatePlainObject(value, { path: pathValue });
+    const keys = Object.keys(value);
+    if (keys.length > PIPELINE_LIMITS.collection) {
+      _pipelineInputError('Pipeline object has too many fields', {
+        code: 'pipeline-too-complex',
+        path: pathValue,
+        rejectedValue: value,
+      });
+    }
+    for (const key of keys) {
+      if (key === '__proto__' || key === 'prototype' || key === 'constructor') {
+        _pipelineInputError('Pipeline definition contains a forbidden object key', {
+          code: 'dangerous-key',
+          path: _childPath(pathValue, key),
+          rejectedValue: key,
+        });
+      }
+      _validatePlainTree(value[key], _childPath(pathValue, key), context, depth + 1);
+    }
+  } finally {
+    context.ancestors.delete(value);
+  }
+}
+
+function validatePipelineIdentifier(id, pathValue = 'id') {
+  const validated = apiValidation.validateIdentifier(id, {
+    path: pathValue,
+    maxLength: PIPELINE_LIMITS.id,
+    pattern: PIPELINE_ID_PATTERN,
+  });
+  if (validated === 'prototype'
+      || Object.prototype.hasOwnProperty.call(Object.prototype, validated)) {
+    _pipelineInputError(`${pathValue} must not use a prototype-sensitive name`, {
+      code: 'invalid-identifier',
+      path: pathValue,
+      rejectedValue: id,
+      expected: 'safe identifier',
+    });
+  }
+  return validated;
+}
+
+function _validatePipelineText(value, pathValue, options = {}) {
+  return apiValidation.validateString(value, {
+    path: pathValue,
+    optional: options.optional === true,
+    allowEmpty: options.allowEmpty !== false,
+    maxLength: options.maxLength || PIPELINE_LIMITS.description,
+  });
+}
+
+function _validateProjectReference(value, pathValue, config) {
+  if (value === undefined || value === null || value === '') return;
+  _validatePipelineText(value, pathValue, { allowEmpty: false, maxLength: 128 });
+  if (value.trim().toLowerCase() === 'central') return;
+  const result = shared.resolveConfiguredProject(value, config || {});
+  if (result.error) {
+    _pipelineInputError(result.error, {
+      code: 'invalid-project',
+      path: pathValue,
+      rejectedValue: value,
+    });
+  }
+}
+
+function _validateAgentReference(value, pathValue, config, options = {}) {
+  if (value === undefined || value === null || value === '') {
+    if (options.required === true) {
+      _pipelineInputError(`${pathValue.join ? pathValue.join('.') : pathValue} must identify a configured agent`, {
+        code: 'invalid-agent',
+        path: pathValue,
+        rejectedValue: value,
+      });
+    }
+    return;
+  }
+  _validatePipelineText(value, pathValue, { allowEmpty: false, maxLength: 128 });
+  if (options.allowAll === true && value === 'all') return;
+  const agents = Object.keys(config?.agents || {});
+  if (!agents.includes(value)) {
+    _pipelineInputError(`Unknown agent "${value}". Known agents: ${agents.join(', ') || '(none)'}`, {
+      code: 'invalid-agent',
+      path: pathValue,
+      rejectedValue: value,
+      allowedValues: agents,
+    });
+  }
+}
+
+function _validateProjectFields(value, pathValue, config) {
+  _validateProjectReference(value.project, _childPath(pathValue, 'project'), config);
+  if (value.projects !== undefined) {
+    apiValidation.validateArray(value.projects, {
+      path: _childPath(pathValue, 'projects'),
+      maxLength: 50,
+      itemValidator(project, context) {
+        _validateProjectReference(project, context.path, config);
+      },
+    });
+  }
+}
+
+function _validateMonitoredResources(resources, pathValue, config) {
+  if (resources === undefined) return;
+  apiValidation.validateArray(resources, {
+    path: pathValue,
+    maxLength: PIPELINE_LIMITS.resources,
+    itemValidator(resource, context) {
+      if (typeof resource === 'string') {
+        _validatePipelineText(resource, context.path, {
+          allowEmpty: false,
+          maxLength: PIPELINE_LIMITS.endpoint,
+        });
+        if (shared.getPrNumber({ id: resource, url: resource }) == null) {
+          _pipelineInputError('Monitored resource must identify a pull request', {
+            code: 'invalid-monitored-resource',
+            path: context.path,
+            rejectedValue: resource,
+          });
+        }
+        return;
+      }
+      apiValidation.validatePlainObject(resource, { path: context.path });
+      if (resource.type !== undefined) {
+        apiValidation.validateEnum(resource.type, {
+          path: _childPath(context.path, 'type'),
+          values: ['pr'],
+        });
+      }
+      const ref = resource.id || resource.label || resource.url;
+      _validatePipelineText(ref, _childPath(context.path, 'id'), {
+        allowEmpty: false,
+        maxLength: PIPELINE_LIMITS.endpoint,
+      });
+      _validateProjectReference(
+        resource.project ?? resource._project,
+        _childPath(context.path, 'project'),
+        config,
+      );
+    },
+  });
+}
+
+function _validateCondition(condition, pathValue) {
+  let check = condition;
+  let value;
+  if (typeof condition === 'object' && condition !== null) {
+    apiValidation.validatePlainObject(condition, { path: pathValue });
+    check = condition.check;
+    value = condition.value;
+  }
+  apiValidation.validateEnum(check, {
+    path: typeof condition === 'object' && condition !== null
+      ? _childPath(pathValue, 'check')
+      : pathValue,
+    values: PIPELINE_CONDITION_CHECKS,
+  });
+  if (check === 'maxRuns' && value !== undefined) {
+    apiValidation.validateInteger(value, { path: _childPath(pathValue, 'value') });
+    apiValidation.validateRange(value, {
+      path: _childPath(pathValue, 'value'),
+      min: 1,
+      max: 1000000,
+    });
+  }
+}
+
+function _validateWorkItemPriority(priority, pathValue) {
+  const error = shared.validateWorkItemPriority(priority);
+  if (!error) return;
+  _pipelineInputError(error.error, {
+    code: error.code,
+    path: pathValue,
+    rejectedValue: error.rejectedValue,
+    allowedValues: error.allowedValues,
+  });
+}
+
+function _validateApiCall(call, pathValue) {
+  apiValidation.validatePlainObject(call, { path: pathValue });
+  const endpoint = _validatePipelineText(call.endpoint, _childPath(pathValue, 'endpoint'), {
+    allowEmpty: false,
+    maxLength: PIPELINE_LIMITS.endpoint,
+  });
+  let normalizedPath;
+  let decodedPath;
+  try {
+    normalizedPath = new URL(endpoint, 'http://localhost').pathname;
+    decodedPath = decodeURIComponent(normalizedPath);
+  } catch {
+    normalizedPath = '';
+    decodedPath = '';
+  }
+  const endpointSegments = decodedPath.split('/');
+  if (!endpoint.startsWith('/api/') || !normalizedPath.startsWith('/api/')
+      || !decodedPath.startsWith('/api/') || /[?#\\]/.test(decodedPath)
+      || endpointSegments.includes('.') || endpointSegments.includes('..')) {
+    _pipelineInputError('Pipeline API endpoint must be a canonical local /api/ path', {
+      code: 'invalid-api-endpoint',
+      path: _childPath(pathValue, 'endpoint'),
+      rejectedValue: endpoint,
+    });
+  }
+  apiValidation.validateEnum(call.method, {
+    path: _childPath(pathValue, 'method'),
+    optional: true,
+    values: PIPELINE_API_METHODS,
+  });
+}
+
+function _validateTaskItem(item, pathValue, config) {
+  apiValidation.validatePlainObject(item, { path: pathValue });
+  _validatePipelineText(item.title, _childPath(pathValue, 'title'), {
+    optional: true,
+    maxLength: PIPELINE_LIMITS.title,
+  });
+  _validatePipelineText(item.description, _childPath(pathValue, 'description'), { optional: true });
+  apiValidation.validateEnum(item.type, {
+    path: _childPath(pathValue, 'type'),
+    optional: true,
+    values: PIPELINE_WORK_TYPES,
+  });
+  _validateWorkItemPriority(item.priority, _childPath(pathValue, 'priority'));
+  _validateAgentReference(item.agent, _childPath(pathValue, 'agent'), config);
+  _validateProjectFields(item, pathValue, config);
+  for (const field of ['agentLock', 'hardAgent']) {
+    apiValidation.validateBoolean(item[field], {
+      path: _childPath(pathValue, field),
+      optional: true,
+    });
+  }
+}
+
+function _rejectStagePayload(stage, fields, pathValue) {
+  for (const field of fields) {
+    if (stage[field] !== undefined) {
+      _pipelineInputError(`Stage type "${stage.type}" does not accept ${field}`, {
+        code: 'invalid-stage-payload',
+        path: _childPath(pathValue, field),
+        rejectedValue: stage[field],
+      });
+    }
+  }
+}
+
+function _validateStage(stage, pathValue, context) {
+  apiValidation.validatePlainObject(stage, { path: pathValue });
+  const stageId = validatePipelineIdentifier(stage.id, _childPath(pathValue, 'id'));
+  if (context.allStageIds.has(stageId)) {
+    _pipelineInputError(`Duplicate pipeline stage id "${stageId}"`, {
+      code: 'duplicate-stage-id',
+      path: _childPath(pathValue, 'id'),
+      rejectedValue: stageId,
+    });
+  }
+  context.allStageIds.add(stageId);
+  apiValidation.validateEnum(stage.type, {
+    path: _childPath(pathValue, 'type'),
+    values: PIPELINE_STAGE_TYPES,
+  });
+  // `allowLegacyDisplayFields` relaxes the title requirement so historical
+  // stored pipeline definitions don't crash discovery. That leniency must NOT
+  // extend to side-effecting stages that consume `stage.title` to name a
+  // persisted record when they carry no per-record collection: a task stage
+  // without `items` and a meeting stage without `meetings` still require a
+  // title, otherwise a malformed stored definition like `{id:"task",type:"task"}`
+  // reaches executeTaskStage/executeMeetingStage and dispatches an UNTITLED
+  // work item / meeting (review PR #966). Schedule stages are already guarded
+  // downstream by validateScheduleDefinition (title required there); plan stages
+  // carry a safe `slugify(stage.title || 'pipeline-plan')` fallback.
+  const titleBacksSideEffect =
+    (stage.type === STAGE_TYPE.TASK && stage.items === undefined)
+    || (stage.type === STAGE_TYPE.MEETING && stage.meetings === undefined);
+  _validatePipelineText(stage.title, _childPath(pathValue, 'title'), {
+    optional: context.allowLegacyDisplayFields === true && !titleBacksSideEffect,
+    allowEmpty: false,
+    maxLength: PIPELINE_LIMITS.title,
+  });
+  _validatePipelineText(stage.description, _childPath(pathValue, 'description'), { optional: true });
+  _validateWorkItemPriority(stage.priority, _childPath(pathValue, 'priority'));
+  _validateAgentReference(stage.agent, _childPath(pathValue, 'agent'), context.config);
+  _validateProjectFields(stage, pathValue, context.config);
+  _validateMonitoredResources(
+    stage.monitoredResources,
+    _childPath(pathValue, 'monitoredResources'),
+    context.config,
+  );
+  for (const field of ['agentLock', 'hardAgent', 'autoApprove']) {
+    apiValidation.validateBoolean(stage[field], {
+      path: _childPath(pathValue, field),
+      optional: true,
+    });
+  }
+  if (stage.dependsOn !== undefined) {
+    apiValidation.validateArray(stage.dependsOn, {
+      path: _childPath(pathValue, 'dependsOn'),
+      maxLength: PIPELINE_LIMITS.stages,
+      itemValidator(dependency, dependencyContext) {
+        validatePipelineIdentifier(dependency, dependencyContext.path);
+      },
+    });
+    if (context.insideParallel === true && stage.dependsOn.length > 0) {
+      _pipelineInputError('Parallel sub-stages cannot declare dependencies', {
+        code: 'unsupported-parallel-dependency',
+        path: _childPath(pathValue, 'dependsOn'),
+        rejectedValue: stage.dependsOn,
+      });
+    }
+  }
+
+  switch (stage.type) {
+    case STAGE_TYPE.TASK:
+      apiValidation.validateEnum(stage.taskType, {
+        path: _childPath(pathValue, 'taskType'),
+        optional: true,
+        values: PIPELINE_WORK_TYPES,
+      });
+      if (stage.count !== undefined) {
+        apiValidation.validateInteger(stage.count, { path: _childPath(pathValue, 'count') });
+        apiValidation.validateRange(stage.count, {
+          path: _childPath(pathValue, 'count'),
+          min: 1,
+          max: PIPELINE_LIMITS.collection,
+        });
+      }
+      if (stage.items !== undefined) {
+        apiValidation.validateArray(stage.items, {
+          path: _childPath(pathValue, 'items'),
+          minLength: 1,
+          maxLength: PIPELINE_LIMITS.collection,
+          itemValidator(item, itemContext) {
+            _validateTaskItem(item, itemContext.path, context.config);
+          },
+        });
+      }
+      break;
+    case STAGE_TYPE.MEETING:
+      if (stage.participants !== undefined) {
+        apiValidation.validateArray(stage.participants, {
+          path: _childPath(pathValue, 'participants'),
+          minLength: 1,
+          maxLength: PIPELINE_LIMITS.collection,
+          itemValidator(participant, participantContext) {
+            _validateAgentReference(
+              participant,
+              participantContext.path,
+              context.config,
+              { allowAll: true, required: true },
+            );
+          },
+        });
+        if (stage.participants.includes('all') && stage.participants.length !== 1) {
+          _pipelineInputError('Meeting participants "all" must be used alone', {
+            code: 'invalid-agent',
+            path: _childPath(pathValue, 'participants'),
+            rejectedValue: stage.participants,
+          });
+        }
+      } else if (Object.keys(context.config?.agents || {}).length === 0) {
+        _pipelineInputError('Meeting stage requires participants or configured agents', {
+          code: 'invalid-agent',
+          path: _childPath(pathValue, 'participants'),
+          rejectedValue: stage.participants,
+        });
+      }
+      if (stage.meetings !== undefined) {
+        apiValidation.validateArray(stage.meetings, {
+          path: _childPath(pathValue, 'meetings'),
+          minLength: 1,
+          maxLength: PIPELINE_LIMITS.collection,
+          itemValidator(meeting, meetingContext) {
+            apiValidation.validatePlainObject(meeting, { path: meetingContext.path });
+            _validatePipelineText(meeting.title, _childPath(meetingContext.path, 'title'), {
+              allowEmpty: false,
+              maxLength: PIPELINE_LIMITS.title,
+            });
+            _validatePipelineText(meeting.agenda, _childPath(meetingContext.path, 'agenda'), {
+              optional: true,
+            });
+          },
+        });
+      }
+      break;
+    case STAGE_TYPE.API: {
+      if (stage.calls !== undefined) {
+        apiValidation.validateArray(stage.calls, {
+          path: _childPath(pathValue, 'calls'),
+          minLength: 1,
+          maxLength: PIPELINE_LIMITS.collection,
+          itemValidator(call, callContext) {
+            _validateApiCall(call, callContext.path);
+          },
+        });
+      } else {
+        _validateApiCall({
+          endpoint: stage.endpoint,
+          method: stage.method,
+          body: stage.body,
+        }, pathValue);
+      }
+      break;
+    }
+    case STAGE_TYPE.SCHEDULE:
+      apiValidation.validateEnum(stage.taskType, {
+        path: _childPath(pathValue, 'taskType'),
+        optional: true,
+        values: PIPELINE_WORK_TYPES,
+      });
+      if (stage.schedules !== undefined) {
+        apiValidation.validateArray(stage.schedules, {
+          path: _childPath(pathValue, 'schedules'),
+          minLength: 1,
+          maxLength: PIPELINE_LIMITS.collection,
+          itemValidator(schedule) {
+            scheduler.validateScheduleDefinition(schedule, { config: context.config });
+          },
+        });
+      } else {
+        scheduler.validateScheduleDefinition({
+          id: _pipelineScheduleId(stage.id, context.pipelineId),
+          cron: stage.cron,
+          title: stage.title,
+          type: stage.taskType || WORK_TYPE.IMPLEMENT,
+          enabled: true,
+        }, { config: context.config });
+      }
+      break;
+    case STAGE_TYPE.CONDITION: {
+      const condition = stage.check !== undefined ? stage.check : stage.condition;
+      _validateCondition(condition, _childPath(pathValue, 'check'));
+      for (const field of ['onMet', 'onUnmet']) {
+        apiValidation.validateEnum(stage[field], {
+          path: _childPath(pathValue, field),
+          optional: true,
+          values: PIPELINE_CONDITION_ACTIONS,
+        });
+      }
+      break;
+    }
+    case STAGE_TYPE.WAIT:
+      _rejectStagePayload(stage, [
+        'calls', 'endpoint', 'method', 'body', 'items', 'meetings',
+        'stages', 'schedules', 'check', 'condition', 'cron',
+      ], pathValue);
+      break;
+    case STAGE_TYPE.PARALLEL:
+      _validateStageList(stage.stages, _childPath(pathValue, 'stages'), {
+        ...context,
+        insideParallel: true,
+      });
+      break;
+    case STAGE_TYPE.PLAN:
+    case STAGE_TYPE.MERGE_PRS:
+      break;
+    default:
+      break;
+  }
+}
+
+function _validateStageList(stages, pathValue, context) {
+  apiValidation.validateArray(stages, {
+    path: pathValue,
+    minLength: 1,
+    maxLength: PIPELINE_LIMITS.stages,
+  });
+  const localStages = new Map();
+  stages.forEach((stage, index) => {
+    _validateStage(stage, _childPath(pathValue, index), context);
+    localStages.set(stage.id, stage);
+  });
+  for (const [stageId, stage] of localStages) {
+    for (const dependency of stage.dependsOn || []) {
+      if (!localStages.has(dependency)) {
+        _pipelineInputError(`Stage "${stageId}" depends on unknown stage "${dependency}"`, {
+          code: 'unknown-stage-dependency',
+          path: _childPath(pathValue, stageId),
+          rejectedValue: dependency,
+        });
+      }
+    }
+  }
+  const visiting = new Set();
+  const visited = new Set();
+  function visit(stageId) {
+    if (visiting.has(stageId)) {
+      _pipelineInputError(`Pipeline stage dependency cycle includes "${stageId}"`, {
+        code: 'pipeline-cycle',
+        path: pathValue,
+        rejectedValue: stageId,
+      });
+    }
+    if (visited.has(stageId)) return;
+    visiting.add(stageId);
+    for (const dependency of localStages.get(stageId).dependsOn || []) visit(dependency);
+    visiting.delete(stageId);
+    visited.add(stageId);
+  }
+  for (const stageId of localStages.keys()) visit(stageId);
+}
+
+function validatePipelineDefinition(definition, options = {}) {
+  _validatePlainTree(definition);
+  apiValidation.validatePlainObject(definition, { path: 'pipeline' });
+  validatePipelineIdentifier(definition.id);
+  _validatePipelineText(definition.title, 'title', {
+    optional: options.allowLegacyDisplayFields === true,
+    allowEmpty: false,
+    maxLength: PIPELINE_LIMITS.title,
+  });
+  _validatePipelineText(definition.description, 'description', { optional: true });
+  apiValidation.validateBoolean(definition.enabled, { path: 'enabled', optional: true });
+  _validateProjectFields(definition, 'pipeline', options.config);
+  _validateMonitoredResources(
+    definition.monitoredResources,
+    'monitoredResources',
+    options.config,
+  );
+  if (definition.trigger !== undefined && definition.trigger !== null) {
+    apiValidation.validatePlainObject(definition.trigger, { path: 'trigger' });
+    const triggerKeys = Object.keys(definition.trigger);
+    if (triggerKeys.some(key => key !== 'cron')) {
+      _pipelineInputError('Pipeline trigger accepts only a cron field', {
+        code: 'invalid-pipeline-trigger',
+        path: 'trigger',
+        rejectedValue: definition.trigger,
+      });
+    }
+    if (triggerKeys.length > 0) {
+      scheduler.validateCronExpression(definition.trigger.cron, { path: 'trigger.cron' });
+    }
+  }
+  if (definition.stopWhen !== undefined && definition.stopWhen !== null) {
+    _validateCondition(definition.stopWhen, 'stopWhen');
+  }
+  _validateStageList(definition.stages, 'stages', {
+    config: options.config || {},
+    pipelineId: definition.id,
+    allowLegacyDisplayFields: options.allowLegacyDisplayFields === true,
+    allStageIds: new Set(),
+  });
+  return definition;
+}
+
+function findPipelineStage(definition, stageId) {
+  for (const stage of definition?.stages || []) {
+    if (stage?.id === stageId) return stage;
+    const nested = findPipelineStage(stage, stageId);
+    if (nested) return nested;
+  }
+  return null;
+}
+
+function _pipelineScheduleId(stageId, pipelineId) {
+  const identity = pipelineId ? `${pipelineId}-${stageId}` : stageId;
+  const hash = crypto.createHash('sha256')
+    .update(`${pipelineId || 'standalone'}\0${stageId}`)
+    .digest('hex')
+    .slice(0, 32);
+  const suffix = `-${hash}-sched`;
+  const base = slugify(identity, scheduler.SCHEDULE_LIMITS.id - suffix.length) || 'stage';
+  return `${base}${suffix}`;
+}
+
+function validatePipelineStoredIdentity(pipelineId, pipeline) {
+  validatePipelineIdentifier(pipelineId, 'pipelineId');
+  const storedId = validatePipelineIdentifier(pipeline?.id);
+  if (storedId !== pipelineId) {
+    _pipelineInputError('Stored pipeline id does not match the requested id', {
+      code: 'pipeline-id-mismatch',
+      path: 'id',
+      rejectedValue: storedId,
+    });
+  }
+  return pipeline;
+}
+
 // ── Pipeline CRUD ────────────────────────────────────────────────────────────
 
 function getPipelines() {
@@ -51,16 +716,20 @@ function getPipelines() {
 }
 
 function getPipeline(id) {
+  validatePipelineIdentifier(id);
   const filePath = path.join(PIPELINES_DIR, id + '.json');
   return safeJson(filePath);
 }
 
-function savePipeline(pipeline) {
+function savePipeline(pipeline, options = {}) {
+  if (options.validate === true) validatePipelineDefinition(pipeline, options);
+  else validatePipelineIdentifier(pipeline?.id);
   if (!fs.existsSync(PIPELINES_DIR)) fs.mkdirSync(PIPELINES_DIR, { recursive: true });
   mutateJsonFileLocked(path.join(PIPELINES_DIR, pipeline.id + '.json'), () => pipeline, { defaultValue: {} });
 }
 
 function deletePipeline(id) {
+  validatePipelineIdentifier(id);
   const filePath = path.join(PIPELINES_DIR, id + '.json');
   if (!fs.existsSync(filePath)) return false;
   try {
@@ -96,6 +765,7 @@ function getActiveRun(pipelineId) {
 }
 
 function startRun(pipelineId, pipeline) {
+  validatePipelineIdentifier(pipelineId, 'pipelineId');
   const runId = `run-${uid()}`;
   const stages = {};
   for (const stage of (pipeline.stages || [])) {
@@ -106,7 +776,9 @@ function startRun(pipelineId, pipeline) {
   let alreadyActive = false;
   mutatePipelineRuns((data) => {
     if (!data[pipelineId]) data[pipelineId] = [];
-    if (data[pipelineId].some(r => r.status === PIPELINE_STATUS.RUNNING || r.status === PIPELINE_STATUS.PAUSED)) {
+    if (data[pipelineId].some(r => r.status === PIPELINE_STATUS.RUNNING
+      || r.status === PIPELINE_STATUS.PAUSED
+      || r.status === PIPELINE_STATUS.WAITING_HUMAN)) {
       alreadyActive = true;
       return data;
     }
@@ -123,6 +795,25 @@ function startRun(pipelineId, pipeline) {
   return run;
 }
 
+function validatePipelineStart(pipelineId, pipeline, config) {
+  validatePipelineStoredIdentity(pipelineId, pipeline);
+  validatePipelineDefinition(pipeline, { config });
+  if (pipeline.enabled === false) {
+    _pipelineInputError(`Pipeline "${pipelineId}" is disabled`, {
+      code: 'pipeline-disabled',
+      statusCode: 409,
+      path: 'enabled',
+      rejectedValue: pipeline.enabled,
+    });
+  }
+  return pipeline;
+}
+
+function startValidatedRun(pipelineId, pipeline, config) {
+  validatePipelineStart(pipelineId, pipeline, config);
+  return startRun(pipelineId, pipeline);
+}
+
 function updateRunStage(pipelineId, runId, stageId, updates) {
   if (updates && Object.prototype.hasOwnProperty.call(updates, 'status')) {
     const validStatuses = Object.values(PIPELINE_STATUS);
@@ -465,7 +1156,7 @@ async function executeStage(stage, run, pipeline, config) {
     case STAGE_TYPE.MERGE_PRS:
       return executeMergePrsStage(resolved, stageState, run, config);
     case STAGE_TYPE.SCHEDULE:
-      return executeScheduleStage(resolved, stageState, config);
+      return executeScheduleStage(resolved, stageState, config, pipeline);
     case STAGE_TYPE.CONDITION:
       return executeConditionStage(resolved, stageState, run, pipeline, config);
     case STAGE_TYPE.WAIT:
@@ -512,7 +1203,7 @@ function executeTaskStage(stage, stageState, run, config, pipeline = {}) {
           title: item.title || stage.title,
           description: item.description || stage.description || '',
           type: wiType,
-          priority: item.priority || stage.priority || 'medium',
+          priority: item.priority || stage.priority || WORK_ITEM_PRIORITY.MEDIUM,
           // Agent is a soft routing hint unless agentLock/hardAgent is set.
           ...(item.agent || stage.agent ? { agent: item.agent || stage.agent } : {}),
           ...(item.agentLock === true || stage.agentLock === true || item.hardAgent === true || stage.hardAgent === true ? { agentLock: true } : {}),
@@ -712,7 +1403,7 @@ async function executePlanStage(stage, stageState, run, config, pipeline = {}) {
           } else if (!workItems.some(w => w.id === wiId)) {
             workItems.push({
               id: wiId, title: `Convert plan to PRD: ${existingPlanFile}`,
-              type: WORK_TYPE.PLAN_TO_PRD, priority: 'high', status: WI_STATUS.PENDING,
+              type: WORK_TYPE.PLAN_TO_PRD, priority: WORK_ITEM_PRIORITY.HIGH, status: WI_STATUS.PENDING,
               planFile: existingPlanFile, created: ts(), createdBy: 'pipeline:' + run.pipelineId,
               // W-mp8ho6w500034a58: PLAN_TO_PRD is read-only — no branch needed.
               _pipelineRun: run.runId, _pipelineStage: stage.id,
@@ -816,7 +1507,7 @@ async function executePlanStage(stage, stageState, run, config, pipeline = {}) {
           id: wiId,
           title: `Convert plan to PRD: ${path.basename(filePath)}`,
           type: WORK_TYPE.PLAN_TO_PRD,
-          priority: 'high',
+          priority: WORK_ITEM_PRIORITY.HIGH,
           status: WI_STATUS.PENDING,
           planFile: path.basename(filePath),
           created: ts(),
@@ -935,9 +1626,17 @@ function executeMergePrsStage(stage, stageState, run, config) {
   return { status: PIPELINE_STATUS.RUNNING, artifacts: { prs: prIds } };
 }
 
-function executeScheduleStage(stage, stageState, config) {
+function executeScheduleStage(stage, stageState, config, pipeline) {
   // Create/update schedules in config
-  const schedules = stage.schedules || [{ id: stage.id + '-sched', cron: stage.cron, title: stage.title, type: routing.normalizeWorkType(stage.taskType, WORK_TYPE.IMPLEMENT) }];
+  const implicit = !stage.schedules;
+  const schedules = stage.schedules || [{
+    id: _pipelineScheduleId(stage.id, pipeline?.id),
+    cron: stage.cron,
+    title: stage.title,
+    type: routing.normalizeWorkType(stage.taskType, WORK_TYPE.IMPLEMENT),
+    ...(pipeline?.id ? { _pipelineId: pipeline.id } : {}),
+    _pipelineStage: stage.id,
+  }];
   // P-bf05-config-write-race — atomic locked write so concurrent
   // addProject/removeProject/dashboard-settings writers can't clobber the
   // schedules we just appended. The prior `safeWrite(CONFIG_PATH, config)`
@@ -946,10 +1645,60 @@ function executeScheduleStage(stage, stageState, config) {
   // don't drop concurrent edits.
   mutateJsonFileLocked(CONFIG_PATH, (cfg) => {
     if (!cfg || typeof cfg !== 'object' || Array.isArray(cfg)) return cfg;
-    for (const sched of schedules) {
-      const existing = (cfg.schedules || []).find(s => s.id === sched.id);
-      if (!existing) {
-        cfg.schedules = cfg.schedules || [];
+    cfg.schedules = cfg.schedules || [];
+    for (const definition of schedules) {
+      const sched = { ...definition };
+      let existingIndex = cfg.schedules.findIndex(candidate => candidate.id === sched.id);
+
+      if (implicit) {
+        const sameDefinition = candidate => candidate
+          && candidate.cron === sched.cron
+          && candidate.title === sched.title
+          && routing.normalizeWorkType(candidate.type, WORK_TYPE.IMPLEMENT) === sched.type;
+        const sameOwner = candidate => sameDefinition(candidate)
+          && candidate._pipelineStage === stage.id
+          && (pipeline?.id ? candidate._pipelineId === pipeline.id : !candidate._pipelineId);
+        const legacyId = `${stage.id}-sched`;
+        const legacyIndex = cfg.schedules.findIndex(candidate => (
+          candidate.id === legacyId && sameDefinition(candidate)
+        ));
+
+        if (legacyIndex >= 0) {
+          const legacy = cfg.schedules[legacyIndex];
+          if (existingIndex >= 0 && sameOwner(cfg.schedules[existingIndex])) {
+            const existing = cfg.schedules[existingIndex];
+            if (legacy.enabled !== undefined) existing.enabled = legacy.enabled;
+            Object.assign(existing, sched);
+            if (legacy.enabled !== undefined) existing.enabled = legacy.enabled;
+            _copyScheduleRunHistory(legacyId, existing.id);
+            cfg.schedules.splice(legacyIndex, 1);
+            continue;
+          }
+          if (existingIndex >= 0) {
+            sched.id = _uniqueScheduleId(cfg.schedules, sched.id);
+            existingIndex = -1;
+          }
+          _copyScheduleRunHistory(legacyId, sched.id);
+          cfg.schedules[legacyIndex] = {
+            ...legacy,
+            ...sched,
+            enabled: legacy.enabled === undefined ? true : legacy.enabled,
+          };
+          continue;
+        }
+
+        if (existingIndex >= 0) {
+          const existing = cfg.schedules[existingIndex];
+          if (sameOwner(existing) || (sameDefinition(existing) && !existing._pipelineId)) {
+            Object.assign(existing, sched);
+            continue;
+          }
+          sched.id = _uniqueScheduleId(cfg.schedules, sched.id);
+          existingIndex = -1;
+        }
+      }
+
+      if (existingIndex < 0) {
         cfg.schedules.push({ ...sched, enabled: true });
       }
     }
@@ -958,6 +1707,25 @@ function executeScheduleStage(stage, stageState, config) {
   return { status: PIPELINE_STATUS.COMPLETED, completedAt: ts() };
 }
 
+function _uniqueScheduleId(schedules, desiredId) {
+  let candidate = desiredId;
+  for (let suffix = 2; schedules.some(schedule => schedule.id === candidate); suffix += 1) {
+    const suffixText = `-${suffix}`;
+    candidate = `${desiredId.slice(0, scheduler.SCHEDULE_LIMITS.id - suffixText.length)}${suffixText}`;
+  }
+  return candidate;
+}
+
+function _copyScheduleRunHistory(fromId, toId) {
+  mutateScheduleRuns((runs) => {
+    if (Object.prototype.hasOwnProperty.call(runs, fromId)
+        && !Object.prototype.hasOwnProperty.call(runs, toId)) {
+      runs[toId] = runs[fromId];
+    }
+    return runs;
+  });
+}
+
 function executeConditionStage(stage, stageState, run, pipeline, config) {
   const check = stage.check || stage.condition;
   if (!check) {
@@ -1179,6 +1947,15 @@ async function discoverPipelineWork(config) {
   const now = new Date();
 
   for (const pipeline of pipelines) {
+    try {
+      validatePipelineDefinition(pipeline, {
+        config,
+        allowLegacyDisplayFields: true,
+      });
+    } catch (error) {
+      log('warn', `Pipeline ${pipeline?.id || '(missing id)'}: invalid definition — skipping (${error.message})`);
+      continue;
+    }
     if (pipeline.enabled === false) continue;
 
     // Check for active run
@@ -1466,11 +2243,22 @@ async function discoverPipelineWork(config) {
 
 module.exports = {
   PIPELINES_DIR,
+  PIPELINE_LIMITS,
+  PIPELINE_STAGE_TYPES,
+  PIPELINE_CONDITION_CHECKS,
+  PIPELINE_CONDITION_ACTIONS,
+  PIPELINE_API_METHODS,
+  validatePipelineIdentifier,
+  validatePipelineDefinition,
+  validatePipelineStoredIdentity,
+  validatePipelineStart,
+  findPipelineStage,
   getPipelines, getPipeline, savePipeline, deletePipeline,
-  getPipelineRuns, getActiveRun, startRun, updateRunStage, upsertRunStage, completeRun,
+  getPipelineRuns, getActiveRun, startRun, startValidatedRun, updateRunStage, upsertRunStage, completeRun,
   discoverPipelineWork,
   evaluateCondition, // exported for testing
   executeTaskStage, executePlanStage, executeScheduleStage, executeApiStage, executeMeetingStage, executeMergePrsStage, isStageComplete, resolveTemplate, // exported for testing
+  _pipelineScheduleId, // exported for testing
   _resolvePipelineProjects, // exported for testing
   _findMeetingsInRun, _findExistingPlanForMeeting, _findExistingPrdForPlan, _canonicalPlanName, // exported for testing
 };