@jjlabsio/claude-crew 0.1.30 → 0.1.32

package/scripts/crew-codex/lib/fs.mjs

@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: Apache-2.0
+// Derived from @openai/codex-plugin-cc and modified for claude-crew.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export function ensureAbsolutePath(cwd, maybePath) {
+  return path.isAbsolute(maybePath) ? maybePath : path.resolve(cwd, maybePath);
+}
+
+export function createTempDir(prefix = "codex-plugin-") {
+  return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+}
+
+export function readJsonFile(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+export function writeJsonFile(filePath, value) {
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
+export function safeReadFile(filePath) {
+  return fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf8") : "";
+}
+
+export function isProbablyText(buffer) {
+  const sample = buffer.subarray(0, Math.min(buffer.length, 4096));
+  for (const value of sample) {
+    if (value === 0) {
+      return false;
+    }
+  }
+  return true;
+}
+
+export function readStdinIfPiped() {
+  if (process.stdin.isTTY) {
+    return "";
+  }
+  return fs.readFileSync(0, "utf8");
+}

package/scripts/crew-codex/lib/git.mjs

@@ -0,0 +1,348 @@
+// SPDX-License-Identifier: Apache-2.0
+// Derived from @openai/codex-plugin-cc and modified for claude-crew.
+import fs from "node:fs";
+import path from "node:path";
+
+import { isProbablyText } from "./fs.mjs";
+import { formatCommandFailure, runCommand, runCommandChecked } from "./process.mjs";
+
+const MAX_UNTRACKED_BYTES = 24 * 1024;
+const DEFAULT_INLINE_DIFF_MAX_FILES = 2;
+const DEFAULT_INLINE_DIFF_MAX_BYTES = 256 * 1024;
+
+function git(cwd, args, options = {}) {
+  return runCommand("git", args, { cwd, ...options });
+}
+
+function gitChecked(cwd, args, options = {}) {
+  return runCommandChecked("git", args, { cwd, ...options });
+}
+
+function listUniqueFiles(...groups) {
+  return [...new Set(groups.flat().filter(Boolean))].sort();
+}
+
+function normalizeMaxInlineFiles(value) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    return DEFAULT_INLINE_DIFF_MAX_FILES;
+  }
+  return Math.floor(parsed);
+}
+
+function normalizeMaxInlineDiffBytes(value) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    return DEFAULT_INLINE_DIFF_MAX_BYTES;
+  }
+  return Math.floor(parsed);
+}
+
+function measureGitOutputBytes(cwd, args, maxBytes) {
+  const result = git(cwd, args, { maxBuffer: maxBytes + 1 });
+  if (result.error && /** @type {NodeJS.ErrnoException} */ (result.error).code === "ENOBUFS") {
+    return maxBytes + 1;
+  }
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    throw new Error(formatCommandFailure(result));
+  }
+  return Buffer.byteLength(result.stdout, "utf8");
+}
+
+function measureCombinedGitOutputBytes(cwd, argSets, maxBytes) {
+  let totalBytes = 0;
+  for (const args of argSets) {
+    const remainingBytes = maxBytes - totalBytes;
+    if (remainingBytes < 0) {
+      return maxBytes + 1;
+    }
+    totalBytes += measureGitOutputBytes(cwd, args, remainingBytes);
+    if (totalBytes > maxBytes) {
+      return totalBytes;
+    }
+  }
+  return totalBytes;
+}
+
+function buildBranchComparison(cwd, baseRef) {
+  const mergeBase = gitChecked(cwd, ["merge-base", "HEAD", baseRef]).stdout.trim();
+  return {
+    mergeBase,
+    commitRange: `${mergeBase}..HEAD`,
+    reviewRange: `${baseRef}...HEAD`
+  };
+}
+
+export function ensureGitRepository(cwd) {
+  const result = git(cwd, ["rev-parse", "--show-toplevel"]);
+  const errorCode = result.error && "code" in result.error ? result.error.code : null;
+  if (errorCode === "ENOENT") {
+    throw new Error("git is not installed. Install Git and retry.");
+  }
+  if (result.status !== 0) {
+    throw new Error("This command must run inside a Git repository.");
+  }
+  return result.stdout.trim();
+}
+
+export function getRepoRoot(cwd) {
+  return gitChecked(cwd, ["rev-parse", "--show-toplevel"]).stdout.trim();
+}
+
+export function detectDefaultBranch(cwd) {
+  const symbolic = git(cwd, ["symbolic-ref", "refs/remotes/origin/HEAD"]);
+  if (symbolic.status === 0) {
+    const remoteHead = symbolic.stdout.trim();
+    if (remoteHead.startsWith("refs/remotes/origin/")) {
+      return remoteHead.replace("refs/remotes/origin/", "");
+    }
+  }
+
+  const candidates = ["main", "master", "trunk"];
+  for (const candidate of candidates) {
+    const local = git(cwd, ["show-ref", "--verify", "--quiet", `refs/heads/${candidate}`]);
+    if (local.status === 0) {
+      return candidate;
+    }
+    const remote = git(cwd, ["show-ref", "--verify", "--quiet", `refs/remotes/origin/${candidate}`]);
+    if (remote.status === 0) {
+      return `origin/${candidate}`;
+    }
+  }
+
+  throw new Error("Unable to detect the repository default branch. Pass --base <ref> or use --scope working-tree.");
+}
+
+export function getCurrentBranch(cwd) {
+  return gitChecked(cwd, ["branch", "--show-current"]).stdout.trim() || "HEAD";
+}
+
+export function getWorkingTreeState(cwd) {
+  const staged = gitChecked(cwd, ["diff", "--cached", "--name-only"]).stdout.trim().split("\n").filter(Boolean);
+  const unstaged = gitChecked(cwd, ["diff", "--name-only"]).stdout.trim().split("\n").filter(Boolean);
+  const untracked = gitChecked(cwd, ["ls-files", "--others", "--exclude-standard"]).stdout.trim().split("\n").filter(Boolean);
+
+  return {
+    staged,
+    unstaged,
+    untracked,
+    isDirty: staged.length > 0 || unstaged.length > 0 || untracked.length > 0
+  };
+}
+
+export function resolveReviewTarget(cwd, options = {}) {
+  ensureGitRepository(cwd);
+
+  const requestedScope = options.scope ?? "auto";
+  const baseRef = options.base ?? null;
+  const state = getWorkingTreeState(cwd);
+  const supportedScopes = new Set(["auto", "working-tree", "branch"]);
+
+  if (baseRef) {
+    return {
+      mode: "branch",
+      label: `branch diff against ${baseRef}`,
+      baseRef,
+      explicit: true
+    };
+  }
+
+  if (requestedScope === "working-tree") {
+    return {
+      mode: "working-tree",
+      label: "working tree diff",
+      explicit: true
+    };
+  }
+
+  if (!supportedScopes.has(requestedScope)) {
+    throw new Error(
+      `Unsupported review scope "${requestedScope}". Use one of: auto, working-tree, branch, or pass --base <ref>.`
+    );
+  }
+
+  if (requestedScope === "branch") {
+    const detectedBase = detectDefaultBranch(cwd);
+    return {
+      mode: "branch",
+      label: `branch diff against ${detectedBase}`,
+      baseRef: detectedBase,
+      explicit: true
+    };
+  }
+
+  if (state.isDirty) {
+    return {
+      mode: "working-tree",
+      label: "working tree diff",
+      explicit: false
+    };
+  }
+
+  const detectedBase = detectDefaultBranch(cwd);
+  return {
+    mode: "branch",
+    label: `branch diff against ${detectedBase}`,
+    baseRef: detectedBase,
+    explicit: false
+  };
+}
+
+function formatSection(title, body) {
+  return [`## ${title}`, "", body.trim() ? body.trim() : "(none)", ""].join("\n");
+}
+
+function formatUntrackedFile(cwd, relativePath) {
+  const absolutePath = path.join(cwd, relativePath);
+  let stat;
+  try {
+    stat = fs.statSync(absolutePath);
+  } catch {
+    return `### ${relativePath}\n(skipped: broken symlink or unreadable file)`;
+  }
+  if (stat.isDirectory()) {
+    return `### ${relativePath}\n(skipped: directory)`;
+  }
+  if (stat.size > MAX_UNTRACKED_BYTES) {
+    return `### ${relativePath}\n(skipped: ${stat.size} bytes exceeds ${MAX_UNTRACKED_BYTES} byte limit)`;
+  }
+
+  let buffer;
+  try {
+    buffer = fs.readFileSync(absolutePath);
+  } catch {
+    return `### ${relativePath}\n(skipped: broken symlink or unreadable file)`;
+  }
+  if (!isProbablyText(buffer)) {
+    return `### ${relativePath}\n(skipped: binary file)`;
+  }
+
+  return [`### ${relativePath}`, "```", buffer.toString("utf8").trimEnd(), "```"].join("\n");
+}
+
+function collectWorkingTreeContext(cwd, state, options = {}) {
+  const includeDiff = options.includeDiff !== false;
+  const status = gitChecked(cwd, ["status", "--short", "--untracked-files=all"]).stdout.trim();
+  const changedFiles = listUniqueFiles(state.staged, state.unstaged, state.untracked);
+
+  let parts;
+  if (includeDiff) {
+    const stagedDiff = gitChecked(cwd, ["diff", "--cached", "--binary", "--no-ext-diff", "--submodule=diff"]).stdout;
+    const unstagedDiff = gitChecked(cwd, ["diff", "--binary", "--no-ext-diff", "--submodule=diff"]).stdout;
+    const untrackedBody = state.untracked.map((file) => formatUntrackedFile(cwd, file)).join("\n\n");
+    parts = [
+      formatSection("Git Status", status),
+      formatSection("Staged Diff", stagedDiff),
+      formatSection("Unstaged Diff", unstagedDiff),
+      formatSection("Untracked Files", untrackedBody)
+    ];
+  } else {
+    const stagedStat = gitChecked(cwd, ["diff", "--shortstat", "--cached"]).stdout.trim();
+    const unstagedStat = gitChecked(cwd, ["diff", "--shortstat"]).stdout.trim();
+    const untrackedBody = state.untracked.map((file) => formatUntrackedFile(cwd, file)).join("\n\n");
+    parts = [
+      formatSection("Git Status", status),
+      formatSection("Staged Diff Stat", stagedStat),
+      formatSection("Unstaged Diff Stat", unstagedStat),
+      formatSection("Changed Files", changedFiles.join("\n")),
+      formatSection("Untracked Files", untrackedBody)
+    ];
+  }
+
+  return {
+    mode: "working-tree",
+    summary: `Reviewing ${state.staged.length} staged, ${state.unstaged.length} unstaged, and ${state.untracked.length} untracked file(s).`,
+    content: parts.join("\n"),
+    changedFiles
+  };
+}
+
+function collectBranchContext(cwd, baseRef, options = {}) {
+  const includeDiff = options.includeDiff !== false;
+  const comparison = options.comparison ?? buildBranchComparison(cwd, baseRef);
+  const currentBranch = getCurrentBranch(cwd);
+  const changedFiles = gitChecked(cwd, ["diff", "--name-only", comparison.commitRange]).stdout.trim().split("\n").filter(Boolean);
+  const logOutput = gitChecked(cwd, ["log", "--oneline", "--decorate", comparison.commitRange]).stdout.trim();
+  const diffStat = gitChecked(cwd, ["diff", "--stat", comparison.commitRange]).stdout.trim();
+
+  return {
+    mode: "branch",
+    summary: `Reviewing branch ${currentBranch} against ${baseRef} from merge-base ${comparison.mergeBase}.`,
+    content: includeDiff
+      ? [
+          formatSection("Commit Log", logOutput),
+          formatSection("Diff Stat", diffStat),
+          formatSection(
+            "Branch Diff",
+            gitChecked(cwd, ["diff", "--binary", "--no-ext-diff", "--submodule=diff", comparison.commitRange]).stdout
+          )
+        ].join("\n")
+      : [
+          formatSection("Commit Log", logOutput),
+          formatSection("Diff Stat", diffStat),
+          formatSection("Changed Files", changedFiles.join("\n"))
+        ].join("\n"),
+    changedFiles,
+    comparison
+  };
+}
+
+function buildAdversarialCollectionGuidance(options = {}) {
+  if (options.includeDiff !== false) {
+    return "Use the repository context below as primary evidence.";
+  }
+
+  return "The repository context below is a lightweight summary. Inspect the target diff yourself with read-only git commands before finalizing findings.";
+}
+
+export function collectReviewContext(cwd, target, options = {}) {
+  const repoRoot = getRepoRoot(cwd);
+  const currentBranch = getCurrentBranch(repoRoot);
+  const maxInlineFiles = normalizeMaxInlineFiles(options.maxInlineFiles);
+  const maxInlineDiffBytes = normalizeMaxInlineDiffBytes(options.maxInlineDiffBytes);
+  let details;
+  let includeDiff;
+  let diffBytes;
+
+  if (target.mode === "working-tree") {
+    const state = getWorkingTreeState(repoRoot);
+    diffBytes = measureCombinedGitOutputBytes(
+      repoRoot,
+      [
+        ["diff", "--cached", "--binary", "--no-ext-diff", "--submodule=diff"],
+        ["diff", "--binary", "--no-ext-diff", "--submodule=diff"]
+      ],
+      maxInlineDiffBytes
+    );
+    includeDiff =
+      options.includeDiff ??
+      (listUniqueFiles(state.staged, state.unstaged, state.untracked).length <= maxInlineFiles &&
+        diffBytes <= maxInlineDiffBytes);
+    details = collectWorkingTreeContext(repoRoot, state, { includeDiff });
+  } else {
+    const comparison = buildBranchComparison(repoRoot, target.baseRef);
+    const fileCount = gitChecked(repoRoot, ["diff", "--name-only", comparison.commitRange]).stdout.trim().split("\n").filter(Boolean).length;
+    diffBytes = measureGitOutputBytes(
+      repoRoot,
+      ["diff", "--binary", "--no-ext-diff", "--submodule=diff", comparison.commitRange],
+      maxInlineDiffBytes
+    );
+    includeDiff = options.includeDiff ?? (fileCount <= maxInlineFiles && diffBytes <= maxInlineDiffBytes);
+    details = collectBranchContext(repoRoot, target.baseRef, { includeDiff, comparison });
+  }
+
+  return {
+    cwd: repoRoot,
+    repoRoot,
+    branch: currentBranch,
+    target,
+    fileCount: details.changedFiles.length,
+    diffBytes,
+    inputMode: includeDiff ? "inline-diff" : "self-collect",
+    collectionGuidance: buildAdversarialCollectionGuidance({ includeDiff }),
+    ...details
+  };
+}

package/scripts/crew-codex/lib/job-control.mjs

@@ -0,0 +1,310 @@
+// SPDX-License-Identifier: Apache-2.0
+// Derived from @openai/codex-plugin-cc and modified for claude-crew.
+import fs from "node:fs";
+
+import { getSessionRuntimeStatus } from "./codex.mjs";
+import { getConfig, listJobs, readJobFile, resolveJobFile } from "./state.mjs";
+import { SESSION_ID_ENV } from "./tracked-jobs.mjs";
+import { resolveWorkspaceRoot } from "./workspace.mjs";
+
+export const DEFAULT_MAX_STATUS_JOBS = 8;
+export const DEFAULT_MAX_PROGRESS_LINES = 4;
+
+export function sortJobsNewestFirst(jobs) {
+  return [...jobs].sort((left, right) => String(right.updatedAt ?? "").localeCompare(String(left.updatedAt ?? "")));
+}
+
+function getCurrentSessionId(options = {}) {
+  return options.env?.[SESSION_ID_ENV] ?? process.env[SESSION_ID_ENV] ?? null;
+}
+
+function filterJobsForCurrentSession(jobs, options = {}) {
+  const sessionId = getCurrentSessionId(options);
+  if (!sessionId) {
+    return jobs;
+  }
+  return jobs.filter((job) => job.sessionId === sessionId);
+}
+
+function getJobTypeLabel(job) {
+  if (typeof job.kindLabel === "string" && job.kindLabel) {
+    return job.kindLabel;
+  }
+  if (job.kind === "adversarial-review") {
+    return "adversarial-review";
+  }
+  if (job.jobClass === "review") {
+    return "review";
+  }
+  if (job.jobClass === "task") {
+    return "task";
+  }
+  if (job.kind === "review") {
+    return "review";
+  }
+  if (job.kind === "task") {
+    return "task";
+  }
+  return "job";
+}
+
+function stripLogPrefix(line) {
+  return line.replace(/^\[[^\]]+\]\s*/, "").trim();
+}
+
+function isProgressBlockTitle(line) {
+  return (
+    ["Final output", "Assistant message", "Reasoning summary", "Review output"].includes(line) ||
+    /^Subagent .+ message$/.test(line) ||
+    /^Subagent .+ reasoning summary$/.test(line)
+  );
+}
+
+export function readJobProgressPreview(logFile, maxLines = DEFAULT_MAX_PROGRESS_LINES) {
+  if (!logFile || !fs.existsSync(logFile)) {
+    return [];
+  }
+
+  const lines = fs
+    .readFileSync(logFile, "utf8")
+    .split(/\r?\n/)
+    .map((line) => line.trimEnd())
+    .filter(Boolean)
+    .filter((line) => line.startsWith("["))
+    .map(stripLogPrefix)
+    .filter((line) => line && !isProgressBlockTitle(line));
+
+  return lines.slice(-maxLines);
+}
+
+function formatElapsedDuration(startValue, endValue = null) {
+  const start = Date.parse(startValue ?? "");
+  if (!Number.isFinite(start)) {
+    return null;
+  }
+
+  const end = endValue ? Date.parse(endValue) : Date.now();
+  if (!Number.isFinite(end) || end < start) {
+    return null;
+  }
+
+  const totalSeconds = Math.max(0, Math.round((end - start) / 1000));
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  const seconds = totalSeconds % 60;
+
+  if (hours > 0) {
+    return `${hours}h ${minutes}m`;
+  }
+  if (minutes > 0) {
+    return `${minutes}m ${seconds}s`;
+  }
+  return `${seconds}s`;
+}
+
+function looksLikeVerificationCommand(line) {
+  return /\b(test|tests|lint|build|typecheck|type-check|check|verify|validate|pytest|jest|vitest|cargo test|npm test|pnpm test|yarn test|go test|mvn test|gradle test|tsc|eslint|ruff)\b/i.test(
+    line
+  );
+}
+
+function inferLegacyJobPhase(job, progressPreview = []) {
+  switch (job.status) {
+    case "queued":
+      return "queued";
+    case "cancelled":
+      return "cancelled";
+    case "failed":
+      return "failed";
+    case "completed":
+      return "done";
+    default:
+      break;
+  }
+
+  for (let index = progressPreview.length - 1; index >= 0; index -= 1) {
+    const line = progressPreview[index].toLowerCase();
+    if (line.startsWith("starting codex") || line.startsWith("thread ready") || line.startsWith("turn started")) {
+      return "starting";
+    }
+    if (line.startsWith("reviewer started") || line.includes("review mode")) {
+      return "reviewing";
+    }
+    if (line.startsWith("searching:") || line.startsWith("calling ") || line.startsWith("running tool:")) {
+      return "investigating";
+    }
+    if (line.startsWith("starting collaboration tool:")) {
+      return "investigating";
+    }
+    if (line.startsWith("running command:")) {
+      return looksLikeVerificationCommand(line)
+        ? "verifying"
+        : job.jobClass === "review"
+          ? "reviewing"
+          : "investigating";
+    }
+    if (line.startsWith("command completed:")) {
+      return looksLikeVerificationCommand(line) ? "verifying" : "running";
+    }
+    if (line.startsWith("applying ") || line.startsWith("file changes ")) {
+      return "editing";
+    }
+    if (line.startsWith("turn completed")) {
+      return "finalizing";
+    }
+    if (line.startsWith("codex error:") || line.startsWith("failed:")) {
+      return "failed";
+    }
+  }
+
+  return job.jobClass === "review" ? "reviewing" : "running";
+}
+
+export function enrichJob(job, options = {}) {
+  const maxProgressLines = options.maxProgressLines ?? DEFAULT_MAX_PROGRESS_LINES;
+  const enriched = {
+    ...job,
+    kindLabel: getJobTypeLabel(job),
+    progressPreview:
+      job.status === "queued" || job.status === "running" || job.status === "failed"
+        ? readJobProgressPreview(job.logFile, maxProgressLines)
+        : [],
+    elapsed: formatElapsedDuration(job.startedAt ?? job.createdAt, job.completedAt ?? null),
+    duration:
+      job.status === "completed" || job.status === "failed" || job.status === "cancelled"
+        ? formatElapsedDuration(job.startedAt ?? job.createdAt, job.completedAt ?? job.updatedAt)
+        : null
+  };
+
+  return {
+    ...enriched,
+    phase: enriched.phase ?? inferLegacyJobPhase(enriched, enriched.progressPreview)
+  };
+}
+
+export function readStoredJob(workspaceRoot, jobId) {
+  const jobFile = resolveJobFile(workspaceRoot, jobId);
+  if (!fs.existsSync(jobFile)) {
+    return null;
+  }
+  return readJobFile(jobFile);
+}
+
+function matchJobReference(jobs, reference, predicate = () => true) {
+  const filtered = jobs.filter(predicate);
+  if (!reference) {
+    return filtered[0] ?? null;
+  }
+
+  const exact = filtered.find((job) => job.id === reference);
+  if (exact) {
+    return exact;
+  }
+
+  const prefixMatches = filtered.filter((job) => job.id.startsWith(reference));
+  if (prefixMatches.length === 1) {
+    return prefixMatches[0];
+  }
+  if (prefixMatches.length > 1) {
+    throw new Error(`Job reference "${reference}" is ambiguous. Use a longer job id.`);
+  }
+
+  throw new Error(`No job found for "${reference}". Run crew-codex status to list known jobs.`);
+}
+
+export function buildStatusSnapshot(cwd, options = {}) {
+  const workspaceRoot = resolveWorkspaceRoot(cwd);
+  const config = getConfig(workspaceRoot);
+  const jobs = sortJobsNewestFirst(filterJobsForCurrentSession(listJobs(workspaceRoot), options));
+  const maxJobs = options.maxJobs ?? DEFAULT_MAX_STATUS_JOBS;
+  const maxProgressLines = options.maxProgressLines ?? DEFAULT_MAX_PROGRESS_LINES;
+
+  const running = jobs
+    .filter((job) => job.status === "queued" || job.status === "running")
+    .map((job) => enrichJob(job, { maxProgressLines }));
+
+  const latestFinishedRaw = jobs.find((job) => job.status !== "queued" && job.status !== "running") ?? null;
+  const latestFinished = latestFinishedRaw ? enrichJob(latestFinishedRaw, { maxProgressLines }) : null;
+
+  const recent = (options.all ? jobs : jobs.slice(0, maxJobs))
+    .filter((job) => job.status !== "queued" && job.status !== "running" && job.id !== latestFinished?.id)
+    .map((job) => enrichJob(job, { maxProgressLines }));
+
+  return {
+    workspaceRoot,
+    config,
+    sessionRuntime: getSessionRuntimeStatus(options.env, workspaceRoot),
+    running,
+    latestFinished,
+    recent,
+    needsReview: Boolean(config.stopReviewGate)
+  };
+}
+
+export function buildSingleJobSnapshot(cwd, reference, options = {}) {
+  const workspaceRoot = resolveWorkspaceRoot(cwd);
+  const jobs = sortJobsNewestFirst(listJobs(workspaceRoot));
+  const selected = matchJobReference(jobs, reference);
+  if (!selected) {
+    throw new Error(`No job found for "${reference}". Run crew-codex status to inspect known jobs.`);
+  }
+
+  return {
+    workspaceRoot,
+    job: enrichJob(selected, { maxProgressLines: options.maxProgressLines })
+  };
+}
+
+export function resolveResultJob(cwd, reference) {
+  const workspaceRoot = resolveWorkspaceRoot(cwd);
+  const jobs = sortJobsNewestFirst(reference ? listJobs(workspaceRoot) : filterJobsForCurrentSession(listJobs(workspaceRoot)));
+  const selected = matchJobReference(
+    jobs,
+    reference,
+    (job) => job.status === "completed" || job.status === "failed" || job.status === "cancelled"
+  );
+
+  if (selected) {
+    return { workspaceRoot, job: selected };
+  }
+
+  const active = matchJobReference(jobs, reference, (job) => job.status === "queued" || job.status === "running");
+  if (active) {
+    throw new Error(`Job ${active.id} is still ${active.status}. Check crew-codex status and try again once it finishes.`);
+  }
+
+  if (reference) {
+    throw new Error(`No finished job found for "${reference}". Run crew-codex status to inspect active jobs.`);
+  }
+
+  throw new Error("No finished Codex jobs found for this repository yet.");
+}
+
+export function resolveCancelableJob(cwd, reference, options = {}) {
+  const workspaceRoot = resolveWorkspaceRoot(cwd);
+  const jobs = sortJobsNewestFirst(listJobs(workspaceRoot));
+  const activeJobs = jobs.filter((job) => job.status === "queued" || job.status === "running");
+
+  if (reference) {
+    const selected = matchJobReference(activeJobs, reference);
+    if (!selected) {
+      throw new Error(`No active job found for "${reference}".`);
+    }
+    return { workspaceRoot, job: selected };
+  }
+
+  const sessionScopedActiveJobs = filterJobsForCurrentSession(activeJobs, options);
+
+  if (sessionScopedActiveJobs.length === 1) {
+    return { workspaceRoot, job: sessionScopedActiveJobs[0] };
+  }
+  if (sessionScopedActiveJobs.length > 1) {
+    throw new Error("Multiple Codex jobs are active. Pass a job id to crew-codex cancel.");
+  }
+
+  if (getCurrentSessionId(options)) {
+    throw new Error("No active Codex jobs to cancel for this session.");
+  }
+
+  throw new Error("No active Codex jobs to cancel.");
+}