@tutar/graph-engineering 0.3.0

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@tutar/graph-engineering",
+  "version": "0.3.0",
+  "description": "Install and inspect project-owned Graph Engineering workflows for GitHub software development.",
+  "type": "module",
+  "bin": {
+    "graph-engineering": "bin/graph-engineering.mjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "templates/",
+    "migrations/",
+    "release-metadata.json",
+    "README.md"
+  ],
+  "scripts": {
+    "prepack": "node scripts/sync-package-assets.mjs",
+    "test": "node --test test/*.test.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tutar/graph-engineering.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/tutar/graph-engineering/issues"
+  },
+  "homepage": "https://github.com/tutar/graph-engineering#readme",
+  "license": "MIT"
+}

package/release-metadata.json

@@ -0,0 +1,4 @@
+{
+  "productVersion": "0.3.0",
+  "sourceCommit": "049fdb6a98ab9867572637a5728f91f4683124ce"
+}

package/templates/development/.github/graph-engineering/development-worktree.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+interrupted_ref="refs/graph-engineering/interrupted/${TARGET_BRANCH}"
+interrupted_stash_ref="refs/graph-engineering/interrupted-stash/${TARGET_BRANCH}"
+legacy_interrupted_ref="refs/loop-engineering/interrupted/${TARGET_BRANCH}"
+legacy_interrupted_stash_ref="refs/loop-engineering/interrupted-stash/${TARGET_BRANCH}"
+
+migrate_legacy_ref() {
+  local current="$1"
+  local legacy="$2"
+  if ! git show-ref --verify --quiet "${current}" && git show-ref --verify --quiet "${legacy}"; then
+    git update-ref "${current}" "${legacy}"
+    git update-ref -d "${legacy}"
+  fi
+}
+
+case "${1:-}" in
+  prepare)
+    migrate_legacy_ref "${interrupted_ref}" "${legacy_interrupted_ref}"
+    migrate_legacy_ref "${interrupted_stash_ref}" "${legacy_interrupted_stash_ref}"
+    if git show-ref --verify --quiet "${interrupted_ref}"; then
+      git switch --force-create "${TARGET_BRANCH}" "${interrupted_ref}"
+      git rebase "${BASE_BRANCH}"
+    elif git ls-remote --exit-code origin "refs/heads/${TARGET_BRANCH}" >/dev/null 2>&1; then
+      git fetch origin "${TARGET_BRANCH}"
+      git switch --create "${TARGET_BRANCH}" --track "origin/${TARGET_BRANCH}"
+    else
+      git switch --create "${TARGET_BRANCH}"
+    fi
+    ;;
+  restore)
+    migrate_legacy_ref "${interrupted_ref}" "${legacy_interrupted_ref}"
+    migrate_legacy_ref "${interrupted_stash_ref}" "${legacy_interrupted_stash_ref}"
+    if git show-ref --verify --quiet "${interrupted_stash_ref}"; then
+      git stash apply --index "${interrupted_stash_ref}"
+      git update-ref -d "${interrupted_stash_ref}"
+    fi
+    if git show-ref --verify --quiet "${interrupted_ref}"; then
+      git update-ref -d "${interrupted_ref}"
+    fi
+    ;;
+  *)
+    echo "usage: development-worktree.sh prepare|restore" >&2
+    exit 2
+    ;;
+esac

package/templates/development/.github/graph-engineering/github-development-ticket.mjs

@@ -0,0 +1,246 @@
+import { spawn, execFileSync } from "node:child_process";
+import { accessSync, constants, realpathSync } from "node:fs";
+import { delimiter, join } from "node:path";
+import { createInterface } from "node:readline";
+import {
+  STOP_HOOK_WAIT_TIMEOUT_MS,
+  expireStopHookTimeouts,
+  shouldAwaitStopHooks,
+} from "./stop-hook-drain.mjs";
+import { findThreadRecord, formatThreadRecord } from "./thread-record.mjs";
+
+const repository = requiredEnv("GITHUB_REPOSITORY");
+const issueNumber = Number(requiredEnv("ISSUE_NUMBER"));
+const baseBranch = requiredEnv("BASE_BRANCH");
+const tokenBudgetInput = process.env.GOAL_TOKEN_BUDGET ?? "500000";
+const tokenBudget = tokenBudgetInput === "unlimited" ? null : Number(tokenBudgetInput);
+if (!Number.isSafeInteger(issueNumber) || issueNumber <= 0) throw new Error("ISSUE_NUMBER must be a positive integer");
+if (tokenBudget !== null && (!Number.isSafeInteger(tokenBudget) || tokenBudget <= 0)) {
+  throw new Error('GOAL_TOKEN_BUDGET must be a positive integer or "unlimited"');
+}
+
+const issueUrl = `https://github.com/${repository}/issues/${issueNumber}`;
+const goalPrompt = `使用 Matt Skill $implement 完成 ${issueUrl}；若 Issue 含 Acceptance Criteria，逐项依据实际验证结果，只将已满足项的复选框更新为已勾选；完成后将提交 push 到当前开发分支；如果不存在关联 PR，创建指向 ${baseBranch} 的 Draft PR。只有实现、自测、review、commit、push、Draft PR，以及适用时的验收条件状态同步都完成后才能结束 Goal。不得执行或输出认证状态、token、credential 或其他秘密。`;
+
+function ghJson(args) {
+  return JSON.parse(execFileSync("gh", args, { encoding: "utf8", env: process.env }));
+}
+
+function getThreadRecord() {
+  const pages = ghJson(["api", `repos/${repository}/issues/${issueNumber}/comments`, "--paginate", "--slurp"]);
+  return findThreadRecord(pages.flat(), { repository, issueNumber });
+}
+
+function saveThreadRecord(threadId) {
+  execFileSync(
+    "gh",
+    ["api", "--method", "POST", `repos/${repository}/issues/${issueNumber}/comments`, "-f", `body=${formatThreadRecord({ repository, issueNumber, threadId })}`],
+    { stdio: "inherit", env: process.env },
+  );
+}
+
+function resolveExecutable(name) {
+  for (const directory of (process.env.PATH ?? "").split(delimiter)) {
+    if (!directory) continue;
+    const candidate = join(directory, name);
+    try {
+      accessSync(candidate, constants.X_OK);
+      return realpathSync(candidate);
+    } catch {}
+  }
+  throw new Error(`Unable to resolve ${name} from PATH`);
+}
+
+function requiredEnv(name) {
+  const value = process.env[name];
+  if (!value) throw new Error(`${name} is required`);
+  return value;
+}
+
+const codexExecutable = resolveExecutable("codex");
+const ghExecutable = resolveExecutable("gh");
+const nodeExecutable = resolveExecutable("node");
+const homebrewLib = ghExecutable.includes("/Cellar/") ? `${ghExecutable.split("/Cellar/")[0]}/lib` : null;
+const homebrewLibPermission = homebrewLib ? `,${JSON.stringify(homebrewLib)}="read"` : "";
+const filesystemPermissions = `permissions.github-contributor.filesystem={glob_scan_max_depth=3,":minimal"="read",${JSON.stringify(codexExecutable)}="read",${JSON.stringify(ghExecutable)}="read",${JSON.stringify(nodeExecutable)}="read"${homebrewLibPermission},":workspace_roots"={"."="write",".git"="write",".codex"="read","**/*.env"="deny"}}`;
+const gitContributorConfig = [
+  "-c", 'default_permissions="github-contributor"',
+  "-c", "features.network_proxy=true",
+  "-c", 'permissions.github-contributor.description="Write the current checkout including Git metadata and reach GitHub and Agent Skills"',
+  "-c", filesystemPermissions,
+  "-c", 'permissions.github-contributor.network={enabled=true,allow_upstream_proxy=true,allow_local_binding=true,domains={"github.com"="allow","api.github.com"="allow","uploads.github.com"="allow","objects.githubusercontent.com"="allow","raw.githubusercontent.com"="allow","agentskills.io"="allow"}}',
+];
+
+const server = spawn("codex", ["app-server", ...gitContributorConfig, "--strict-config", "--listen", "stdio://"], {
+  cwd: process.cwd(),
+  env: process.env,
+  stdio: ["pipe", "pipe", "pipe"],
+});
+server.stderr.on("data", (chunk) => process.stderr.write(chunk));
+
+let nextId = 1;
+const pending = new Map();
+const activeTurns = new Map();
+const completedStopHooks = new Map();
+const awaitingStopHooks = new Map();
+let stopHookCount = 0;
+let cancellationSignal = null;
+let forcedCancellation = false;
+let threadId = null;
+let goal = null;
+
+function send(message) {
+  server.stdin.write(`${JSON.stringify(message)}\n`);
+}
+
+function request(method, params) {
+  const id = nextId++;
+  send({ method, id, params });
+  return new Promise((resolve, reject) => pending.set(id, { method, resolve, reject }));
+}
+
+const lines = createInterface({ input: server.stdout });
+lines.on("line", (line) => {
+  const message = JSON.parse(line);
+  if (message.id !== undefined && pending.has(message.id)) {
+    const entry = pending.get(message.id);
+    pending.delete(message.id);
+    if (message.error) entry.reject(new Error(`${entry.method}: ${JSON.stringify(message.error)}`));
+    else entry.resolve(message.result);
+    return;
+  }
+  if (message.method === "thread/goal/updated") {
+    goal = message.params.goal;
+    console.log(`GOAL status=${goal.status} tokens=${goal.tokensUsed} seconds=${goal.timeUsedSeconds}`);
+  } else if (message.method === "turn/started") {
+    activeTurns.set(message.params.turn.id, message.params.threadId);
+    console.log(`TURN_STARTED ${message.params.turn.id}`);
+  } else if (message.method === "turn/completed") {
+    activeTurns.delete(message.params.turn.id);
+    const completed = completedStopHooks.get(message.params.turn.id)?.size ?? 0;
+    if (shouldAwaitStopHooks({
+      turnThreadId: message.params.threadId,
+      goalThreadId: threadId,
+      completedHookCount: completed,
+      configuredHookCount: stopHookCount,
+    })) {
+      awaitingStopHooks.set(message.params.turn.id, Date.now() + STOP_HOOK_WAIT_TIMEOUT_MS);
+    }
+    console.log(`TURN_COMPLETED ${message.params.turn.id} ${message.params.turn.status}`);
+  } else if (message.method === "hook/completed" && message.params.run.eventName === "stop") {
+    const turnId = message.params.turnId;
+    if (turnId) {
+      const completed = completedStopHooks.get(turnId) ?? new Set();
+      completed.add(message.params.run.id);
+      completedStopHooks.set(turnId, completed);
+      if (completed.size >= stopHookCount) awaitingStopHooks.delete(turnId);
+      console.log(`STOP_HOOK_COMPLETED ${turnId} ${message.params.run.status}`);
+    }
+  }
+});
+
+function requestCancellation(signal) {
+  if (cancellationSignal) {
+    forcedCancellation = true;
+    server.kill("SIGTERM");
+    return;
+  }
+  cancellationSignal = signal;
+  console.log(`CANCEL_REQUESTED ${signal}`);
+  for (const [turnId, activeThreadId] of activeTurns) {
+    void request("turn/interrupt", { threadId: activeThreadId, turnId }).catch((error) => {
+      console.error(`TURN_INTERRUPT_FAILED ${turnId} ${error.message}`);
+    });
+  }
+}
+
+process.on("SIGINT", requestCancellation);
+process.on("SIGTERM", requestCancellation);
+
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function waitForGoal() {
+  const deadline = Date.now() + 110 * 60 * 1000;
+  while (Date.now() < deadline) {
+    const expiredStopHooks = expireStopHookTimeouts(awaitingStopHooks);
+    for (const turnId of expiredStopHooks) console.warn(`STOP_HOOK_TIMEOUT ${turnId}`);
+    if (expiredStopHooks.length > 0 && goal?.status === "active" && activeTurns.size === 0) {
+      throw new Error("Stop hook timed out while Goal remains active; rerun the workflow to resume");
+    }
+    if (forcedCancellation) throw new Error(`Forced cancellation after ${cancellationSignal}`);
+    if (cancellationSignal && activeTurns.size === 0 && awaitingStopHooks.size === 0) {
+      console.log(`CANCEL_DRAINED ${cancellationSignal}`);
+      throw new Error(`Cancelled by ${cancellationSignal}`);
+    }
+    if (goal && goal.status !== "active" && activeTurns.size === 0 && awaitingStopHooks.size === 0) return goal;
+    await delay(500);
+  }
+  throw new Error("Timed out waiting for Goal terminal state");
+}
+
+try {
+  await request("initialize", {
+    clientInfo: { name: "github-development-ticket", version: "0.1.2" },
+    capabilities: { experimentalApi: true },
+  });
+  send({ method: "initialized" });
+
+  const hookList = await request("hooks/list", { cwds: [process.cwd()] });
+  stopHookCount = hookList.data
+    .flatMap((entry) => entry.hooks)
+    .filter((hook) => hook.enabled && hook.eventName === "stop" && ["managed", "trusted"].includes(hook.trustStatus))
+    .length;
+  console.log(`STOP_HOOKS_CONFIGURED ${stopHookCount}`);
+
+  const record = getThreadRecord();
+  if (record) {
+    threadId = record.threadId;
+    await request("thread/resume", {
+      threadId,
+      cwd: process.cwd(),
+      permissions: "github-contributor",
+      approvalPolicy: "never",
+    });
+    const recovered = await request("thread/goal/get", { threadId });
+    goal = recovered.goal;
+    console.log(`THREAD_RESUMED ${threadId} status=${goal?.status ?? "missing"}`);
+    if (goal?.status === "complete") process.exitCode = 0;
+    else {
+      const resized = await request("thread/goal/set", { threadId, tokenBudget });
+      goal = resized.goal;
+      console.log(`GOAL_BUDGET_UPDATED ${goal.tokensUsed}/${goal.tokenBudget ?? "unlimited"}`);
+      goal = { ...goal, status: "active" };
+      const activated = await request("thread/goal/set", { threadId, status: "active" });
+      goal = activated.goal;
+    }
+  } else {
+    const started = await request("thread/start", {
+      cwd: process.cwd(),
+      permissions: "github-contributor",
+      approvalPolicy: "never",
+      ephemeral: false,
+    });
+    threadId = started.thread.id;
+    await request("thread/goal/set", {
+      threadId,
+      objective: goalPrompt,
+      status: "active",
+      tokenBudget,
+    });
+    saveThreadRecord(threadId);
+    console.log(`THREAD_CREATED ${threadId}`);
+  }
+
+  if (goal?.status !== "complete") {
+    const result = await waitForGoal();
+    console.log(`FINAL_GOAL=${JSON.stringify(result)}`);
+    if (result.status !== "complete") throw new Error(`Goal stopped with ${result.status}`);
+  } else {
+    console.log(`FINAL_GOAL=${JSON.stringify(goal)}`);
+  }
+} finally {
+  lines.close();
+  server.kill("SIGTERM");
+}

package/templates/development/.github/graph-engineering/stop-hook-drain.mjs

@@ -0,0 +1,20 @@
+export const STOP_HOOK_WAIT_TIMEOUT_MS = 60_000;
+
+export function shouldAwaitStopHooks({
+  turnThreadId,
+  goalThreadId,
+  completedHookCount,
+  configuredHookCount,
+}) {
+  return turnThreadId === goalThreadId && completedHookCount < configuredHookCount;
+}
+
+export function expireStopHookTimeouts(awaitingStopHooks, now = Date.now()) {
+  const expired = [];
+  for (const [turnId, deadline] of awaitingStopHooks) {
+    if (deadline > now) continue;
+    awaitingStopHooks.delete(turnId);
+    expired.push(turnId);
+  }
+  return expired;
+}

package/templates/development/.github/graph-engineering/thread-record.mjs

@@ -0,0 +1,39 @@
+export const RECORD_KIND = "graph-engineering:github-development-ticket:v0.3.0";
+export const LEGACY_RECORD_KIND = "loop-engineering:github-development-ticket:v0.1.0";
+
+export function formatThreadRecord({ repository, issueNumber, threadId }) {
+  return [
+    "Codex Goal Thread 已创建；相同 Ticket 的后续运行将恢复该 Thread。",
+    "",
+    `<!-- ${RECORD_KIND}`,
+    `repository=${repository}`,
+    `issue=${issueNumber}`,
+    `thread=${threadId}`,
+    "-->",
+  ].join("\n");
+}
+
+export function parseThreadRecord(body) {
+  if (typeof body !== "string") return null;
+  for (const kind of [RECORD_KIND, LEGACY_RECORD_KIND]) {
+    const pattern = new RegExp(
+      `<!--\\s*${escapeRegExp(kind)}\\s+repository=([^\\s]+)\\s+issue=(\\d+)\\s+thread=([^\\s]+)\\s*-->`,
+    );
+    const match = body.match(pattern);
+    if (match) return { repository: match[1], issueNumber: Number(match[2]), threadId: match[3] };
+  }
+  return null;
+}
+
+export function findThreadRecord(comments, { repository, issueNumber }) {
+  for (const comment of [...comments].reverse()) {
+    if (comment?.user?.login !== "github-actions[bot]") continue;
+    const record = parseThreadRecord(comment.body);
+    if (record?.repository === repository && record.issueNumber === Number(issueNumber)) return record;
+  }
+  return null;
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/templates/development/.github/workflows/github-development-ticket.yml

@@ -0,0 +1,124 @@
+name: Graph Engineering - GitHub Development Ticket
+
+on:
+  issues:
+    types: [labeled]
+  workflow_dispatch:
+    inputs:
+      issue_number:
+        description: Issue number to start or resume
+        required: true
+        type: number
+      goal_token_budget:
+        description: Total Goal token budget, or unlimited to clear the token limit
+        required: false
+        default: "500000"
+        type: string
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+
+concurrency:
+  group: github-development-ticket-${{ github.repository }}-${{ github.event.issue.number || inputs.issue_number }}
+  cancel-in-progress: false
+
+jobs:
+  implement:
+    if: >-
+      github.event_name == 'workflow_dispatch' ||
+      (github.event.action == 'labeled' && github.event.label.name == 'development-ticket')
+    runs-on: [self-hosted, Linux, X64]
+    timeout-minutes: 120
+    env:
+      GH_TOKEN: ${{ github.token }}
+      ISSUE_NUMBER: ${{ github.event.issue.number || inputs.issue_number }}
+      BASE_BRANCH: ${{ github.event.repository.default_branch || 'main' }}
+      TARGET_BRANCH: agent/issue-${{ github.event.issue.number || inputs.issue_number }}
+      GOAL_TOKEN_BUDGET: ${{ inputs.goal_token_budget || '500000' }}
+    steps:
+      - name: Validate Development Ticket
+        shell: bash
+        run: |
+          set -euo pipefail
+          test "$(gh issue view "${ISSUE_NUMBER}" --repo "${GITHUB_REPOSITORY}" --json state --jq .state)" = "OPEN"
+          test "$(gh issue view "${ISSUE_NUMBER}" --repo "${GITHUB_REPOSITORY}" --json labels \
+            --jq 'any(.labels[]; .name == "ready-for-agent")')" = true
+          test "$(gh issue view "${ISSUE_NUMBER}" --repo "${GITHUB_REPOSITORY}" --json labels \
+            --jq 'any(.labels[]; .name == "development-ticket")')" = true
+
+      - name: Preserve interrupted Ticket work
+        shell: bash
+        run: |
+          set -euo pipefail
+          if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+            current_branch="$(git branch --show-current)"
+            test -n "${current_branch}"
+            if test "${current_branch}" = "${TARGET_BRANCH}"; then
+              interrupted_ref="refs/graph-engineering/interrupted/${TARGET_BRANCH}"
+              interrupted_stash_ref="refs/graph-engineering/interrupted-stash/${TARGET_BRANCH}"
+              git update-ref -d "${interrupted_ref}"
+              git update-ref -d "${interrupted_stash_ref}"
+              if git ls-remote --exit-code origin "refs/heads/${TARGET_BRANCH}" >/dev/null 2>&1; then
+                git fetch origin "${TARGET_BRANCH}"
+                if ! git merge-base --is-ancestor HEAD "origin/${TARGET_BRANCH}"; then
+                  git update-ref "${interrupted_ref}" HEAD
+                fi
+              else
+                git update-ref "${interrupted_ref}" HEAD
+              fi
+            fi
+            if test -n "$(git status --porcelain)"; then
+              git stash push --include-untracked \
+                --message "graph-engineering:${GITHUB_REPOSITORY}:${current_branch}"
+              if test "${current_branch}" = "${TARGET_BRANCH}"; then
+                git update-ref "${interrupted_stash_ref}" refs/stash
+              fi
+            fi
+          fi
+
+      - name: Check out default branch
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          ref: ${{ env.BASE_BRANCH }}
+          fetch-depth: 0
+
+      - name: Prepare development branch
+        run: bash .github/graph-engineering/development-worktree.sh prepare
+
+      - name: Restore interrupted Ticket work
+        run: bash .github/graph-engineering/development-worktree.sh restore
+
+      - name: Mark Ticket in progress
+        shell: bash
+        run: gh issue edit "${ISSUE_NUMBER}" --add-label in-progress
+
+      - name: Configure Git identity
+        shell: bash
+        run: |
+          git config user.name "codex[bot]"
+          git config user.email "codex[bot]@users.noreply.github.com"
+
+      - name: Start or resume Goal
+        shell: bash
+        run: node .github/graph-engineering/github-development-ticket.mjs
+
+      - name: Verify Codex delivery
+        shell: bash
+        run: |
+          set -euo pipefail
+          test -z "$(git status --porcelain)"
+          test "$(git rev-list --count "origin/${BASE_BRANCH}..HEAD")" -gt 0
+          test "$(git rev-parse HEAD)" = "$(git ls-remote origin "refs/heads/${TARGET_BRANCH}" | cut -f1)"
+          test "$(gh pr list --head "${TARGET_BRANCH}" --base "${BASE_BRANCH}" --state open \
+            --json url,isDraft,state \
+            --jq 'length == 1 and .[0].isDraft and .[0].state == "OPEN"')" = true
+
+      - name: Mark Ticket delivery complete
+        shell: bash
+        run: |
+          set -euo pipefail
+          gh issue edit "${ISSUE_NUMBER}" \
+            --remove-label development-ticket \
+            --remove-label in-progress

package/templates/pr-review/.github/graph-engineering/capture-review.mjs

@@ -0,0 +1,16 @@
+import { writeFile } from "node:fs/promises";
+
+import { mapActionExecution } from "./pr-review-case.mjs";
+
+const target = JSON.parse(process.env.TRUSTED_TARGET);
+const execution = mapActionExecution({
+  actionOutcome: process.env.ACTION_OUTCOME ?? "success",
+  finalMessage: process.env.FINAL_MESSAGE,
+}, target);
+
+await writeFile("review-execution.json", `${JSON.stringify(execution, null, 2)}\n`);
+if (execution.review) await writeFile("review-result.json", `${JSON.stringify(execution.review, null, 2)}\n`);
+if (process.env.GITHUB_OUTPUT) {
+  await writeFile(process.env.GITHUB_OUTPUT, `terminal=${execution.terminal}\n`, { flag: "a" });
+}
+if (execution.terminal !== "completed") throw new Error(execution.diagnostic);

package/templates/pr-review/.github/graph-engineering/check-publication.mjs

@@ -0,0 +1,23 @@
+export const CHECK_NAME = "Graph Engineering / PR Review";
+export const DEFINITION_ID = "github-pr-review/current";
+
+export function checkExternalId(target) {
+  return `${DEFINITION_ID}:${target.repository}:pull-request:${target.number}:${target.headSha}`;
+}
+
+export function planCheckPublication({ target, existingChecks, checkName = CHECK_NAME }) {
+  const externalId = checkExternalId(target);
+  const matches = existingChecks.filter((check) => (
+    check.name === checkName
+    && check.head_sha === target.headSha
+    && check.external_id === externalId
+  ));
+  if (matches.length > 1) {
+    throw new Error(`duplicate-review-check: ${matches.length} Checks match ${externalId}`);
+  }
+  const existing = matches[0];
+
+  return existing
+    ? { method: "PATCH", path: `/repos/${target.repository}/check-runs/${existing.id}`, externalId }
+    : { method: "POST", path: `/repos/${target.repository}/check-runs`, externalId };
+}

package/templates/pr-review/.github/graph-engineering/codex-compatibility-profile.json

@@ -0,0 +1,67 @@
+{
+  "definition": "github-pr-review/current",
+  "profile": "github-pr-review/codex/current",
+  "executor": {
+    "id": "codex-compatible-executor",
+    "version": "current"
+  },
+  "runner": {
+    "labels": ["self-hosted", "Linux", "X64", "codex"]
+  },
+  "authentication": {
+    "mode": "runner-backed-codex",
+    "credentialSource": "default-codex-home",
+    "repositorySecret": false
+  },
+  "action": {
+    "source": "tutar/codex-action",
+    "sourceRef": "fix/runner-login-no-proxy",
+    "commit": "f33581290086e62dc34d420a7f1862477fc2b503",
+    "upstream": {
+      "source": "openai/codex-action",
+      "commit": "86365089eb2b84e0a8fb0717b304f8bdcb13b20e"
+    },
+    "patch": "read-proxy-server-info-only-with-openai-api-key",
+    "codexVersion": "0.153.4",
+    "requiredInputs": ["prompt-file", "output-schema-file", "working-directory", "codex-version", "safety-strategy"],
+    "acceptedInputs": ["prompt-file", "output-schema-file", "working-directory", "codex-version", "model", "effort", "permission-profile", "safety-strategy"]
+  },
+  "mapping": {
+    "goalPrompt": "prompt-file",
+    "reviewSchema": "output-schema-file",
+    "codexVersion": "codex-version",
+    "workingDirectory": "working-directory",
+    "model": "model",
+    "reasoningEffort": "effort",
+    "safetyStrategy": "safety-strategy",
+    "terminal": "step-outcome",
+    "finalMessage": "final-message"
+  },
+  "outputs": ["final-message"],
+  "permissions": {
+    "reviewJob": {
+      "contents": "read",
+      "pull-requests": "read",
+      "checks": "read"
+    },
+    "publishJob": {
+      "contents": "read",
+      "pull-requests": "read",
+      "checks": "write"
+    }
+  },
+  "consumerConfiguration": {
+    "pullRequestActions": ["opened", "reopened", "synchronize", "ready_for_review"],
+    "manualDispatch": "boolean",
+    "includeDrafts": [false],
+    "modelPattern": "^[A-Za-z0-9._-]*$",
+    "reasoningEfforts": ["", "low", "medium", "high", "xhigh"],
+    "safetyStrategies": ["read-only"],
+    "checkTextMaxLength": 100
+  },
+  "validation": {
+    "failClosed": true,
+    "resultSchema": "review-result.schema.json",
+    "terminals": ["completed", "handoff", "failed", "cancelled"]
+  }
+}