@dev-loops/core 1.0.0-rc.2 → 1.0.0-rc.4

package/src/github/issue-ops.mjs

@@ -0,0 +1,556 @@
+import { readFile } from "node:fs/promises";
+import { readFileSync, statSync } from "node:fs";
+import { runChild as defaultRunChild } from "../cli/primitives.mjs";
+import { parseJsonText } from "./review-threads.mjs";
+import { parseRepoSlug } from "./repo-slug.mjs";
+
+/**
+ * Core `gh issue` operations, extracted from the thin CLI wrappers under
+ * `scripts/github/*.mjs` (view/create/edit/comment/list-issue,
+ * detect-linked-issue-pr) so both the CLI scripts and the GitHub tracker
+ * adapter (`../tracker/github-adapter.mjs`) call one implementation instead
+ * of duplicating gh-command construction. The CLI scripts keep their own
+ * arg parsing/USAGE/runCli; this module owns the actual `gh` calls and output
+ * shaping. Mirrors the existing `../projects/move-queue-item.mjs` /
+ * `../projects/list-queue-items.mjs` split (core logic + thin CLI wrapper).
+ */
+
+const ISSUE_URL_NUMBER_PATTERN = /\/issues\/(\d+)(?:\D|$)/u;
+
+// ── view-issue ──────────────────────────────────────────────────────────
+
+export const VIEW_ISSUE_DEFAULT_FIELDS = "number,title,body,state,author,labels,url,createdAt,updatedAt";
+
+export async function viewIssue(options, { env = process.env, ghCommand = "gh", run = defaultRunChild } = {}) {
+  const fields = options.fields ?? VIEW_ISSUE_DEFAULT_FIELDS;
+  const result = await run(
+    ghCommand,
+    ["issue", "view", String(options.issue), "--repo", options.repo, "--json", fields],
+    env,
+  );
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || `exit code ${result.code}`;
+    throw new Error(`gh issue view failed: ${detail}`);
+  }
+  const issue = parseJsonText(result.stdout, { label: "gh issue view" });
+  if (issue === null || typeof issue !== "object" || Array.isArray(issue)) {
+    throw new Error("gh issue view did not return a JSON object");
+  }
+  return { ok: true, issue };
+}
+
+// ── create-issue ────────────────────────────────────────────────────────
+
+// Build the `gh issue create` args. A --body-file path is forwarded straight
+// to gh so large bodies avoid command-length limits.
+export function buildCreateArgs(options) {
+  const args = ["issue", "create", "--repo", options.repo, "--title", options.title];
+  if (options.body !== undefined) {
+    args.push("--body", options.body);
+  } else {
+    args.push("--body-file", options.bodyFile);
+  }
+  if (options.milestone !== undefined) {
+    args.push("--milestone", options.milestone);
+  }
+  for (const l of options.labels ?? []) {
+    args.push("--label", l);
+  }
+  for (const u of options.assignees ?? []) {
+    args.push("--assignee", u);
+  }
+  return args;
+}
+
+// Reject a --body-file path that does not RESOLVE (following symlinks) to a
+// regular file. The CLI layer's literal-string rejections (`-`, `/dev/stdin`,
+// `/dev/fd/N`, ...) only catch known stdin-device spellings; a symlink to one
+// of those devices (or to /dev/null, a FIFO, etc.) dodges that regex yet still
+// reads as empty/non-file when `gh` re-reads the same path with stdin ignored.
+// `statSync` follows symlinks, so this closes that gap regardless of path shape.
+function assertRegularFilePath(path) {
+  if (!statSync(path).isFile()) {
+    throw new Error(`--body-file must be a regular file: ${path}`);
+  }
+}
+
+// Read (for validation only — the actual gh call still forwards the path, see
+// buildCreateArgs) and reject a --body-file that isn't a regular file or whose
+// content is empty/whitespace-only. This is the real guard behind the CLI's
+// stdin-device rejection: `gh` is spawned with stdin ignored, so it re-reads
+// the same path fresh — this validates what gh will actually see, not just the
+// path's literal spelling.
+export async function resolveCreateBody(options) {
+  if (options.bodyFile === undefined) return options.body;
+  assertRegularFilePath(options.bodyFile);
+  return await readFile(options.bodyFile, "utf8");
+}
+
+export async function createIssue(options, { env = process.env, ghCommand = "gh", run = defaultRunChild } = {}) {
+  const body = await resolveCreateBody(options);
+  if (typeof body !== "string" || body.trim().length === 0) {
+    const source = options.bodyFile !== undefined ? `--body-file ${options.bodyFile}` : "--body";
+    throw new Error(`issue body resolved empty from ${source} — refusing to create a bodyless issue`);
+  }
+  const args = buildCreateArgs(options);
+  const result = await run(ghCommand, args, env);
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || `exit code ${result.code}`;
+    throw new Error(`gh issue create failed: ${detail}`);
+  }
+  // gh prints the created issue URL to stdout.
+  const url = (result.stdout ?? "").trim();
+  const match = ISSUE_URL_NUMBER_PATTERN.exec(url);
+  if (!match) {
+    throw new Error(`gh issue create returned no parseable issue URL: ${url || "<empty>"}`);
+  }
+  return { ok: true, issueNumber: Number(match[1]), url };
+}
+
+// ── edit-issue ──────────────────────────────────────────────────────────
+
+export async function resolveEditBody(options) {
+  if (options.bodyFile === undefined) return options.body;
+  // Stdin (fd 0): fs/promises readFile does NOT accept an integer fd, so read
+  // it synchronously via the callback-style API (which does). A real path
+  // stays on the async promise read.
+  const body =
+    options.bodyFile === "-" ? readFileSync(0, "utf8") : await readFile(options.bodyFile, "utf8");
+  if (body.trim().length === 0) {
+    throw new Error(`--body-file ${options.bodyFile} is empty`);
+  }
+  return body;
+}
+
+// Build the `gh issue edit` args and the parallel `edited` list (which fields
+// were touched) so callers get a stable summary without re-reading the issue.
+export async function buildEditArgs(options) {
+  const args = ["issue", "edit", String(options.issue), "--repo", options.repo];
+  const edited = [];
+  if (options.title !== undefined) {
+    args.push("--title", options.title);
+    edited.push("title");
+  }
+  const body = await resolveEditBody(options);
+  if (body !== undefined) {
+    if (options.bodyFile !== undefined && options.bodyFile !== "-") {
+      args.push("--body-file", options.bodyFile);
+    } else {
+      args.push("--body", body);
+    }
+    edited.push("body");
+  }
+  for (const u of options.addAssignees ?? []) {
+    args.push("--add-assignee", u);
+  }
+  if ((options.addAssignees ?? []).length > 0) edited.push("add-assignee");
+  for (const u of options.removeAssignees ?? []) {
+    args.push("--remove-assignee", u);
+  }
+  if ((options.removeAssignees ?? []).length > 0) edited.push("remove-assignee");
+  if (options.milestone !== undefined) {
+    args.push("--milestone", options.milestone);
+    edited.push("milestone");
+  }
+  return { args, edited };
+}
+
+// gh's own --reason values are space-separated ("not planned"), but the
+// CLI-facing flag value stays the underscore form (`not_planned`) since it's
+// stable and shell-friendly without quoting; map it here at the gh-args
+// boundary rather than changing the public flag value.
+const REASON_ARG_BY_CLI_VALUE = { not_planned: "not planned" };
+
+// Build the `gh issue close`/`gh issue reopen` args for a --state change. Kept
+// as a separate `gh` call from `gh issue edit` — that command has no --state
+// flag, so a state change is its own invocation, run after the edit call.
+export function buildStateChangeArgs(options) {
+  if (options.state === "closed") {
+    const args = ["issue", "close", String(options.issue), "--repo", options.repo];
+    if (options.reason !== undefined) {
+      args.push("--reason", REASON_ARG_BY_CLI_VALUE[options.reason] ?? options.reason);
+    }
+    return args;
+  }
+  if (options.state !== "open") {
+    // Fail closed: this is an exported seam, so an unexpected state must never
+    // silently degrade into a reopen.
+    throw new Error(`invalid state ${JSON.stringify(options.state)} — expected "open" or "closed"`);
+  }
+  return ["issue", "reopen", String(options.issue), "--repo", options.repo];
+}
+
+export async function editIssue(options, { env = process.env, ghCommand = "gh", run = defaultRunChild } = {}) {
+  const { args, edited } = await buildEditArgs(options);
+  // Skip the edit call entirely when --state is the only change requested —
+  // `gh issue edit` with no field flags errors ("no changed fields").
+  if (edited.length > 0) {
+    const result = await run(ghCommand, args, env);
+    if (result.code !== 0) {
+      const detail = result.stderr.trim() || `exit code ${result.code}`;
+      throw new Error(`gh issue edit failed: ${detail}`);
+    }
+  }
+  if (options.state !== undefined) {
+    const stateArgs = buildStateChangeArgs(options);
+    const result = await run(ghCommand, stateArgs, env);
+    if (result.code !== 0) {
+      const verb = options.state === "closed" ? "close" : "reopen";
+      const detail = result.stderr.trim() || `exit code ${result.code}`;
+      // Surface the edits that DID land before the state change failed, so a
+      // caller (or a human reading the error) knows the field edits are not
+      // rolled back — only the state change itself failed.
+      const landed = edited.length > 0 ? ` after edits were applied: ${edited.join(", ")}` : "";
+      throw new Error(`state change failed${landed} — gh issue ${verb} failed: ${detail}`);
+    }
+    edited.push("state");
+  }
+  return { ok: true, repo: options.repo, issue: options.issue, edited };
+}
+
+// ── comment-issue ───────────────────────────────────────────────────────
+
+export async function resolveCommentBody(options) {
+  if (options.bodyFile === undefined) {
+    if (options.body.trim().length === 0) {
+      throw new Error("--body must not be empty");
+    }
+    return options.body;
+  }
+  const source = options.bodyFile === "-" ? 0 : options.bodyFile;
+  const body = await readFile(source, "utf8");
+  if (body.trim().length === 0) {
+    throw new Error(`--body-file ${options.bodyFile} is empty`);
+  }
+  return body;
+}
+
+export async function commentIssue(options, { env = process.env, ghCommand = "gh", run = defaultRunChild } = {}) {
+  const body = await resolveCommentBody(options);
+  const result = await run(
+    ghCommand,
+    ["issue", "comment", String(options.issue), "--repo", options.repo, "--body", body],
+    env,
+  );
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || `exit code ${result.code}`;
+    throw new Error(`gh issue comment failed: ${detail}`);
+  }
+  const commentUrl = result.stdout
+    .split(/\r?\n/u)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)
+    .pop() ?? null;
+  if (commentUrl === null || !/^https?:\/\//u.test(commentUrl)) {
+    throw new Error(`gh issue comment did not return a comment URL (got: ${result.stdout.trim() || "<empty>"})`);
+  }
+  return { ok: true, repo: options.repo, issue: options.issue, commentUrl };
+}
+
+// ── list-issues ─────────────────────────────────────────────────────────
+
+// Returns a well-typed issue, or null if the gh entry is missing/invalid in
+// any required field.
+export function normalizeIssue(raw) {
+  if (!Number.isInteger(raw?.number) || typeof raw?.title !== "string" || typeof raw?.state !== "string") {
+    return null;
+  }
+  return {
+    number: raw.number,
+    title: raw.title,
+    // gh reports issue state UPPERCASE (OPEN/CLOSED); normalize to lowercase.
+    state: raw.state.toLowerCase(),
+    labels: Array.isArray(raw?.labels)
+      ? raw.labels.map((l) => (typeof l?.name === "string" ? l.name : null)).filter((n) => n !== null)
+      : [],
+  };
+}
+
+export async function listIssues(options, { env = process.env, ghCommand = "gh", run = defaultRunChild } = {}) {
+  const args = [
+    "issue",
+    "list",
+    "--repo",
+    options.repo,
+    "--state",
+    options.state ?? "open",
+    "--limit",
+    String(options.limit ?? 30),
+    "--json",
+    "number,title,state,labels",
+  ];
+  for (const label of options.labels ?? []) {
+    args.push("--label", label);
+  }
+  const result = await run(ghCommand, args, env);
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || `exit code ${result.code}`;
+    throw new Error(`gh issue list failed: ${detail}`);
+  }
+  const payload = parseJsonText(result.stdout, { label: "gh issue list" });
+  if (!Array.isArray(payload)) {
+    throw new Error("gh issue list did not return a JSON array");
+  }
+  return { ok: true, issues: payload.map(normalizeIssue).filter((issue) => issue !== null) };
+}
+
+// ── detect-linked-issue-pr ──────────────────────────────────────────────
+
+export const LINKED_ISSUE_PR_QUERY = [
+  "query($owner:String!, $name:String!, $issue:Int!, $after:String) {",
+  "  repository(owner:$owner, name:$name) {",
+  "    issue(number:$issue) {",
+  "      timelineItems(first:100, after:$after, itemTypes:[CONNECTED_EVENT, CROSS_REFERENCED_EVENT]) {",
+  "        pageInfo {",
+  "          hasNextPage",
+  "          endCursor",
+  "        }",
+  "        nodes {",
+  "          __typename",
+  "          ... on ConnectedEvent {",
+  "            createdAt",
+  "            subject {",
+  "              __typename",
+  "              ... on PullRequest {",
+  "                number",
+  "                state",
+  "                url",
+  "                repository { nameWithOwner }",
+  "              }",
+  "            }",
+  "          }",
+  "          ... on CrossReferencedEvent {",
+  "            createdAt",
+  "            willCloseTarget",
+  "            source {",
+  "              __typename",
+  "              ... on PullRequest {",
+  "                number",
+  "                state",
+  "                url",
+  "                repository { nameWithOwner }",
+  "              }",
+  "            }",
+  "          }",
+  "        }",
+  "      }",
+  "    }",
+  "  }",
+  "}",
+].join("\n");
+
+function buildLinkedPrQueryArgs({ owner, name, issue, after }) {
+  const args = [
+    "api",
+    "graphql",
+    "--field",
+    `owner=${owner}`,
+    "--field",
+    `name=${name}`,
+    "-F",
+    `issue=${issue}`,
+    "--field",
+    `query=${LINKED_ISSUE_PR_QUERY}`,
+  ];
+  if (typeof after === "string" && after.length > 0) {
+    args.push("--field", `after=${after}`);
+  }
+  return args;
+}
+
+function readLinkedPrTimelineConnection(payload) {
+  const connection = payload?.data?.repository?.issue?.timelineItems;
+  if (!connection || typeof connection !== "object") {
+    throw new Error("Invalid linked-PR GraphQL payload: missing data.repository.issue.timelineItems");
+  }
+  const nodes = Array.isArray(connection.nodes) ? connection.nodes : [];
+  const pageInfo = connection.pageInfo ?? {};
+  return {
+    nodes,
+    hasNextPage: Boolean(pageInfo.hasNextPage),
+    endCursor: typeof pageInfo.endCursor === "string" ? pageInfo.endCursor : null,
+  };
+}
+
+function normalizeLinkedPrNode(node) {
+  if (!node || typeof node !== "object") {
+    return null;
+  }
+  if (node.__typename === "ConnectedEvent") {
+    return {
+      eventType: "CONNECTED_EVENT",
+      eventCreatedAt: node.createdAt,
+      pr: node.subject,
+    };
+  }
+  if (node.__typename === "CrossReferencedEvent") {
+    // Only a cross-reference that will CLOSE this issue owns its board status.
+    // A bare body-mention (willCloseTarget:false, e.g. "part of #X") must not
+    // create board-ownership linkage (#1130).
+    if (node.willCloseTarget !== true) {
+      return null;
+    }
+    return {
+      eventType: "CROSS_REFERENCED_EVENT",
+      eventCreatedAt: node.createdAt,
+      pr: node.source,
+    };
+  }
+  return null;
+}
+
+function compareStableStrings(left, right) {
+  if (left === right) {
+    return 0;
+  }
+  return left < right ? -1 : 1;
+}
+
+function normalizeRepoSlugForComparison(repo) {
+  return typeof repo === "string" ? repo.trim().toLowerCase() : "";
+}
+
+function normalizeOpenSameRepoCandidate(candidate, repo) {
+  const pr = candidate?.pr;
+  const number = pr?.number;
+  const state = pr?.state;
+  const url = pr?.url;
+  const nameWithOwner = pr?.repository?.nameWithOwner;
+  if (!Number.isInteger(number) || number <= 0) {
+    return null;
+  }
+  if (
+    state !== "OPEN"
+    || normalizeRepoSlugForComparison(nameWithOwner) !== normalizeRepoSlugForComparison(repo)
+  ) {
+    return null;
+  }
+  const createdAtMs = Date.parse(candidate.eventCreatedAt);
+  if (!Number.isFinite(createdAtMs)) {
+    return null;
+  }
+  return {
+    prNumber: number,
+    prUrl: typeof url === "string" ? url : null,
+    eventType: candidate.eventType,
+    eventCreatedAt: typeof candidate.eventCreatedAt === "string" ? candidate.eventCreatedAt : null,
+    createdAtMs,
+  };
+}
+
+function normalizeClosedUnmergedSameRepoCandidate(candidate, repo) {
+  const pr = candidate?.pr;
+  const number = pr?.number;
+  const state = pr?.state;
+  const url = pr?.url;
+  const nameWithOwner = pr?.repository?.nameWithOwner;
+  if (!Number.isInteger(number) || number <= 0) {
+    return null;
+  }
+  if (
+    state !== "CLOSED"
+    || normalizeRepoSlugForComparison(nameWithOwner) !== normalizeRepoSlugForComparison(repo)
+  ) {
+    return null;
+  }
+  const createdAtMs = Date.parse(candidate.eventCreatedAt);
+  if (!Number.isFinite(createdAtMs)) {
+    return null;
+  }
+  return {
+    prNumber: number,
+    prUrl: typeof url === "string" ? url : null,
+    eventType: candidate.eventType,
+    eventCreatedAt: typeof candidate.eventCreatedAt === "string" ? candidate.eventCreatedAt : null,
+    createdAtMs,
+  };
+}
+
+export function selectLinkedIssuePr(candidates) {
+  if (!Array.isArray(candidates) || candidates.length === 0) {
+    return null;
+  }
+  const sorted = [...candidates].sort((left, right) => {
+    const leftPriority = left.eventType === "CONNECTED_EVENT" ? 0 : 1;
+    const rightPriority = right.eventType === "CONNECTED_EVENT" ? 0 : 1;
+    if (leftPriority !== rightPriority) {
+      return leftPriority - rightPriority;
+    }
+    if (left.createdAtMs !== right.createdAtMs) {
+      return right.createdAtMs - left.createdAtMs;
+    }
+    if (left.prNumber !== right.prNumber) {
+      return right.prNumber - left.prNumber;
+    }
+    return compareStableStrings(String(left.prUrl ?? ""), String(right.prUrl ?? ""));
+  });
+  return sorted[0] ?? null;
+}
+
+export async function detectLinkedIssuePr({ repo, issue }, { env = process.env, ghCommand = "gh", runChild = defaultRunChild } = {}) {
+  const { owner, name } = parseRepoSlug(repo);
+  const candidates = [];
+  const closedUnmergedCandidates = [];
+  let after = null;
+  while (true) {
+    const result = await runChild(
+      ghCommand,
+      buildLinkedPrQueryArgs({ owner, name, issue, after }),
+      env,
+    );
+    if (result.code !== 0) {
+      const detail = result.stderr.trim() || `exit code ${result.code}`;
+      throw new Error(`gh command failed: ${detail}`);
+    }
+    const payload = parseJsonText(result.stdout);
+    const { nodes, hasNextPage, endCursor } = readLinkedPrTimelineConnection(payload);
+    for (const node of nodes) {
+      const normalizedNode = normalizeLinkedPrNode(node);
+      if (!normalizedNode) {
+        continue;
+      }
+      const normalizedCandidate = normalizeOpenSameRepoCandidate(normalizedNode, repo);
+      if (normalizedCandidate) {
+        candidates.push(normalizedCandidate);
+      }
+      const closedUnmergedCandidate = normalizeClosedUnmergedSameRepoCandidate(normalizedNode, repo);
+      if (closedUnmergedCandidate) {
+        closedUnmergedCandidates.push(closedUnmergedCandidate);
+      }
+    }
+    if (!hasNextPage) {
+      break;
+    }
+    if (!endCursor) {
+      throw new Error("Invalid linked-PR GraphQL payload: pageInfo.hasNextPage is true but endCursor is missing");
+    }
+    after = endCursor;
+  }
+  const selected = selectLinkedIssuePr(candidates);
+  const selectedClosedUnmerged = selectLinkedIssuePr(closedUnmergedCandidates);
+  if (!selected) {
+    return {
+      ok: true,
+      repo,
+      issue,
+      hasOpenLinkedPr: false,
+      prNumber: null,
+      prUrl: null,
+      hasPriorClosedUnmergedPr: selectedClosedUnmerged !== null,
+      priorClosedUnmergedPrNumber: selectedClosedUnmerged?.prNumber ?? null,
+      priorClosedUnmergedPrUrl: selectedClosedUnmerged?.prUrl ?? null,
+    };
+  }
+  return {
+    ok: true,
+    repo,
+    issue,
+    hasOpenLinkedPr: true,
+    prNumber: selected.prNumber,
+    prUrl: selected.prUrl,
+    selection: {
+      eventType: selected.eventType,
+      eventCreatedAt: selected.eventCreatedAt,
+    },
+  };
+}

package/src/github/ownership-helpers.mjs

@@ -0,0 +1,79 @@
+/**
+ * Shared deterministic single-contributor ownership classification for
+ * issue/PR assignees.
+ *
+ * Owner: packages/core — reusable pure logic consumed by the startup
+ * resolver (`resolve-dev-loop-startup.mjs`) and the Next Up pickup source
+ * (`resolve-active-board-item.mjs`). `classifyOwnership` never shells out —
+ * callers fetch assignees and the viewer's login via `gh`, then classify here.
+ */
+import { isCopilotLogin } from "./copilot-helpers.mjs";
+
+export const OWNERSHIP_STATE = Object.freeze({
+  ASSIGNED_TO_ME: "assigned_to_me",
+  ASSIGNED_TO_OTHER: "assigned_to_other",
+  ASSIGNED_TO_COPILOT: "assigned_to_copilot",
+  UNASSIGNED: "unassigned",
+});
+
+/**
+ * Classify assignee ownership of an issue/PR relative to the viewer.
+ *
+ * Copilot assignment is checked FIRST and short-circuits before any human
+ * comparison — the viewer login is never required to detect it, so a
+ * copilot-assigned artifact is unaffected by viewer-login resolution
+ * failures (matches the existing, unchanged Copilot-first flow).
+ *
+ * `assigned_to_me` requires the viewer to be the SOLE human assignee.
+ * `gh issue/pr edit --add-assignee` is not compare-and-swap, so two loopers
+ * racing to claim the same unassigned item can both end up co-assigned;
+ * membership-based classification would wave both through. A viewer
+ * co-assigned alongside another human is `assigned_to_other` (contested) —
+ * `foreignLogins` names the OTHER humans only (never the viewer), so error
+ * messages stay accurate. Login comparison is case-insensitive (GitHub
+ * logins are case-insensitive).
+ *
+ * @param {Array<{login?: string}>} assignees
+ * @param {string|null} [viewerLogin] - required only when a non-copilot
+ *   assignee is present; pass null/undefined when the caller skipped
+ *   resolving it (empty assignees, or a copilot assignee already found).
+ * @returns {{ state: string, foreignLogins: string[] }}
+ */
+export function classifyOwnership(assignees, viewerLogin = null) {
+  const logins = (Array.isArray(assignees) ? assignees : [])
+    .map((a) => a?.login)
+    .filter((login) => typeof login === "string" && login.length > 0);
+  if (logins.some(isCopilotLogin)) {
+    return { state: OWNERSHIP_STATE.ASSIGNED_TO_COPILOT, foreignLogins: [] };
+  }
+  if (logins.length === 0) {
+    return { state: OWNERSHIP_STATE.UNASSIGNED, foreignLogins: [] };
+  }
+  const viewerLoginLower = typeof viewerLogin === "string" && viewerLogin.length > 0
+    ? viewerLogin.toLowerCase()
+    : null;
+  const otherLogins = viewerLoginLower === null
+    ? logins
+    : logins.filter((login) => login.toLowerCase() !== viewerLoginLower);
+  if (viewerLoginLower !== null && otherLogins.length === 0) {
+    return { state: OWNERSHIP_STATE.ASSIGNED_TO_ME, foreignLogins: [] };
+  }
+  return { state: OWNERSHIP_STATE.ASSIGNED_TO_OTHER, foreignLogins: otherLogins };
+}
+
+/**
+ * Whether classifying these assignees requires a resolved viewer login (i.e.
+ * there is at least one non-copilot assignee to compare against). Lets
+ * callers skip the extra `gh api user` call for the common empty/copilot
+ * cases, which also keeps those cases immune to viewer-login resolution
+ * failures.
+ *
+ * @param {Array<{login?: string}>} assignees
+ * @returns {boolean}
+ */
+export function ownershipNeedsViewerLogin(assignees) {
+  const logins = (Array.isArray(assignees) ? assignees : [])
+    .map((a) => a?.login)
+    .filter((login) => typeof login === "string" && login.length > 0);
+  return logins.length > 0 && !logins.some(isCopilotLogin);
+}

package/src/github/review-threads.mjs

@@ -166,6 +166,34 @@ export function parseReviewThreads(payload) {
   };
 }
 
+/**
+ * The fix-loop's re-entry working set: only unresolved threads, each with its
+ * comment bodies joined in thread order. Location fields come from the thread
+ * node when the payload carries them (`path`/`line`/`isOutdated`); snapshots
+ * without them yield `path: null`, `line: null`, `isOutdated: false`.
+ *
+ * @returns {{ summary: object, threads: Array<{ threadId: string, path: string|null, line: number|null, isOutdated: boolean, bodies: string[] }> }}
+ */
+export function parseUnresolvedThreadBodies(payload) {
+  const rawThreads = extractRawThreads(payload);
+  const { summary } = parseReviewThreads(payload);
+  const threads = rawThreads
+    .map((thread, threadIndex) => ({ thread, threadIndex }))
+    .filter(({ thread }) => !thread?.isResolved)
+    .map(({ thread, threadIndex }) => ({
+      threadId: normalizeId(thread?.id ?? thread?.databaseId, `thread-${threadIndex + 1}`),
+      path: typeof thread?.path === "string" && thread.path.length > 0 ? thread.path : null,
+      line: Number.isInteger(thread?.line) ? thread.line : null,
+      isOutdated: Boolean(thread?.isOutdated),
+      bodies: extractRawComments(thread).map((comment) =>
+        normalizeBody(comment?.body ?? comment?.bodyText ?? comment?.bodyHTML ?? ""),
+      ),
+    }))
+    .sort((left, right) => compareIds(left.threadId, right.threadId));
+
+  return { summary, threads };
+}
+
 // ── Signal classification heuristics ──────────────────────────────────────
 
 const HIGH_SIGNAL_PATTERNS = [
@@ -303,10 +331,23 @@ export function parseJsonText(text) {
   }
 }
 
-export function formatCliError(error) {
+// Renders the one shared { ok: false, error, hint? } envelope every
+// JSON-emitting gate CLI's main() catch block prints to stderr. `usage` is
+// accepted only as a PRESENCE check for a fallback usage string (a caller
+// passing its own `USAGE` constant when the error itself might not already
+// carry one) — the fallback's actual TEXT, like `error.usage`'s, is never
+// embedded here. Argument errors (and any error a caller marks with a usage
+// string) used to inline that string's full multi-KB text into this JSON
+// payload, which every calling agent then paid to read back out of its own
+// tool result on every mistyped flag. A one-line `hint` pointing at --help
+// carries the same "usage exists, go look" signal at a fraction of the size;
+// --help itself is unaffected (it prints the full USAGE text directly, never
+// through this function).
+export function formatCliError(error, { usage } = {}) {
   const payload = { ok: false, error: error instanceof Error ? error.message : String(error) };
-  if (error instanceof Error && typeof error.usage === "string") {
-    payload.usage = error.usage;
+  const hasUsage = (error instanceof Error && typeof error.usage === "string") || typeof usage === "string";
+  if (hasUsage) {
+    payload.hint = "run with --help for usage";
   }
   return JSON.stringify(payload);
 }