{"record":{"id":"200d9aed2edd0c56","repo":"can1357/oh-my-pi","slug":"agents-must-be-a-positive-integer","errorCode":null,"errorMessage":"--agents must be a positive integer","messagePattern":"--agents must be a positive integer","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/coding-agent/src/cleanse/index.ts","lineNumber":56,"sourceCode":"\t/** Choose between discovered checkers; omit to run every checker without prompting. */\n\tpickTarget?(checkers: readonly CleanseCheckerDescriptor[]): Promise<CleanseTargetChoice>;\n\t/** Free-form request prompt when no runnable checker was discovered; `null` cancels. */\n\tpromptRequest?(): Promise<string | null>;\n}\n\n/**\n * Detect project diagnostics, dispatch one bounded repair batch, and verify it.\n *\n * Cancellation flows exclusively through `signal`; the caller owns signal\n * sources (SIGINT for the CLI, Esc for the interactive overlay).\n */\nexport async function runCleanse(\n\toptions: CleanseCommandOptions,\n\tui: CleanseRunUi,\n\tsignal: AbortSignal,\n): Promise<CleanseCommandResult> {\n\tconst maxAgents = options.maxAgents ?? 32;\n\tif (!Number.isInteger(maxAgents) || maxAgents <= 0) throw new Error(\"--agents must be a positive integer\");\n\tconst model = options.model?.trim() || DEFAULT_MODEL;\n\tconst cwd = getProjectDir();\n\tlet runtime: CleanseAgentRuntime | undefined;\n\tlet runtimePromise: Promise<CleanseAgentRuntime> | undefined;\n\tlet loopResult: CleanseLoopResult | undefined;\n\tconst board = ui.board;\n\tconst hooks: CleanseAgentHooks = {\n\t\tonStart: (name, assignment) => board.agentStarted(name, assignment),\n\t\tonProgress: (name, _assignment, progress) => board.agentProgress(name, progress),\n\t\tonFinish: (outcome, assignment) => board.agentFinished(outcome, assignment),\n\t};\n\tconst checkerEvents: CleanseCheckerRunEvents = {\n\t\tonCheckerStart: checker => board.checkerStarted(checker),\n\t\tonCheckerEnd: (check, durationMs) => board.checkerFinished(check, durationMs),\n\t};\n\tconst ensureRuntime = async (): Promise<CleanseAgentRuntime> => {\n\t\truntimePromise ??= (async () => {\n\t\t\tboard.phase(`Resolving model ${model}...`);","sourceCodeStart":38,"sourceCodeEnd":74,"githubUrl":"https://github.com/can1357/oh-my-pi/blob/969062200754ea02cfac922e5ebb8c608c079e15/packages/coding-agent/src/cleanse/index.ts#L38-L74","documentation":"runCleanse validates options.maxAgents before starting the cleanse runtime; when supplied it must be an integer greater than zero (default is 32 when omitted). A non-integer (e.g. 2.5, NaN) or zero/negative value aborts the cleanse run immediately with this Error.","triggerScenarios":"Calling runCleanse with CleanseCommandOptions.maxAgents set to 0, a negative number, a non-integer float like 1.5, or NaN (e.g. from parsing a bad CLI string). Omitting maxAgents never triggers it.","commonSituations":"Passing --agents 0 or --agents abc through a wrapper that does Number(value) without checking NaN, or a config file where maxAgents was left at 0 or edited to a float.","solutions":["Set maxAgents to a positive integer (or omit it to use the default 32).","If parsing from a string, validate with Number.isInteger(Number(raw)) and surface a clear CLI error before calling runCleanse.","Clamp at the call site: maxAgents = Math.max(1, Math.floor(userValue))."],"exampleFix":"// before\nawait runCleanse({ maxAgents: Number(argv.agents), ... }, ui, signal); // NaN when --agents is empty\n// after\nconst maxAgents = argv.agents ? Number(argv.agents) : undefined;\nif (maxAgents !== undefined && (!Number.isInteger(maxAgents) || maxAgents <= 0)) {\n  throw new CliUsageError(\"--agents must be a positive integer\");\n}\nawait runCleanse({ maxAgents, ... }, ui, signal);","handlingStrategy":"validation","validationCode":"const n = options.maxAgents;\nif (n !== undefined && (!Number.isInteger(n) || n <= 0)) {\n  throw new Error(\"--agents must be a positive integer\");\n}","typeGuard":"function isValidMaxAgents(v: unknown): v is number {\n  return typeof v === \"number\" && Number.isInteger(v) && v > 0;\n}","tryCatchPattern":"try {\n  await runCleanse(options, ui, signal);\n} catch (err) {\n  if (err instanceof Error && err.message.includes(\"--agents must be a positive integer\")) {\n    console.error(\"Invalid --agents value; use a positive integer (default 32).\");\n    process.exitCode = 2;\n    return;\n  }\n  throw err;\n}","preventionTips":["Parse CLI numbers with Number.parseInt and check Number.isNaN before use.","Default to 32 instead of passing 0/undefined-derived values.","Validate user-supplied options at the CLI boundary with a CliUsageError."],"tags":["cli","validation","argument-parsing"],"backgroundTag":"invalid-argument-value","analyzedSha":"969062200754ea02cfac922e5ebb8c608c079e15","analyzedAt":"2026-08-31T10:29:35.737Z","schemaVersion":2},"datasetVersion":"2026-08-31T14:17:45.589Z"}