{"record":{"id":"304706fd0e8f1b02","repo":"openai/codex-plugin-cc","slug":"job-reference-reference-is-ambiguous-use-a-l","errorCode":null,"errorMessage":"Job reference \"${reference}\" is ambiguous. Use a longer job id.","messagePattern":"Job reference \"(.+?)\" is ambiguous\\. Use a longer job id\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"plugins/codex/scripts/lib/job-control.mjs","lineNumber":207,"sourceCode":"}\n\nfunction matchJobReference(jobs, reference, predicate = () => true) {\n  const filtered = jobs.filter(predicate);\n  if (!reference) {\n    return filtered[0] ?? null;\n  }\n\n  const exact = filtered.find((job) => job.id === reference);\n  if (exact) {\n    return exact;\n  }\n\n  const prefixMatches = filtered.filter((job) => job.id.startsWith(reference));\n  if (prefixMatches.length === 1) {\n    return prefixMatches[0];\n  }\n  if (prefixMatches.length > 1) {\n    throw new Error(`Job reference \"${reference}\" is ambiguous. Use a longer job id.`);\n  }\n\n  throw new Error(`No job found for \"${reference}\". Run /codex:status to list known jobs.`);\n}\n\nexport function buildStatusSnapshot(cwd, options = {}) {\n  const workspaceRoot = resolveWorkspaceRoot(cwd);\n  const config = getConfig(workspaceRoot);\n  const jobs = sortJobsNewestFirst(filterJobsForCurrentSession(listJobs(workspaceRoot), options));\n  const maxJobs = options.maxJobs ?? DEFAULT_MAX_STATUS_JOBS;\n  const maxProgressLines = options.maxProgressLines ?? DEFAULT_MAX_PROGRESS_LINES;\n\n  const running = jobs\n    .filter((job) => job.status === \"queued\" || job.status === \"running\")\n    .map((job) => enrichJob(job, { maxProgressLines }));\n\n  const latestFinishedRaw = jobs.find((job) => job.status !== \"queued\" && job.status !== \"running\") ?? null;\n  const latestFinished = latestFinishedRaw ? enrichJob(latestFinishedRaw, { maxProgressLines }) : null;","sourceCodeStart":189,"sourceCodeEnd":225,"githubUrl":"https://github.com/openai/codex-plugin-cc/blob/db52e28f4d9ded852ab3942cea316258ae4ef346/plugins/codex/scripts/lib/job-control.mjs#L189-L225","documentation":"Thrown by matchJobReference() when the supplied reference string is a prefix of more than one job id (after predicate filtering). The function first tries an exact id match, then a single prefix match; if the prefix matches multiple jobs it refuses to guess. This protects against operating on the wrong job.","triggerScenarios":"Passing a short prefix like 'ab' when job ids 'abc123' and 'abcdef' both exist and pass the active predicate. Reached via buildSingleJobSnapshot, resolveResultJob, or resolveCancelableJob when a reference resolves ambiguously.","commonSituations":"User copies only the first few characters of a job id from /codex:status; many jobs created in quick succession share long common prefixes (timestamp-based ids); passing the creation-order prefix instead of the full id.","solutions":["Run /codex:status and copy a longer (unique) prefix of the intended job id.","Pass the full job id to eliminate any ambiguity.","If you control id generation, increase id entropy so short prefixes collide less often."],"exampleFix":"// before\nresolveResultJob(cwd, \"ab\");\n\n// after\nresolveResultJob(cwd, \"abc123\");","handlingStrategy":"validation","validationCode":"function resolveUnique(jobs, reference) {\n  if (!reference) return jobs[0] ?? null;\n  if (jobs.some((j) => j.id === reference)) return jobs.find((j) => j.id === reference);\n  const prefixMatches = jobs.filter((j) => j.id.startsWith(reference));\n  if (prefixMatches.length === 1) return prefixMatches[0];\n  if (prefixMatches.length > 1) {\n    // surface options instead of throwing blindly\n    return { ambiguous: true, candidates: prefixMatches.map((j) => j.id) };\n  }\n  return null;\n}\n\n// before calling resolveResultJob(cwd, ref):\nconst probe = resolveUnique(listJobs(workspaceRoot), ref);\nif (probe?.ambiguous) {\n  throw new Error(`Ambiguous prefix '${ref}'. Candidates: ${probe.candidates.join(\", \")}`);\n}","typeGuard":null,"tryCatchPattern":"try {\n  resolveResultJob(cwd, ref);\n} catch (err) {\n  if (/is ambiguous/.test(err.message)) {\n    // prompt user for a longer prefix using /codex:status output\n    const snap = buildStatusSnapshot(cwd, { all: true });\n    console.log(snap.recent.map((j) => j.id).join(\"\\n\"));\n  } else throw err;\n}","preventionTips":["Always pass the full job id rather than a short prefix in automation.","When displaying ids in /codex:status, show enough characters to be unique.","Pre-validate the prefix against the live job list before resolving."],"tags":["job-control","disambiguation","codex","prefix-match"],"backgroundTag":null,"analyzedSha":"db52e28f4d9ded852ab3942cea316258ae4ef346","analyzedAt":"2026-08-13T05:13:20.855Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}