fix: reject selector-shaped wait arguments instead of reading them as text

`wait <condition> '<selector>' [timeoutMs]` (e.g. `wait open 'label="Open"' 25000`,
`wait exists 'label="x"' 100`) and any unrecognized `key=value` token used to fall
through parseWaitPositionals' text fallback and wait out the full timeout for
literal text that could never appear on screen — reading as a false "element
absent" instead of the caller's own argument mistake (#1035 is the sibling fix
for click/press/fill/get).

parseWaitPositionals now returns a typed `invalid` variant whenever a positional
token is selector-shaped (a recognized key, or an unrecognized key=value) but the
list doesn't form a valid selector expression, or a valid selector prefix is
followed by unquoted trailing tokens. The message names the offending token,
points condition words (exists/present/appears/gone/disappears) at the selector
form, and always offers the explicit `wait text '<text>'` escape hatch. Bare text
(single- and multi-word) and the explicit `text` keyword form are unaffected.

Excluding `invalid` from the type consumed by selector-runtime's toWaitTarget
makes the remaining kind-by-kind narrowing exhaustive without a runtime fallback
branch.

Author: thymikee

src/commands/capture/wait.ts

@@ -113,6 +113,9 @@ function readWaitOptionsFromPositionals(
       ...readTimeoutOption(parsed.timeoutMs),
     };
   }
+  if (parsed.kind === 'invalid') {
+    throw new AppError('INVALID_ARGS', parsed.message);
+  }
   return {
     ...base,
     selector: parsed.selectorExpression,

src/core/wait-positionals.test.ts

@@ -0,0 +1,194 @@
+/**
+ * #1800: a positional list shaped like a selector (a recognized key, or an
+ * unrecognized `key=value`) must never silently degrade to a `text` wait —
+ * that degradation is exactly the shape that reads as "element absent" after
+ * a full timeout instead of the caller's own argument mistake. See #1035 for
+ * the sibling fix on click/press/fill/get.
+ */
+import assert from 'node:assert/strict';
+import fc from 'fast-check';
+import { test } from 'vitest';
+import { isValidSelectorExpression, SELECTOR_KEY_NAMES } from '@agent-device/selectors';
+import { PROPERTY_RUNS } from '../__tests__/test-utils/index.ts';
+import { parseWaitPositionals, resolveWaitBudgetMs } from './wait-positionals.ts';
+
+function assertInvalid(args: string[], messageFragment: string) {
+  const result = parseWaitPositionals(args);
+  assert.ok(result, `expected a result for ${JSON.stringify(args)}`);
+  assert.equal(result.kind, 'invalid');
+  if (result.kind !== 'invalid') return;
+  assert.ok(
+    result.message.includes(messageFragment),
+    `expected message to include ${JSON.stringify(messageFragment)}, got ${JSON.stringify(result.message)}`,
+  );
+}
+
+// --- the issue's reproduction shapes -----------------------------------
+
+test('a condition word followed by a selector-shaped value is rejected, not read as text (#1800 repro)', () => {
+  const result = parseWaitPositionals(['open', 'label="Open"', '25000']);
+  assert.ok(result);
+  assert.notEqual(result.kind, 'text');
+  assertInvalid(['open', 'label="Open"', '25000'], 'label="Open"');
+});
+
+test('"exists" followed by a selector-shaped value is rejected and points at the selector form', () => {
+  assertInvalid(['exists', 'label="x"', '100'], "wait 'visible");
+});
+
+test('unknown selector key is rejected with the supported-key list, not read as text', () => {
+  const result = parseWaitPositionals(['lbl="x"', '100']);
+  assert.ok(result);
+  assert.equal(result.kind, 'invalid');
+  if (result.kind !== 'invalid') return;
+  assert.equal(result.reason, 'unknown-selector-key');
+  assert.ok(result.message.includes('lbl'));
+  assert.ok(result.message.includes('label='));
+});
+
+// --- still-valid selector forms are untouched ---------------------------
+
+test('a valid selector still parses as selector', () => {
+  const result = parseWaitPositionals(['label="Open"', '5000']);
+  assert.deepEqual(result, {
+    kind: 'selector',
+    selectorExpression: 'label="Open"',
+    timeoutMs: 5000,
+  });
+});
+
+test('"visible" leading a valid selector still parses as selector (boolean key, not a condition word)', () => {
+  const result = parseWaitPositionals(['visible', 'label="Open"', '25000']);
+  assert.deepEqual(result, {
+    kind: 'selector',
+    selectorExpression: 'visible label="Open"',
+    timeoutMs: 25000,
+  });
+});
+
+// --- trailing tokens after a valid selector prefix are rejected too -----
+
+test('a valid selector prefix followed by an unquoted extra word is rejected, not merged into text', () => {
+  assertInvalid(['label="Open"', 'foo', '5000'], 'extra arguments');
+});
+
+// --- bare text keeps working ---------------------------------------------
+
+test('bare single-word text still parses as text', () => {
+  const result = parseWaitPositionals(['Continue', '1500']);
+  assert.deepEqual(result, { kind: 'text', text: 'Continue', timeoutMs: 1500 });
+});
+
+test('bare multi-word text still parses as text', () => {
+  const result = parseWaitPositionals(['Sign', 'in', '2000']);
+  assert.deepEqual(result, { kind: 'text', text: 'Sign in', timeoutMs: 2000 });
+});
+
+test('explicit "text" keyword form bypasses selector-shape rejection entirely', () => {
+  // Even though "label=Open" is selector-shaped, the explicit `text` keyword is the caller's
+  // unambiguous escape hatch and must always win.
+  const result = parseWaitPositionals(['text', 'label=Open', '5000']);
+  assert.deepEqual(result, { kind: 'text', text: 'label=Open', timeoutMs: 5000 });
+});
+
+test('free prose containing a bare "=" with no key stays literal text', () => {
+  const result = parseWaitPositionals(['Total', '=', '5', '3000']);
+  assert.deepEqual(result, { kind: 'text', text: 'Total = 5', timeoutMs: 3000 });
+});
+
+// --- documented boundary: a bare selector-key word alone is rejected, not text ---
+
+test('a single word that IS a recognized selector key is rejected rather than read as literal text', () => {
+  // "id" alone cannot become a valid selector (it needs a value), but it also must not silently
+  // become literal wait text — an agent that meant the word "id" has to say so via `wait text`.
+  assertInvalid(['id', '3000'], "wait text 'id'");
+});
+
+// --- resolveWaitBudgetMs stays sane for the new variant -------------------
+
+test('resolveWaitBudgetMs returns null for a rejected selector-shaped positional list', () => {
+  assert.equal(resolveWaitBudgetMs(['open', 'label="Open"', '25000']), null);
+});
+
+// --- properties over examples ---------------------------------------------
+
+const TEXT_SELECTOR_KEYS = SELECTOR_KEY_NAMES.filter((key) => !isValidSelectorExpression(key));
+const BOOLEAN_SELECTOR_KEYS = SELECTOR_KEY_NAMES.filter((key) => isValidSelectorExpression(key));
+
+const selectorValueArb = fc.oneof(
+  fc.constantFrom('Open', 'Sign in', "it's", 'a || b', 'key=value'),
+  fc.string({ minLength: 1, maxLength: 8 }).filter((value) => value.trim().length > 0),
+);
+
+/** One token of a generated, guaranteed-valid selector expression. */
+const selectorTokenArb: fc.Arbitrary<string> = fc.oneof(
+  fc
+    .record({ key: fc.constantFrom(...TEXT_SELECTOR_KEYS), value: selectorValueArb })
+    .map(({ key, value }) => `${key}=${JSON.stringify(value)}`),
+  fc.constantFrom(...BOOLEAN_SELECTOR_KEYS),
+);
+
+const validSelectorTokensArb: fc.Arbitrary<string[]> = fc.array(selectorTokenArb, {
+  minLength: 1,
+  maxLength: 3,
+});
+
+test('property: a generated valid selector expression never parses as text or invalid', () => {
+  fc.assert(
+    fc.property(validSelectorTokensArb, (tokens) => {
+      const result = parseWaitPositionals(tokens);
+      assert.ok(result);
+      assert.equal(result.kind, 'selector');
+    }),
+    { numRuns: PROPERTY_RUNS },
+  );
+});
+
+const plainWordArb = fc
+  .string({ minLength: 1, maxLength: 6 })
+  .filter(
+    (token) =>
+      token.trim().length > 0 &&
+      !token.includes('=') &&
+      !token.startsWith('@') &&
+      token !== 'text' &&
+      token !== 'stable' &&
+      Number.isNaN(Number(token)),
+  );
+
+const recognizedKeyValueTokenArb: fc.Arbitrary<string> = fc
+  .record({ key: fc.constantFrom(...SELECTOR_KEY_NAMES), value: selectorValueArb })
+  .map(({ key, value }) => `${key}=${JSON.stringify(value)}`);
+
+const unrecognizedKeyValueTokenArb: fc.Arbitrary<string> = fc
+  .record({
+    key: fc
+      .string({ minLength: 1, maxLength: 8 })
+      .filter(
+        (key) =>
+          /^[a-zA-Z][a-zA-Z0-9]*$/.test(key) &&
+          !SELECTOR_KEY_NAMES.includes(key.toLowerCase() as (typeof SELECTOR_KEY_NAMES)[number]),
+      ),
+    value: selectorValueArb,
+  })
+  .map(({ key, value }) => `${key}=${JSON.stringify(value)}`);
+
+const keyValueShapedTokenArb = fc.oneof(recognizedKeyValueTokenArb, unrecognizedKeyValueTokenArb);
+
+test('property: any positional list containing a key=value-shaped token never parses as text', () => {
+  fc.assert(
+    fc.property(
+      fc.array(plainWordArb, { maxLength: 3 }),
+      keyValueShapedTokenArb,
+      fc.nat({ max: 3 }),
+      (plainTokens, kvToken, insertAtRaw) => {
+        const insertAt = Math.min(insertAtRaw, plainTokens.length);
+        const tokens = [...plainTokens.slice(0, insertAt), kvToken, ...plainTokens.slice(insertAt)];
+        const result = parseWaitPositionals(tokens);
+        assert.ok(result);
+        assert.notEqual(result.kind, 'text');
+      },
+    ),
+    { numRuns: PROPERTY_RUNS },
+  );
+});

src/core/wait-positionals.ts

@@ -1,39 +1,152 @@
 import { parseTimeout } from '../utils/parse-timeout.ts';
-import { isValidSelectorExpression, splitSelectorFromArgs } from '@agent-device/selectors';
+import {
+  detectUnknownSelectorKeyToken,
+  isRoleHintWord,
+  isSelectorToken,
+  isValidSelectorExpression,
+  SELECTOR_KEY_NAMES,
+  splitSelectorFromArgs,
+} from '@agent-device/selectors';
+
+export type WaitInvalidReason = 'unknown-selector-key' | 'selector-shaped-text';
 
 export type WaitParsed =
   | { kind: 'sleep'; durationMs: number }
   | { kind: 'ref'; rawRef: string; timeoutMs: number | null }
   | { kind: 'selector'; selectorExpression: string; timeoutMs: number | null }
   | { kind: 'text'; text: string; timeoutMs: number | null }
-  | { kind: 'stable'; quietMs: number | null; timeoutMs: number | null };
+  | { kind: 'stable'; quietMs: number | null; timeoutMs: number | null }
+  | { kind: 'invalid'; reason: WaitInvalidReason; message: string };
+
+// Words that name a wait CONDITION rather than a selector key. A caller leading with one of these
+// almost certainly wants the selector form — `visible`/`hidden` are already selector keys, so they
+// never reach this list; they parse as valid boolean-key selector terms instead (#1800).
+const CONDITION_WORDS = new Set(['exists', 'present', 'appears', 'gone', 'disappears']);
 
 export function parseWaitPositionals(args: string[]): WaitParsed | null {
   const firstArg = args[0];
   if (firstArg === undefined) return null;
   const sleepMs = parseTimeout(firstArg);
   if (sleepMs !== null) return { kind: 'sleep', durationMs: sleepMs };
   const timeoutMs = parseTimeout(args[args.length - 1]);
-  if (firstArg === 'text') {
-    const text = timeoutMs !== null ? args.slice(1, -1).join(' ') : args.slice(1).join(' ');
-    return { kind: 'text', text: text.trim(), timeoutMs };
-  }
-  if (firstArg === 'stable') {
-    const rest = args.slice(1);
-    const stableTimeoutMs = rest.length > 1 ? parseTimeout(rest[1]) : null;
-    const quietMs = rest.length > 0 ? parseTimeout(rest[0]) : null;
-    return { kind: 'stable', quietMs, timeoutMs: stableTimeoutMs };
-  }
+  if (firstArg === 'text') return parseTextKeyword(args, timeoutMs);
+  if (firstArg === 'stable') return parseStableKeyword(args);
   if (firstArg.startsWith('@')) return { kind: 'ref', rawRef: firstArg, timeoutMs };
+  return parseSelectorOrText(args, timeoutMs);
+}
+
+function parseTextKeyword(args: string[], timeoutMs: number | null): WaitParsed {
+  const text = timeoutMs !== null ? args.slice(1, -1).join(' ') : args.slice(1).join(' ');
+  return { kind: 'text', text: text.trim(), timeoutMs };
+}
+
+function parseStableKeyword(args: string[]): WaitParsed {
+  const rest = args.slice(1);
+  const stableTimeoutMs = rest.length > 1 ? parseTimeout(rest[1]) : null;
+  const quietMs = rest.length > 0 ? parseTimeout(rest[0]) : null;
+  return { kind: 'stable', quietMs, timeoutMs: stableTimeoutMs };
+}
+
+/**
+ * The fallback path once `wait` isn't a keyword form, a sleep, or a `@ref`: either a full selector
+ * expression, or literal text. #1800: a token shaped like a selector (a recognized key, or an
+ * unrecognized `key=value`) must never silently degrade to literal text just because the overall
+ * positional list failed to parse as a full selector expression — that is exactly the shape that
+ * reads as an absent element after a full timeout instead of the caller's own mistake.
+ */
+function parseSelectorOrText(args: string[], timeoutMs: number | null): WaitParsed {
   const argsWithoutTimeout = timeoutMs !== null ? args.slice(0, -1) : args.slice();
   const split = splitSelectorFromArgs(argsWithoutTimeout);
   if (split && split.rest.length === 0 && isValidSelectorExpression(split.selectorExpression)) {
     return { kind: 'selector', selectorExpression: split.selectorExpression, timeoutMs };
   }
+  const rejection = detectSelectorShapedRejection(argsWithoutTimeout, split);
+  if (rejection) return rejection;
   const text = timeoutMs !== null ? args.slice(0, -1).join(' ') : args.join(' ');
   return { kind: 'text', text: text.trim(), timeoutMs };
 }
 
+function detectSelectorShapedRejection(
+  argsWithoutTimeout: string[],
+  split: { selectorExpression: string; rest: string[] } | null,
+): Extract<WaitParsed, { kind: 'invalid' }> | null {
+  for (const token of argsWithoutTimeout) {
+    const unknownKey = detectUnknownSelectorKeyToken(token);
+    if (unknownKey) {
+      return {
+        kind: 'invalid',
+        reason: 'unknown-selector-key',
+        message: formatUnknownSelectorKeyMessage(unknownKey, argsWithoutTimeout),
+      };
+    }
+  }
+  if (split && split.rest.length > 0) {
+    return {
+      kind: 'invalid',
+      reason: 'selector-shaped-text',
+      message: formatTrailingArgsMessage(split, argsWithoutTimeout),
+    };
+  }
+  if (argsWithoutTimeout.some((token) => isSelectorToken(token))) {
+    return {
+      kind: 'invalid',
+      reason: 'selector-shaped-text',
+      message: formatSelectorShapedMessage(argsWithoutTimeout),
+    };
+  }
+  return null;
+}
+
+function formatUnknownSelectorKeyMessage(
+  unknownKey: { key: string; value: string },
+  argsWithoutTimeout: string[],
+): string {
+  const raw = argsWithoutTimeout.join(' ');
+  const hintValue = isRoleHintWord(unknownKey.key)
+    ? `role=${unknownKey.key} label="${unknownKey.value}"`
+    : `label="${unknownKey.value}"`;
+  return (
+    `Unknown selector key "${unknownKey.key}" in "${raw}". Supported: ${SELECTOR_KEY_NAMES.join(', ')}. ` +
+    `Use wait '${hintValue}' [timeoutMs] to wait for the selector, or wait text '${raw}' [timeoutMs] to wait for the literal text "${raw}".`
+  );
+}
+
+function formatTrailingArgsMessage(
+  split: { selectorExpression: string; rest: string[] },
+  argsWithoutTimeout: string[],
+): string {
+  const raw = argsWithoutTimeout.join(' ');
+  return (
+    `Selector ${split.selectorExpression} is followed by unexpected extra arguments: "${split.rest.join(' ')}". ` +
+    `Selector values with spaces need quotes, e.g. label="Sign in". ` +
+    `Use wait '<selector>' [timeoutMs], or wait text '${raw}' [timeoutMs] to wait for the literal text "${raw}".`
+  );
+}
+
+function formatSelectorShapedMessage(argsWithoutTimeout: string[]): string {
+  const raw = argsWithoutTimeout.join(' ');
+  const plainTokens = argsWithoutTimeout.filter((token) => !isSelectorToken(token));
+  const selectorTokens = argsWithoutTimeout.filter((token) => isSelectorToken(token));
+  if (plainTokens.length > 0) {
+    const offending = plainTokens[0]!;
+    const conditionHint = CONDITION_WORDS.has(offending.toLowerCase())
+      ? ` "${offending}" describes a condition, not a selector key. Use the selector form: ` +
+        `wait 'visible ${selectorTokens.join(' ')}' [timeoutMs] to wait for it to appear, or ` +
+        `wait 'hidden ${selectorTokens.join(' ')}' [timeoutMs] to wait for it to disappear.`
+      : ` "${offending}" is not a recognized selector key (${SELECTOR_KEY_NAMES.join(', ')}).`;
+    return (
+      `"${raw}" mixes plain word "${offending}" with selector-shaped "${selectorTokens.join(' ')}", ` +
+      `so it is neither a valid selector nor safe as literal text.${conditionHint} ` +
+      `Use wait '<selector>' [timeoutMs] for a selector, or wait text '${raw}' [timeoutMs] to wait for the literal text "${raw}".`
+    );
+  }
+  return (
+    `"${raw}" looks like a selector key but is not a valid selector expression. ` +
+    `Use wait '<selector>' [timeoutMs], e.g. wait '${argsWithoutTimeout[0]}="value"' [timeoutMs], ` +
+    `or wait text '${raw}' [timeoutMs] to wait for the literal text "${raw}".`
+  );
+}
+
 /**
  * The user-supplied budget of a `wait` invocation, or null when none was given.
  * The budget travels as a positional, not a flag, so it is parsed the same way
@@ -44,5 +157,6 @@ export function resolveWaitBudgetMs(positionals: string[]): number | null {
   const parsed = parseWaitPositionals(positionals);
   if (!parsed) return null;
   if (parsed.kind === 'sleep') return parsed.durationMs;
+  if (parsed.kind === 'invalid') return null;
   return parsed.timeoutMs;
 }

src/daemon/handlers/__tests__/snapshot.test.ts

@@ -107,9 +107,14 @@ test('parseWaitArgs parses selector expression with timeout', () => {
   }
 });
 
-test('parseWaitArgs falls back to text when selector-like token is invalid', () => {
+// #1800: this used to fall back to a literal-text wait for "foo=bar" — a caller typo (or a
+// straight-up unrecognized selector key) that can only ever time out, never match. It is now a
+// typed rejection instead. Full coverage of the rejection shapes lives in
+// src/core/wait-positionals.test.ts, which mirrors this module's source topology.
+test('parseWaitArgs rejects an unrecognized selector-like key=value token instead of reading it as text', () => {
   const result = parseWaitArgs(['foo=bar', '5000']);
-  assert.deepEqual(result, { kind: 'text', text: 'foo=bar', timeoutMs: 5000 });
+  assert.ok(result);
+  assert.equal(result.kind, 'invalid');
 });
 
 test('parseWaitArgs parses bare multi-word text', () => {