@yemi33/minions 0.1.2424 → 0.1.2426

package/engine/untrusted-fence.js

@@ -64,12 +64,25 @@ function _escapeInnerClosers(content) {
 // Strip characters that would break out of the fence header's source="…"
 // attribute. Conservative whitelist — keep ASCII letters/digits and a small
 // set of punctuation that real source attributes need.
-function _sanitizeSourceToken(value) {
+function _sanitizeSourceValue(value) {
   return String(value == null ? '' : value)
     .replace(/[\r\n\t]+/g, ' ')
     .replace(/[<>"'&`]/g, '')
-    .replace(/\s+/g, '_')
-    .slice(0, 200);
+    .replace(/\s+/g, '_');
+}
+
+function _sanitizeSourceToken(value) {
+  return _sanitizeSourceValue(value).slice(0, 200);
+}
+
+function _sanitizeSourceAttribute(value) {
+  const sanitized = _sanitizeSourceValue(value);
+  if (sanitized.length <= 200) return sanitized;
+  const keyIndex = sanitized.lastIndexOf(':key=');
+  if (keyIndex < 0) return sanitized.slice(0, 200);
+  const keySuffix = sanitized.slice(keyIndex);
+  const prefixLength = Math.max(0, 200 - keySuffix.length);
+  return sanitized.slice(0, prefixLength) + keySuffix;
 }
 
 /**
@@ -77,10 +90,10 @@ function _sanitizeSourceToken(value) {
  * domain-specific order so source-inspection tests can assert literal output.
  *
  * Known shapes:
- *   buildSource('pr-comment', { host, slug, number, author }) →
- *     'pr-comment:<host>:<slug>#<number>:author=<author>'   (GitHub)
- *   buildSource('pr-comment', { host:'ado', org, project, repo, number, author }) →
- *     'pr-comment:ado:<org>/<project>/<repo>!<number>:author=<author>'
+ *   buildSource('pr-comment', { host, slug, number, author, key }) →
+ *     'pr-comment:<host>:<slug>#<number>:author=<author>:key=<key>'   (GitHub)
+ *   buildSource('pr-comment', { host:'ado', org, project, repo, number, author, key }) →
+ *     'pr-comment:ado:<org>/<project>/<repo>!<number>:author=<author>:key=<key>'
  *   buildSource('pinned-note', { path }) → 'pinned-note:<path>'
  *   buildSource('team-notes', { path }) → 'team-notes:<path>'
  *   buildSource('agent-memory', { path }) → 'agent-memory:<path>'
@@ -100,16 +113,17 @@ function buildSource(kind, parts) {
   if (k === 'pr-comment') {
     const host = get('host');
     const author = get('author');
+    const key = parts.key == null ? '' : _sanitizeSourceValue(parts.key).slice(0, 240);
     if (host === 'ado') {
       const ref = [get('org'), get('project'), get('repo')].filter(Boolean).join('/');
       const num = get('number');
       const tail = num ? `${ref}!${num}` : ref;
-      return [k, host, tail, author && `author=${author}`].filter(Boolean).join(':');
+      return [k, host, tail, author && `author=${author}`, key && `key=${key}`].filter(Boolean).join(':');
     }
     const slug = get('slug');
     const num = get('number');
     const tail = num ? `${slug}#${num}` : slug;
-    return [k, host, tail, author && `author=${author}`].filter(Boolean).join(':');
+    return [k, host, tail, author && `author=${author}`, key && `key=${key}`].filter(Boolean).join(':');
   }
 
   if (k === 'pinned-note' || k === 'team-notes' || k === 'agent-memory'
@@ -176,7 +190,7 @@ function wrapUntrusted(content, source) {
     ? `${text}\n\n[truncated ${truncatedBytes} more bytes]`
     : text;
 
-  const srcAttr = _sanitizeSourceToken(source || 'untrusted');
+  const srcAttr = _sanitizeSourceAttribute(source || 'untrusted');
   return `${FENCE_OPEN_PREFIX} source="${srcAttr}">${body}${FENCE_CLOSE}`;
 }
 

package/engine/watch-actions.js

@@ -722,12 +722,17 @@ registerActionType(WATCH_ACTION_TYPE.TRIGGER_PIPELINE, {
     let pipelineMod;
     try { pipelineMod = require('./pipeline'); }
     catch (err) { return { ok: false, summary: `trigger-pipeline: pipeline module unavailable (${err.message})` }; }
-    const pipeline = pipelineMod.getPipeline(pipelineId);
+    let pipeline;
+    try { pipeline = pipelineMod.getPipeline(pipelineId); }
+    catch (err) { return { ok: false, summary: `trigger-pipeline: invalid pipeline id (${err.message})` }; }
     if (!pipeline) return { ok: false, summary: `trigger-pipeline: pipeline ${pipelineId} not found` };
     if (pipelineMod.getActiveRun(pipelineId)) {
       return { ok: false, summary: `trigger-pipeline: ${pipelineId} already has an active run` };
     }
-    const run = pipelineMod.startRun(pipelineId, pipeline);
+    const config = shared.safeJson(path.join(shared.MINIONS_DIR, 'config.json')) || {};
+    let run;
+    try { run = pipelineMod.startValidatedRun(pipelineId, pipeline, config); }
+    catch (err) { return { ok: false, summary: `trigger-pipeline: invalid definition (${err.message})` }; }
     if (!run) return { ok: false, summary: `trigger-pipeline: ${pipelineId} startRun returned null` };
     return { ok: true, summary: `triggered pipeline ${pipelineId} run ${run.runId}`, runId: run.runId };
   },

package/engine/watches.js

@@ -70,11 +70,23 @@ const shared = require('./shared');
 const { mutateWatches, ts, uid, log, writeToInbox,
   WATCH_STATUS, WATCH_TARGET_TYPE, WATCH_CONDITION, WATCH_ABSOLUTE_CONDITIONS } = shared;
 const watchActions = require('./watch-actions');
+const apiValidation = require('./api-validation');
 
 // Default check interval: 5 minutes (300000ms). Engine tick runs every 10s
 // (W-mpxpckey000laa4f), so watches are checked every N ticks where
 // N = ceil(interval / tickInterval).
 const DEFAULT_WATCH_INTERVAL = 300000;
+const WATCH_LIMITS = Object.freeze({
+  minIntervalMs: 60000,
+  maxIntervalMs: Number.MAX_SAFE_INTEGER,
+  maxStopAfter: Number.MAX_SAFE_INTEGER,
+  maxTargetStringLength: 4096,
+  maxTargetBytes: 16 * 1024,
+  maxDescriptionLength: 4000,
+  maxRequirements: 20,
+});
+const WATCH_NOTIFY_MODES = Object.freeze(['inbox', 'none']);
+const WATCH_ON_NOT_MET_MODES = Object.freeze(['notify']);
 
 // P-w12d8f3a — Phase 6.2: per-watch evaluation history is capped at 25
 // entries (oldest-first). Bounded to keep watch state compact:
@@ -104,6 +116,7 @@ const TARGET_TYPES = {};
  * @param {object} spec - { label, conditions, absoluteConditions?, fetchEntity, captureState, evaluate }
  *   - label:              string shown in dashboard pickers
  *   - conditions:         array of condition strings the type accepts
+ *   - validateTarget:     (target, { condition, targetType }) => null-or-error-message
  *   - absoluteConditions: (optional) array of condition keys that should fire
  *                         once and auto-expire when stopAfter=0. Normalized
  *                         into a Set on the spec; defaults to an empty Set.
@@ -128,6 +141,9 @@ function registerTargetType(type, spec) {
   if (!Array.isArray(spec.conditions) || spec.conditions.length === 0) {
     throw new Error(`registerTargetType(${type}): spec.conditions must be a non-empty array`);
   }
+  if (spec.validateTarget !== undefined && typeof spec.validateTarget !== 'function') {
+    throw new Error(`registerTargetType(${type}): spec.validateTarget must be a function`);
+  }
   // W-mp7hg58e000b5212 — normalize absoluteConditions into a Set for fast
   // .has() lookup at evaluate-time. Accepts an array (declarative spec form)
   // or pre-built Set; defaults to empty when omitted. Entries must be a
@@ -173,6 +189,295 @@ function listTargetTypes() {
   }));
 }
 
+function _watchInputError(message, code, path, rejectedValue) {
+  throw new apiValidation.ApiInputError(message, {
+    code,
+    field: Array.isArray(path) ? path[path.length - 1] : path,
+    path,
+    rejectedValue,
+  });
+}
+
+function _validateWatchEnum(value, values, options) {
+  if (!Array.isArray(values) || values.length === 0) {
+    _watchInputError(
+      `${options.path || options.field} has no configured allowed values`,
+      'invalid-enum',
+      options.path || options.field,
+      value,
+    );
+  }
+  return apiValidation.validateEnum(value, { ...options, values });
+}
+
+function _validateWatchTarget(target, targetType, path = 'target', condition = null) {
+  const spec = TARGET_TYPES[targetType];
+  let normalized = target;
+  if (typeof target === 'string') {
+    normalized = apiValidation.validateString(target, {
+      field: 'target',
+      path,
+      trim: true,
+      minLength: 1,
+      maxLength: WATCH_LIMITS.maxTargetStringLength,
+    });
+  } else if (target && typeof target === 'object' && !Array.isArray(target)) {
+    apiValidation.validatePlainObject(target, { field: 'target', path });
+    if (Object.keys(target).length === 0) {
+      _watchInputError(`${path} must not be empty`, 'invalid-target', path, target);
+    }
+    let serialized;
+    try {
+      serialized = JSON.stringify(target);
+    } catch {
+      _watchInputError(`${path} must be JSON-serializable`, 'invalid-target', path, target);
+    }
+    if (Buffer.byteLength(serialized, 'utf8') > WATCH_LIMITS.maxTargetBytes) {
+      _watchInputError(
+        `${path} exceeds the ${WATCH_LIMITS.maxTargetBytes}-byte limit`,
+        'invalid-target',
+        path,
+        target,
+      );
+    }
+  } else {
+    _watchInputError(`${path} must be a non-empty string or object`, 'invalid-target', path, target);
+  }
+
+  if (spec && typeof spec.validateTarget === 'function') {
+    let targetError;
+    try {
+      targetError = spec.validateTarget(normalized, { condition, targetType });
+    } catch (err) {
+      if (apiValidation.isApiInputError(err)) throw err;
+      targetError = err && err.message ? err.message : 'target rejected by target-type validator';
+    }
+    if (targetError === false) targetError = 'target rejected by target-type validator';
+    if (typeof targetError === 'string' && targetError.trim()) {
+      _watchInputError(targetError.trim(), 'invalid-target', path, target);
+    }
+  }
+  return normalized;
+}
+
+function _validateWatchInterval(value, path = 'interval') {
+  if (value === undefined || value === null) return DEFAULT_WATCH_INTERVAL;
+  apiValidation.validateInteger(value, { field: 'interval', path });
+  return apiValidation.validateRange(value, {
+    field: 'interval',
+    path,
+    min: WATCH_LIMITS.minIntervalMs,
+    max: WATCH_LIMITS.maxIntervalMs,
+  });
+}
+
+function _validateWatchStopAfter(value, path = 'stopAfter') {
+  if (value === undefined || value === null) return 0;
+  apiValidation.validateInteger(value, { field: 'stopAfter', path });
+  return apiValidation.validateRange(value, {
+    field: 'stopAfter',
+    path,
+    min: 0,
+    max: WATCH_LIMITS.maxStopAfter,
+  });
+}
+
+function _validateWatchAction(action, path = 'action') {
+  if (action === undefined || action === null) return action ?? null;
+  const priorityError = watchActions.validateActionWorkItemPriority(action);
+  if (priorityError) {
+    throw new apiValidation.ApiInputError(priorityError.error, {
+      code: priorityError.code,
+      field: 'priority',
+      path,
+      rejectedValue: priorityError.rejectedValue,
+      allowedValues: priorityError.allowedValues,
+    });
+  }
+  const actionError = watchActions.validateAction(action);
+  if (actionError) _watchInputError(actionError, 'invalid-action', path, action);
+  return action;
+}
+
+function _validateWatchRequires(requires, path = 'requires') {
+  if (requires === undefined || requires === null) return requires ?? null;
+  const requirementError = _validateRequires(requires);
+  if (requirementError) {
+    _watchInputError(requirementError, 'invalid-requirement', path, requires);
+  }
+  return requires.map(requirement => ({
+    target: requirement.target,
+    targetType: requirement.targetType,
+    condition: requirement.condition,
+  }));
+}
+
+function validateWatchCreateInput(input, config) {
+  apiValidation.validatePlainObject(input, { field: 'body', path: 'body' });
+  const targetType = _validateWatchEnum(input.targetType, Object.keys(TARGET_TYPES).sort(), {
+    field: 'targetType',
+    path: 'targetType',
+  });
+  const condition = _validateWatchEnum(input.condition, [...TARGET_TYPES[targetType].conditions], {
+    field: 'condition',
+    path: 'condition',
+    message: `condition must be one of: ${TARGET_TYPES[targetType].conditions.join(', ')} (for targetType ${targetType})`,
+  });
+  const target = _validateWatchTarget(input.target, targetType, 'target', condition);
+  const interval = _validateWatchInterval(input.interval);
+  const stopAfter = _validateWatchStopAfter(input.stopAfter);
+
+  let owner = input.owner;
+  if (owner === undefined || owner === null || owner === '') owner = 'human';
+  owner = apiValidation.validateIdentifier(owner, { field: 'owner', path: 'owner', trim: true });
+  if (config && typeof config === 'object') {
+    _validateWatchEnum(owner, ['human', ...Object.keys(config.agents || {})], {
+      field: 'owner',
+      path: 'owner',
+    });
+  }
+
+  let project = input.project;
+  if (project === undefined || project === null || project === '') {
+    project = null;
+  } else {
+    project = apiValidation.validateString(project, {
+      field: 'project',
+      path: 'project',
+      trim: true,
+      minLength: 1,
+      maxLength: 128,
+    });
+    if (config && typeof config === 'object') {
+      _validateWatchEnum(
+        project,
+        (config.projects || []).map(candidate => candidate && candidate.name).filter(Boolean),
+        {
+          field: 'project',
+          path: 'project',
+        },
+      );
+    }
+  }
+
+  let description = input.description;
+  if (description === undefined || description === null || description === '') {
+    description = null;
+  } else {
+    description = apiValidation.validateString(description, {
+      field: 'description',
+      path: 'description',
+      trim: true,
+      maxLength: WATCH_LIMITS.maxDescriptionLength,
+    });
+  }
+
+  let notify = input.notify;
+  if (notify === undefined || notify === null || notify === '') notify = 'inbox';
+  notify = _validateWatchEnum(notify, [...WATCH_NOTIFY_MODES], {
+    field: 'notify',
+    path: 'notify',
+  });
+
+  let onNotMet = input.onNotMet;
+  if (onNotMet === undefined || onNotMet === null || onNotMet === '') {
+    onNotMet = null;
+  } else {
+    onNotMet = _validateWatchEnum(onNotMet, [...WATCH_ON_NOT_MET_MODES], {
+      field: 'onNotMet',
+      path: 'onNotMet',
+    });
+  }
+
+  return {
+    target,
+    targetType,
+    condition,
+    interval,
+    owner,
+    description,
+    project,
+    notify,
+    stopAfter,
+    onNotMet,
+    action: _validateWatchAction(input.action),
+    requires: _validateWatchRequires(input.requires),
+  };
+}
+
+function validateWatchUpdateInput(updates, existingWatch = null) {
+  apiValidation.validatePlainObject(updates, { field: 'updates', path: 'updates' });
+  const normalized = { ...updates };
+  if (updates.status !== undefined) {
+    normalized.status = _validateWatchEnum(updates.status, Object.values(WATCH_STATUS), {
+      field: 'status',
+      path: 'status',
+    });
+  }
+  if (updates.interval !== undefined) normalized.interval = _validateWatchInterval(updates.interval);
+  if (updates.stopAfter !== undefined) normalized.stopAfter = _validateWatchStopAfter(updates.stopAfter);
+  if (updates.description !== undefined) {
+    normalized.description = updates.description === null
+      ? null
+      : apiValidation.validateString(updates.description, {
+        field: 'description',
+        path: 'description',
+        trim: true,
+        maxLength: WATCH_LIMITS.maxDescriptionLength,
+      });
+  }
+  if (updates.notify !== undefined) {
+    normalized.notify = _validateWatchEnum(updates.notify, [...WATCH_NOTIFY_MODES], {
+      field: 'notify',
+      path: 'notify',
+    });
+  }
+  if (updates.onNotMet !== undefined) {
+    normalized.onNotMet = updates.onNotMet === null || updates.onNotMet === ''
+      ? null
+      : _validateWatchEnum(updates.onNotMet, [...WATCH_ON_NOT_MET_MODES], {
+        field: 'onNotMet',
+        path: 'onNotMet',
+      });
+  }
+  if (updates.condition !== undefined) {
+    const condition = apiValidation.validateString(updates.condition, {
+      field: 'condition',
+      path: 'condition',
+      trim: true,
+      minLength: 1,
+      maxLength: 128,
+    });
+    normalized.condition = existingWatch
+      ? _validateWatchEnum(condition, [...(TARGET_TYPES[existingWatch.targetType]?.conditions || [])], {
+        field: 'condition',
+        path: 'condition',
+      })
+      : condition;
+    if (existingWatch) {
+      _validateWatchTarget(
+        existingWatch.target,
+        existingWatch.targetType,
+        'target',
+        normalized.condition,
+      );
+    }
+  }
+  if (updates.action !== undefined) normalized.action = _validateWatchAction(updates.action);
+  if (updates.requires !== undefined) normalized.requires = _validateWatchRequires(updates.requires);
+  return normalized;
+}
+
+function validateWatchId(value) {
+  return apiValidation.validateIdentifier(value, {
+    field: 'id',
+    path: 'id',
+    trim: true,
+    maxLength: 128,
+    pattern: /^watch-[A-Za-z0-9_-]+$/,
+  });
+}
+
 /**
  * Read all watches from SQLite.
  * @returns {Array<object>}
@@ -186,44 +491,26 @@ function getWatches() {
  * @param {object} opts - Watch definition
  * @returns {object} - Created watch
  */
-function createWatch({ target, targetType, condition, interval, owner, description, project, notify, stopAfter, onNotMet, action, requires }) {
-  if (!target) throw new Error('target is required');
-  if (!targetType || !TARGET_TYPES[targetType]) {
-    throw new Error(`targetType must be one of: ${Object.keys(TARGET_TYPES).sort().join(', ')}`);
-  }
-  const tt = TARGET_TYPES[targetType];
-  if (!condition || !tt.conditions.includes(condition)) {
-    throw new Error(`condition must be one of: ${tt.conditions.join(', ')} (for targetType ${targetType})`);
-  }
-  if (action !== undefined && action !== null) {
-    const actionErr = watchActions.validateAction(action);
-    if (actionErr) throw new Error(actionErr);
-  }
-  // P-w10b6e2d — Phase 5: validate optional requires[] cross-target join.
-  if (requires !== undefined && requires !== null) {
-    const reqErr = _validateRequires(requires);
-    if (reqErr) throw new Error(reqErr);
-  }
+function createWatch(input, config) {
+  const validated = validateWatchCreateInput(input, config);
 
   const watch = {
     id: 'watch-' + uid(),
-    target,
-    targetType,
-    condition,
-    interval: Math.max(60000, Number(interval) || DEFAULT_WATCH_INTERVAL),
-    owner: owner || 'human',
+    target: validated.target,
+    targetType: validated.targetType,
+    condition: validated.condition,
+    interval: validated.interval,
+    owner: validated.owner,
     status: WATCH_STATUS.ACTIVE,
-    description: description || `Watch ${target} for ${condition}`,
-    project: project || null,
-    notify: notify || 'inbox',
-    stopAfter: Number(stopAfter) || 0,   // 0 = run forever; N = expire after N triggers
-    onNotMet: onNotMet || null,          // null | 'notify' — action per poll when condition not met
-    action: action || null,              // optional follow-up action — see engine/watch-actions.js
+    description: validated.description || `Watch ${validated.target} for ${validated.condition}`,
+    project: validated.project,
+    notify: validated.notify,
+    stopAfter: validated.stopAfter,   // 0 = run forever; N = expire after N triggers
+    onNotMet: validated.onNotMet,     // null | 'notify' — action per poll when condition not met
+    action: validated.action,         // optional follow-up action — see engine/watch-actions.js
     // P-w10b6e2d — Phase 5: optional requires[] — when present every entry
     // must also evaluate truthy for the watch to fire. See evaluateWatch.
-    requires: Array.isArray(requires) ? requires.map(r => ({
-      target: r.target, targetType: r.targetType, condition: r.condition,
-    })) : null,
+    requires: validated.requires,
     triggerCount: 0,
     created_at: ts(),
     last_checked: null,
@@ -252,21 +539,9 @@ function createWatch({ target, targetType, condition, interval, owner, descripti
  */
 function updateWatch(id, updates) {
   if (!id) throw new Error('id is required');
-  // Validate status before entering the lock — reject early, never persist invalid values
-  if (updates.status !== undefined && !Object.values(WATCH_STATUS).includes(updates.status)) {
-    log('warn', `Invalid watch status: ${updates.status}`);
-    return null;
-  }
-  if (updates.action !== undefined && updates.action !== null) {
-    const actionErr = watchActions.validateAction(updates.action);
-    if (actionErr) throw new Error(actionErr);
-  }
-  // P-w10b6e2d — Phase 5: validate requires[] before entering the lock so a
-  // bad shape never lands on disk. `[]` is allowed (clears the join).
-  if (updates.requires !== undefined && updates.requires !== null) {
-    const reqErr = _validateRequires(updates.requires);
-    if (reqErr) throw new Error(reqErr);
-  }
+  const existing = getWatches().find(watch => watch.id === id);
+  const normalized = validateWatchUpdateInput(updates, existing);
+  if (!existing) return null;
   let found = null;
   mutateWatches((watches) => {
     const watch = watches.find(w => w.id === id);
@@ -274,7 +549,7 @@ function updateWatch(id, updates) {
     // Only allow safe field updates
     const allowed = ['status', 'interval', 'description', 'notify', 'stopAfter', 'onNotMet', 'condition', 'action', 'requires'];
     for (const key of allowed) {
-      if (updates[key] !== undefined) watch[key] = updates[key];
+      if (normalized[key] !== undefined) watch[key] = normalized[key];
     }
     found = { ...watch };
     return watches;
@@ -376,23 +651,32 @@ function evaluateWatch(watch, state) {
  */
 function _validateRequires(requires) {
   if (!Array.isArray(requires)) return 'requires must be an array of {target, targetType, condition}';
+  if (requires.length > WATCH_LIMITS.maxRequirements) {
+    return `requires must contain at most ${WATCH_LIMITS.maxRequirements} entries`;
+  }
+  const seen = new Set();
   for (let i = 0; i < requires.length; i++) {
     const r = requires[i];
     if (!r || typeof r !== 'object' || Array.isArray(r)) {
       return `requires[${i}] must be a {target, targetType, condition} object`;
     }
-    if (!r.target || typeof r.target !== 'string') {
-      return `requires[${i}].target is required (non-empty string)`;
-    }
     if (!r.targetType || !TARGET_TYPES[r.targetType]) {
       return `requires[${i}].targetType must be one of: ${Object.keys(TARGET_TYPES).sort().join(', ')}`;
     }
     if (!r.condition || !TARGET_TYPES[r.targetType].conditions.includes(r.condition)) {
       return `requires[${i}].condition must be one of: ${TARGET_TYPES[r.targetType].conditions.join(', ')} (for targetType ${r.targetType})`;
     }
+    try {
+      _validateWatchTarget(r.target, r.targetType, `requires[${i}].target`, r.condition);
+    } catch (err) {
+      return err && err.message ? err.message : `requires[${i}].target is invalid`;
+    }
     if (r.requires !== undefined) {
       return `requires[${i}] must not contain a nested 'requires' field (depth cap is 1)`;
     }
+    const identity = JSON.stringify([r.targetType, r.target, r.condition]);
+    if (seen.has(identity)) return `requires[${i}] duplicates an earlier requirement`;
+    seen.add(identity);
   }
   return null;
 }
@@ -720,6 +1004,10 @@ function _captureState(watch, state) {
 
 // ── Built-in target type registrations ───────────────────────────────────────
 
+function _validateStringTarget(target) {
+  return typeof target === 'string' ? null : 'target must be a non-empty string identifier';
+}
+
 // PR — pull request status / build / comments / votes
 registerTargetType(WATCH_TARGET_TYPE.PR, {
   label: 'Pull Request',
@@ -742,6 +1030,7 @@ registerTargetType(WATCH_TARGET_TYPE.PR, {
     WATCH_CONDITION.MERGED, WATCH_CONDITION.BUILD_FAIL, WATCH_CONDITION.BUILD_PASS,
     WATCH_CONDITION.READY_FOR_MERGE,
   ],
+  validateTarget: _validateStringTarget,
   // W-mqa63opd000ha836 — zombie-watch janitor: once a PR reaches a terminal
   // status (merged / closed / abandoned), most PR conditions can never fire
   // again so the watch should auto-expire instead of polling forever.
@@ -894,6 +1183,7 @@ registerTargetType(WATCH_TARGET_TYPE.WORK_ITEM, {
     WATCH_CONDITION.COMPLETED, WATCH_CONDITION.FAILED,
     WATCH_CONDITION.RETRY_LIMIT_REACHED,
   ],
+  validateTarget: _validateStringTarget,
   fetchEntity: (target, state) => (state.workItems || []).find(w => w.id === target) || null,
   // P-w2c8d1e7 — Phase 1.2: surface retry count, pending-reason, and branch
   // for upcoming stalled / branch-aware predicates. `retries` aliases the
@@ -984,6 +1274,7 @@ registerTargetType(WATCH_TARGET_TYPE.MEETING, {
   description: 'Watch a meeting for conclusion or status changes',
   conditions: [WATCH_CONDITION.CONCLUDED, WATCH_CONDITION.STATUS_CHANGE, WATCH_CONDITION.ANY],
   absoluteConditions: [WATCH_CONDITION.CONCLUDED],
+  validateTarget: _validateStringTarget,
   fetchEntity: (target, state) => (state.meetings || []).find(m => m && m.id === target) || null,
   captureState: (m) => ({ status: m.status }),
   evaluate: (condition, m, prevState, target) => {
@@ -1058,6 +1349,7 @@ registerTargetType(WATCH_TARGET_TYPE.PLAN, {
     WATCH_CONDITION.APPROVED, WATCH_CONDITION.REJECTED, WATCH_CONDITION.COMPLETED,
     WATCH_CONDITION.ALL_ITEMS_DONE, WATCH_CONDITION.ITEM_FAILED_N_TIMES,
   ],
+  validateTarget: _validateStringTarget,
   fetchEntity: _findPlan,
   // P-w2c8d1e7 — Phase 1.2: surface item progress derived from the PRD's
   // missing_features array so plan-level predicates (e.g. all-items-done)
@@ -1136,6 +1428,7 @@ registerTargetType(WATCH_TARGET_TYPE.SCHEDULE, {
   // W-mp7hg58e000b5212 — schedule has no absolute conditions today; all of
   // its keywords are change-based (RAN/ENABLED/DISABLED detect transitions).
   absoluteConditions: [],
+  validateTarget: _validateStringTarget,
   fetchEntity: _findSchedule,
   // P-w2c8d1e7 — Phase 1.2: surface next_run as null. Cron parsing in
   // engine/scheduler.js exposes parseCronExpr/.matches() but not a
@@ -1221,6 +1514,7 @@ registerTargetType(WATCH_TARGET_TYPE.PIPELINE, {
   ],
   // W-mp7hg58e000b5212 — per-target absolute (fire-once when stopAfter=0).
   absoluteConditions: [WATCH_CONDITION.COMPLETED, WATCH_CONDITION.FAILED],
+  validateTarget: _validateStringTarget,
   fetchEntity: _findPipelineLatestRun,
   // P-w2c8d1e7 — Phase 1.2: surface current_stage_id (first non-terminal
   // stage in declaration order) for stage-targeted predicates.
@@ -1315,6 +1609,7 @@ registerTargetType(WATCH_TARGET_TYPE.DISPATCH, {
   ],
   // W-mp7hg58e000b5212 — per-target absolute (fire-once when stopAfter=0).
   absoluteConditions: [WATCH_CONDITION.COMPLETED, WATCH_CONDITION.FAILED],
+  validateTarget: _validateStringTarget,
   fetchEntity: _findDispatchEntry,
   captureState: (e) => ({ status: e.status || e._list || null, list: e._list || null }),
   evaluate: (condition, e, prevState, target) => {
@@ -1359,6 +1654,7 @@ registerTargetType(WATCH_TARGET_TYPE.AGENT, {
   // W-mp7hg58e000b5212 — agent has no absolute conditions today; all of its
   // keywords are change-based.
   absoluteConditions: [],
+  validateTarget: _validateStringTarget,
   fetchEntity: _findAgent,
   // P-w2c8d1e7 — Phase 1.2: surface currentDispatchId so predicates can
   // distinguish "agent now working on a different dispatch" from a plain
@@ -1437,10 +1733,16 @@ _loadPluginTargetTypes();
 
 module.exports = {
   DEFAULT_WATCH_INTERVAL,
+  WATCH_LIMITS,
+  WATCH_NOTIFY_MODES,
+  WATCH_ON_NOT_MET_MODES,
   getWatches,
   createWatch,
   updateWatch,
   deleteWatch,
+  validateWatchCreateInput,
+  validateWatchUpdateInput,
+  validateWatchId,
   evaluateWatch,
   checkWatches,
   registerTargetType,