{"record":{"id":"5bc9c571fe87c883","repo":"stablyai/orca","slug":"invalid-argument-5bc9c5","errorCode":"invalid_argument","errorMessage":"--cursor must be a non-negative integer","messagePattern":"--cursor must be a non-negative integer","errorType":"exception","errorClass":"RuntimeClientError","httpStatus":null,"severity":"error","filePath":"src/cli/handlers/terminal.ts","lineNumber":77,"sourceCode":"      // Why: agent JSON calls dominate; topology stays available through an explicit opt-in.\n      includeVisualLayouts: !json || flags.has('include-visual-layouts')\n    })\n    printResult(result, json, formatTerminalList)\n  },\n  'terminal show': async ({ flags, client, cwd, json }) => {\n    const result = await client.call<{ terminal: RuntimeTerminalShow }>('terminal.show', {\n      terminal: await getTerminalHandle(flags, cwd, client)\n    })\n    printResult(result, json, formatTerminalShow)\n  },\n  'terminal read': async ({ flags, client, cwd, json }) => {\n    const cursorFlag = getOptionalStringFlag(flags, 'cursor')\n    const cursor =\n      cursorFlag !== undefined && /^\\d+$/.test(cursorFlag)\n        ? Number.parseInt(cursorFlag, 10)\n        : undefined\n    if (cursorFlag !== undefined && cursor === undefined) {\n      throw new RuntimeClientError('invalid_argument', '--cursor must be a non-negative integer')\n    }\n    const result = await client.call<{ terminal: RuntimeTerminalRead }>('terminal.read', {\n      terminal: await getTerminalHandle(flags, cwd, client),\n      ...(cursor !== undefined ? { cursor } : {}),\n      limit: getOptionalPositiveIntegerFlag(flags, 'limit')\n    })\n    printResult(result, json, formatTerminalRead)\n  },\n  'terminal send': async ({ flags, client, cwd, json }) => {\n    const result = await client.call<{ send: RuntimeTerminalSend }>('terminal.send', {\n      terminal: await getTerminalHandle(flags, cwd, client),\n      text: getOptionalStringFlag(flags, 'text'),\n      enter: flags.get('enter') === true,\n      interrupt: flags.get('interrupt') === true,\n      client: { id: 'orca-cli', type: 'desktop' }\n    })\n    printResult(result, json, formatTerminalSend)\n  },","sourceCodeStart":59,"sourceCodeEnd":95,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/src/cli/handlers/terminal.ts#L59-L95","documentation":"Thrown by the `terminal read` handler when `--cursor` is supplied but does not match `/^\\d+$/` (one or more digits, non-negative). The flag is optional; a missing cursor is fine. The error fires only when a value is present but isn't a pure digits string, so negative numbers, decimals, hex, and non-numeric text all fail.","triggerScenarios":"Running `orca terminal read --cursor <x>` with a negative number, a float, a hex value, a variable that expands to non-digits, or an expression like `--cursor end`.","commonSituations":"Passing a byte offset from a tool that emits negatives or floats; a shell variable that is empty/non-numeric; user assumes `end`/`tail` keywords are supported.","solutions":["Pass a non-negative integer of digits only, e.g. `--cursor 1024`.","Omit `--cursor` to read from the terminal's current/default position.","Sanitize variables: default to 0 or drop the flag when the value isn't pure digits.","For 'latest' content, omit cursor and use `--limit` to bound the read."],"exampleFix":"// before\norca terminal read --cursor -1\norca terminal read --cursor 1.5\norca terminal read --cursor \"$OFFSET\"   // $OFFSET empty or non-numeric\n// after\norca terminal read --cursor 1024\n# script guard\n[[ \"$OFFSET\" =~ ^[0-9]+$ ]] && args+=(--cursor \"$OFFSET\")","handlingStrategy":"type-guard","validationCode":"const cursorFlag = getOptionalStringFlag(flags, 'cursor')\nif (cursorFlag !== undefined && !/^\\d+$/.test(cursorFlag)) { /* reject before terminal.read */ }","typeGuard":"function isNonNegativeIntegerString(v: string): boolean {\n  return /^\\d+$/.test(v)\n}","tryCatchPattern":"try { await terminalRead(flags) }\ncatch (e) {\n  if (e instanceof RuntimeClientError && e.code === 'invalid_argument' && e.message === '--cursor must be a non-negative integer') {\n    // coerce/derive a valid cursor (e.g. default to 0) or drop the flag and retry\n  } else throw e\n}","preventionTips":["Default to omitting --cursor rather than passing -1 or 0 from generic offsets.","Validate numeric flags with the same /^\\d+$/ regex used internally.","Watch for empty/non-numeric shell variables before passing them as --cursor."],"tags":["cli","validation","terminal","invalid-argument","numeric","regex"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}