{"record":{"id":"eeac2e718bc519dc","repo":"openai/codex-plugin-cc","slug":"status-wait-requires-a-job-id","errorCode":null,"errorMessage":"`status --wait` requires a job id.","messagePattern":"`status --wait` requires a job id\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"plugins/codex/scripts/codex-companion.mjs","lineNumber":903,"sourceCode":"    valueOptions: [\"cwd\", \"timeout-ms\", \"poll-interval-ms\"],\n    booleanOptions: [\"json\", \"all\", \"wait\"]\n  });\n\n  const cwd = resolveCommandCwd(options);\n  const reference = positionals[0] ?? \"\";\n  if (reference) {\n    const snapshot = options.wait\n      ? await waitForSingleJobSnapshot(cwd, reference, {\n          timeoutMs: options[\"timeout-ms\"],\n          pollIntervalMs: options[\"poll-interval-ms\"]\n        })\n      : buildSingleJobSnapshot(cwd, reference);\n    outputCommandResult(snapshot, renderJobStatusReport(snapshot.job), options.json);\n    return;\n  }\n\n  if (options.wait) {\n    throw new Error(\"`status --wait` requires a job id.\");\n  }\n\n  const report = buildStatusSnapshot(cwd, { all: options.all });\n  outputResult(renderStatusPayload(report, options.json), options.json);\n}\n\nfunction handleResult(argv) {\n  const { options, positionals } = parseCommandInput(argv, {\n    valueOptions: [\"cwd\"],\n    booleanOptions: [\"json\"]\n  });\n\n  const cwd = resolveCommandCwd(options);\n  const reference = positionals[0] ?? \"\";\n  const { workspaceRoot, job } = resolveResultJob(cwd, reference);\n  const storedJob = readStoredJob(workspaceRoot, job.id);\n  const payload = {\n    job,","sourceCodeStart":885,"sourceCodeEnd":921,"githubUrl":"https://github.com/openai/codex-plugin-cc/blob/db52e28f4d9ded852ab3942cea316258ae4ef346/plugins/codex/scripts/codex-companion.mjs#L885-L921","documentation":"handleStatus supports listing all jobs (no positional) or targeting one job (positional reference). The --wait flag triggers polling via waitForSingleJobSnapshot, which requires a single job reference to poll. Waiting on the entire list is undefined, so --wait without a positional is rejected before the list report is built.","triggerScenarios":"Running `status --wait` with no job id. The guard sits after the reference-present branch (which would have used --wait correctly) and before the all-jobs snapshot.","commonSituations":"User expects --wait to block until all jobs finish; muscle memory from other CLIs where wait blocks globally.","solutions":["Provide a job id: status <job-id> --wait.","Drop --wait to get an immediate snapshot of all jobs: status.","Use --timeout-ms and --poll-interval-ms to tune the wait for a specific job."],"exampleFix":"// before\ncodex-companion.mjs status --wait\n// after\ncodex-companion.mjs status task-abc123 --wait","handlingStrategy":"validation","validationCode":"if (options.wait && !reference) throw new Error('status --wait needs a job id');","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always pair --wait with an explicit job id.","Poll all-jobs status without --wait instead."],"tags":["cli","validation","status","usage"],"backgroundTag":null,"analyzedSha":"db52e28f4d9ded852ab3942cea316258ae4ef346","analyzedAt":"2026-08-13T05:13:20.855Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}