fix(maestro): validate resolved numeric strings before coercion

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Author: thymikee

src/compat/maestro/__tests__/engine-flow.test.ts

@@ -1,6 +1,31 @@
 import { expect, test } from 'vitest';
 import { resolveMaestroTimingPolicy } from '../compatibility-policy.ts';
+import { resolveNumeric } from '../engine-flow.ts';
 
 test('uses the Maestro-compatible extended wait default', () => {
   expect(resolveMaestroTimingPolicy().extendedWaitUntilTimeoutMs).toBe(17_000);
 });
+
+test('resolveNumeric coerces valid resolved strings and numbers', () => {
+  expect(resolveNumeric('42', 'x', {})).toBe(42);
+  expect(resolveNumeric('3.5', 'x', {})).toBe(3.5);
+  expect(resolveNumeric(3.5, 'x', {})).toBe(3.5);
+  expect(resolveNumeric('0', 'x', { integer: true, nonNegative: true })).toBe(0);
+  expect(resolveNumeric('5', 'x', { integer: true, positive: true })).toBe(5);
+  expect(resolveNumeric(5, 'x', { integer: true, positive: true })).toBe(5);
+  expect(resolveNumeric(undefined, 'x', {})).toBeUndefined();
+});
+
+test('resolveNumeric rejects blank, whitespace, and malformed resolved strings', () => {
+  expect(() => resolveNumeric('', 'x', {})).toThrow(/must be a finite number/);
+  expect(() => resolveNumeric('   ', 'x', {})).toThrow(/must be a finite number/);
+  expect(() => resolveNumeric('', 'x', { integer: true, nonNegative: true })).toThrow(
+    /must be a non-negative integer/,
+  );
+  expect(() => resolveNumeric('  ', 'x', { integer: true, nonNegative: true })).toThrow(
+    /must be a non-negative integer/,
+  );
+  expect(() => resolveNumeric('abc', 'x', {})).toThrow(/must be a finite number/);
+  expect(() => resolveNumeric('1.2.3', 'x', {})).toThrow(/must be a finite number/);
+  expect(() => resolveNumeric('1.5', 'x', { integer: true })).toThrow(/must be an integer/);
+});

src/compat/maestro/__tests__/runtime-port.test.ts

@@ -421,4 +421,23 @@ describe('MaestroRuntimePort', () => {
       input: { durationMs: 250 },
     });
   });
+
+  test('rejects blank or whitespace resolved numeric option values with a clear error', async () => {
+    const operations = makeOperations();
+    const program = parseMaestroProgram(
+      '---\n- extendedWaitUntil:\n    visible: Ready\n    timeout: ${TIMEOUT}\n',
+    );
+
+    await expect(
+      executeMaestroProgram(program, createMaestroRuntimePort(operations), {
+        env: { TIMEOUT: '' },
+      }),
+    ).rejects.toThrow(/extendedWaitUntil\.timeout must be a finite number/);
+
+    await expect(
+      executeMaestroProgram(program, createMaestroRuntimePort(operations), {
+        env: { TIMEOUT: '   ' },
+      }),
+    ).rejects.toThrow(/extendedWaitUntil\.timeout must be a finite number/);
+  });
 });

src/compat/maestro/engine-flow.ts

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import { AppError } from '../../kernel/errors.ts';
 import { createRequestCanceledError } from '../../request/cancel.ts';
+import { INTEGER_STRING_PATTERN, NUMERIC_STRING_PATTERN } from './program-ir-values.ts';
 import type {
   MaestroCommand,
   MaestroProgram,
@@ -40,7 +41,10 @@ export function resolveNumeric(
   constraints: ResolveNumericConstraints = {},
 ): number | undefined {
   if (value === undefined) return undefined;
-  const num = typeof value === 'number' ? value : Number(value);
+  const num =
+    typeof value === 'number'
+      ? value
+      : Number(parseResolvedNumericString(value, name, constraints));
   const description = resolveNumericDescription(constraints);
   if (!Number.isFinite(num)) {
     throw new AppError('INVALID_ARGS', `Maestro ${name} must be ${description}.`);
@@ -57,13 +61,26 @@ export function resolveNumeric(
   return num;
 }
 
+function parseResolvedNumericString(
+  value: string,
+  name: string,
+  constraints: ResolveNumericConstraints,
+): string {
+  const description = resolveNumericDescription(constraints);
+  const pattern = constraints.integer ? INTEGER_STRING_PATTERN : NUMERIC_STRING_PATTERN;
+  if (!pattern.test(value)) {
+    throw new AppError('INVALID_ARGS', `Maestro ${name} must be ${description}.`);
+  }
+  return value;
+}
+
 export function readIterationCount(
   value: number | string | undefined,
   fallback: number,
   context: MaestroExecutionContext,
   name: string,
 ): number {
-  const resolved = value === undefined ? fallback : Number(context.resolve(String(value)));
+  const resolved = value === undefined ? fallback : context.resolve(String(value));
   return resolveNumeric(resolved, name, { integer: true, nonNegative: true }) ?? fallback;
 }
 

src/compat/maestro/program-ir-values.ts

@@ -200,8 +200,8 @@ export function readOptionalBoolean(
 }
 
 const VARIABLE_PATTERN = /^\$\{[A-Za-z_][A-Za-z0-9_.]*\}$/;
-const NUMERIC_STRING_PATTERN = /^-?\d+(\.\d+)?$/;
-const INTEGER_STRING_PATTERN = /^-?\d+$/;
+export const NUMERIC_STRING_PATTERN = /^-?\d+(\.\d+)?$/;
+export const INTEGER_STRING_PATTERN = /^-?\d+$/;
 
 type NumericScalarConstraints = {
   integer?: boolean;