@defend-tech/opencode-optima 0.1.72 → 0.1.74

package/assets/agents/workflow_product_manager.md

@@ -45,8 +45,8 @@ You are Workflow_Product_Manager, Optima's ClickUp-first delivery orchestrator.
 - `backlog`: ignore until prioritized.
 - `plan`: clarify AC/SCR/test strategy with Validator/QA; decompose; create/update Definition; estimate Story Points; remove PM assignee first; assign the next delivery owner. Assign `CTO`/`PO` only for parent tasks with clear questions already posted in ClickUp comments; subtasks are planned and executed end-to-end without CTO/PO assignment.
 - `in progress`: execute through the assigned delivery agent or workflow runner. Treat blockers as work to solve first: spawn or resume Coder for code/build/dependency failures, QA for validation/test/evidence failures, Tech Lead for architecture/review/merge failures, and the relevant specialist for domain blockers. Escalate to `CTO`/`PO` only when genuinely blocked by missing credentials, permissions, external tools, or access after local/subagent resolution attempts; do not stop with phase language such as "I reached phase 1" or "no non-human assignee is available".
-- `validation`: before moving any task/subtask into Validation, create or update the required GitHub PR and store its URL/number in ClickUp `agent_metadata`. Subtasks PR from their subtask branch into the parent task branch. Parent tasks PR from the task branch into `dev`. A task in Validation without an open PR is invalid: move it back to `in progress`, open/update the PR, then return it to Validation. Route Tech Lead for architecture/code/PR/standards/repo-skill review and Validator/QA for tests, Playwright/regression/coverage/evidence/final-doc checks.
-- GitHub review wakeups: keep listening for PR review/comment webhooks. Reply in GitHub to human comments. If a comment asks for or implies a change, reply first with what you will do, move the ClickUp task/subtask to `in progress`, delegate/implement the fix, push the same branch, update the PR, move ClickUp back to `validation`, then reply again in GitHub with what changed. Also add concise ClickUp status comments for model work state; never post Optima runtime/process noise.
+- `validation`: before moving any task/subtask into Validation, create or update the required GitHub PR, store its URL/number in ClickUp `agent_metadata`, and leave a concise model-owned ClickUp status comment with the PR link, source branch, target branch, and current validation owner. Subtasks PR from their subtask branch into the parent task branch. Parent tasks PR from the task branch into `dev`. A task in Validation without an open PR link visible in ClickUp is invalid: move it back to `in progress`, open/update the PR, post/update the ClickUp PR-link status, then return it to Validation. Route Tech Lead for architecture/code/PR/standards/repo-skill review and Validator/QA for tests, Playwright/regression/coverage/evidence/final-doc checks.
+- GitHub review wakeups: keep listening for PR review/comment webhooks. Reply in GitHub to human comments. If a comment asks for or implies a change, reply first with what you will do, move the ClickUp task/subtask to `in progress`, delegate/implement the fix, push the same branch, update the PR, move ClickUp back to `validation`, then reply again in GitHub with what changed. Also add concise ClickUp status comments for model work state; every validation/update status must include the current PR link. Never post Optima runtime/process noise.
 - `merge`: parent-only post-approval automation after the configured final approver/CTO approves the GitHub PR. The GitHub accepted/approved review is the merge trigger. Merge the parent PR into `dev`, verify the Vercel preproduction deployment updates automatically, run a small smoke/regression against preproduction, and only then clean workspaces/worktrees/branches and move ClickUp to `completed`. If merge, Vercel deployment, or regression fails, create Bug subtasks under the parent task, move the parent back to `in progress`, and keep the evidence/PR links in ClickUp.
 - `completed` / `Closed`: no execution unless explicitly reopened.
 
@@ -62,7 +62,7 @@ You are Workflow_Product_Manager, Optima's ClickUp-first delivery orchestrator.
 - Parent setup pulls remote once; after parent branch creation, subtasks can trust the parent local branch without continuous remote polling.
 - Branches: parent `<clickup-task-type>/<parent-task-id>`; subtask `<clickup-task-type>/<parent-task-id>-subtask-<subtask-id>`; pending planned subtasks `<clickup-task-type>/<parent-task-id>-pending-<title-slug>`; PoC always `poc/<clickup-task-id>` and remains there unless productized later.
 - PR targets/start points: subtask -> parent branch and starts from the parent branch; if parent branch/worktree is missing, bootstrap the parent from `dev`/`origin/dev` first. Parent task -> `dev` through a GitHub PR before entering Validation. Release -> `dev` to `main` only after explicit approval.
-- Required PR gate: every transition into `validation` must have an open GitHub PR. Do not mark Validation with only local commits, evidence, or ClickUp comments.
+- Required PR gate: every transition into `validation` must have an open GitHub PR and a ClickUp-visible model status comment containing that PR link. Do not mark Validation with only local commits, evidence, or comments without the PR URL.
 - Review/merge cleanup: after the configured final approver/CTO approves and the PR is merged, keep the OpenCode session ids in ClickUp `agent_metadata`; delete only the merged branch/worktree after Vercel preproduction and smoke regression pass. If the task is reopened later, recreate/register the worktree from metadata/branch context and resume the preserved sessions.
 - Final completion gate: parent task completion requires merged PR, Vercel preproduction deployment verified, smoke/regression evidence captured, no open review-change requests, final ClickUp comment with result, and status `completed`.
 - Preserve user work and unrelated dirty files. Stop and ask if unexpected changes appear.

package/dist/index.js

@@ -8627,6 +8627,7 @@ var activeWorkflows = /* @__PURE__ */ new Map();
 var activeClickUpWebhookListeners = /* @__PURE__ */ new Map();
 var activeClickUpWebhookLifecycleRegistry = /* @__PURE__ */ new Map();
 var activeClickUpTaskRoutes = /* @__PURE__ */ new Map();
+var GITHUB_WEBHOOK_EVENTS = ["pull_request", "pull_request_review", "pull_request_review_comment", "issue_comment"];
 function isRootDirectory(candidate) {
   const resolved = path6.resolve(candidate);
   return resolved === path6.parse(resolved).root;
@@ -9880,9 +9881,48 @@ function normalizeNonNegativeInteger(value, defaultValue) {
   const number = Number(value);
   return Number.isInteger(number) && number >= 0 ? number : defaultValue;
 }
+function defaultGitHubWebhookPublicUrl(clickupPublicUrl = "") {
+  const raw = String(clickupPublicUrl || "").trim();
+  if (!raw) return "";
+  try {
+    const url = new URL(raw);
+    url.pathname = "/optima/github/webhook";
+    url.search = "";
+    url.hash = "";
+    return url.toString();
+  } catch {
+    return raw.replace(/\/optima\/clickup\/webhook\b/, "/optima/github/webhook");
+  }
+}
+function normalizeGitHubWebhookConfig(rawGithub = {}, clickupWebhook = {}) {
+  const github = isPlainObject(rawGithub) ? rawGithub : {};
+  const webhook = isPlainObject(github.webhook) ? github.webhook : {};
+  const enabled = github.enabled === true || webhook.enabled === true;
+  const events = Array.isArray(webhook.events) && webhook.events.length > 0 ? [...new Set(webhook.events.map((event) => String(event || "").trim()).filter(Boolean))] : [...GITHUB_WEBHOOK_EVENTS];
+  const publicUrl = String(webhook.public_url || webhook.publicUrl || github.public_url || github.publicUrl || defaultGitHubWebhookPublicUrl(clickupWebhook.publicUrl)).trim();
+  const secret = String(webhook.secret || github.secret || "").trim();
+  const apiToken = String(github.api_token || github.apiToken || "").trim();
+  const repository = String(github.repository || github.repo || "").trim();
+  const [ownerFromRepo, nameFromRepo] = repository.includes("/") ? repository.split("/", 2) : ["", ""];
+  return {
+    enabled,
+    apiToken,
+    repository,
+    owner: String(github.owner || ownerFromRepo || "").trim(),
+    repo: String(github.repo_name || github.repoName || nameFromRepo || "").trim(),
+    webhook: {
+      enabled,
+      publicUrl,
+      secret,
+      path: publicUrl ? new URL(publicUrl, "http://localhost").pathname : "/optima/github/webhook",
+      events
+    }
+  };
+}
 function normalizeClickUpWebhookConfig(rawClickUp = null, worktree = process.cwd()) {
   const raw = isPlainObject(rawClickUp) ? rawClickUp : {};
   const webhook = isPlainObject(raw.webhook) ? raw.webhook : {};
+  const github = normalizeGitHubWebhookConfig(raw.github, { publicUrl: String(webhook.public_url || webhook.publicUrl || "").trim() });
   const routing = isPlainObject(raw.routing) ? raw.routing : {};
   const opencode = isPlainObject(raw.opencode) ? raw.opencode : {};
   const openchamber = isPlainObject(raw.openchamber) ? raw.openchamber : {};
@@ -9935,6 +9975,7 @@ function normalizeClickUpWebhookConfig(rawClickUp = null, worktree = process.cwd
       },
       events
     },
+    github,
     routing: {
       targetAgent: String(routing.target_agent || routing.targetAgent || "workflow_product_manager").trim(),
       productManagerAssigneeId: String(routing.product_manager_assignee_id || routing.productManagerAssigneeId || "").trim(),
@@ -9956,6 +9997,13 @@ function normalizeClickUpWebhookConfig(rawClickUp = null, worktree = process.cwd
   if (!config.webhook.bindHost) errors.push("clickup.webhook.bind_host is required");
   if (!Number.isInteger(config.webhook.bindPort) || config.webhook.bindPort <= 0) errors.push("clickup.webhook.bind_port must be a positive integer");
   if (!config.webhook.location.list_id && !config.webhook.location.folder_id && !config.webhook.location.space_id) errors.push("one clickup.webhook.location id is required");
+  if (config.github.webhook.enabled) {
+    if (!config.github.webhook.publicUrl) errors.push("clickup.github.webhook.public_url is required when GitHub webhook is enabled");
+    if (!config.github.webhook.secret) errors.push("clickup.github.webhook.secret is required when GitHub webhook is enabled");
+    if (!config.github.webhook.path || config.github.webhook.path === clickUpWebhookExpectedPath(config)) errors.push("clickup.github.webhook.path must be distinct from the ClickUp webhook path");
+    const missingGitHubEvents = GITHUB_WEBHOOK_EVENTS.filter((event) => !config.github.webhook.events.includes(event));
+    if (missingGitHubEvents.length > 0) errors.push(`clickup.github.webhook.events missing: ${missingGitHubEvents.join(", ")}`);
+  }
   if (config.opencode.baseUrl) {
     try {
       new URL(config.opencode.baseUrl);
@@ -9993,6 +10041,8 @@ function sanitizeClickUpWebhookState(state = {}, config = null) {
     listener: isPlainObject(state.listener) ? state.listener : {},
     pendingSessions: isPlainObject(state.pendingSessions) ? state.pendingSessions : {},
     lastWebhookAt: state.lastWebhookAt || state.last_webhook_at || null,
+    githubLastWebhookAt: state.githubLastWebhookAt || state.github_last_webhook_at || null,
+    githubRecentEventKeys: Array.isArray(state.githubRecentEventKeys) ? state.githubRecentEventKeys.slice(-200) : [],
     recentEventKeys
   };
 }
@@ -10109,6 +10159,29 @@ function createClickUpApiClient(config, fetchImpl = globalThis.fetch) {
     }
   };
 }
+function createGitHubApiClient(config = {}, fetchImpl = globalThis.fetch) {
+  const token = resolveSecretReference(config?.apiToken);
+  const owner = String(config?.owner || "").trim();
+  const repo = String(config?.repo || "").trim();
+  const request = async (pathname) => {
+    if (typeof fetchImpl !== "function") throw new Error("fetch is unavailable; inject a GitHub client for live PR lookup");
+    if (!owner || !repo) throw new Error("GitHub repository owner/repo is not configured");
+    const response = await fetchImpl(`https://api.github.com/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}${pathname}`, {
+      headers: {
+        Accept: "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+        ...token ? { Authorization: `Bearer ${token}` } : {}
+      }
+    });
+    if (!response.ok) throw new Error(`GitHub API request failed: ${response.status}`);
+    return response.json();
+  };
+  return {
+    async getPullRequest(number) {
+      return request(`/pulls/${encodeURIComponent(number)}`);
+    }
+  };
+}
 function createTestClickUpApiClient(config) {
   const metadata = /* @__PURE__ */ new Map();
   return {
@@ -10339,6 +10412,19 @@ function verifyClickUpSignature(rawBody, signatureHeader, secret) {
   const wanted = Buffer.from(expected, "hex");
   return given.length === wanted.length && crypto.timingSafeEqual(given, wanted);
 }
+function verifyGitHubSignature(rawBody, signatureHeader, secret) {
+  return verifyClickUpSignature(rawBody, signatureHeader, secret);
+}
+function gitHubWebhookEventKey({ headers = {}, event = "", payload = {} } = {}) {
+  const delivery = headers["x-github-delivery"] || headers["X-GitHub-Delivery"] || payload.delivery || payload.delivery_id || "";
+  const id = delivery || payload.pull_request?.id || payload.comment?.id || payload.review?.id || payload.issue?.id || "unknown";
+  return ["github", event || headers["x-github-event"] || headers["X-GitHub-Event"] || "event", id].filter(Boolean).join(":");
+}
+function rememberGitHubWebhookEvent(state = {}, eventKey, limit = 200) {
+  const recent = Array.isArray(state.githubRecentEventKeys) ? state.githubRecentEventKeys : [];
+  if (recent.includes(eventKey)) return { duplicate: true, state };
+  return { duplicate: false, state: { ...state, githubRecentEventKeys: [...recent, eventKey].slice(-limit) } };
+}
 async function resyncClickUpWebhookForSignatureDrift({ rawBody, signature, config, state = {}, worktree = process.cwd(), clickupClient, saveState } = {}) {
   const validation = clickUpWebhookValidationFromConfig(config);
   if (!clickupClient?.listWebhooks && !clickupClient?.createWebhook) {
@@ -10545,6 +10631,105 @@ function clickUpTaskAgentMetadata(task = {}, fieldId = "") {
   const field = fields.find((item) => String(item?.id || "") === fieldId || String(item?.name || "") === "agent_metadata");
   return field?.value || "";
 }
+function gitHubWebhookExpectedPath(config = {}) {
+  return config?.github?.webhook?.path || "/optima/github/webhook";
+}
+function gitHubWebhookEnabled(config = {}) {
+  return Boolean(config?.github?.webhook?.enabled && resolveSecretReference(config?.github?.webhook?.secret));
+}
+function clickUpTaskIdFromGitHubBranch(branch = "") {
+  const tail = String(branch || "").trim().split("/").filter(Boolean).at(-1) || "";
+  if (!tail) return "";
+  const subtask = tail.match(/-subtask-(.+)$/);
+  return branchSafeClickUpId(subtask ? subtask[1] : tail);
+}
+async function gitHubPullRequestContextFromPayload(payload = {}, event = "", githubClient = null) {
+  let pr = payload.pull_request || null;
+  if (!pr && event === "issue_comment" && payload.issue?.pull_request && githubClient?.getPullRequest) {
+    pr = await githubClient.getPullRequest(payload.issue.number);
+  }
+  if (!pr) return null;
+  const headRef = String(pr.head?.ref || pr.head_ref || "").trim();
+  const baseRef = String(pr.base?.ref || pr.base_ref || "").trim();
+  return {
+    number: pr.number || payload.issue?.number || "",
+    id: pr.id || "",
+    url: pr.html_url || pr.url || "",
+    title: pr.title || payload.issue?.title || "",
+    state: pr.state || "",
+    merged: pr.merged === true,
+    headRef,
+    baseRef,
+    taskId: clickUpTaskIdFromGitHubBranch(headRef),
+    repository: pr.head?.repo?.full_name || pr.base?.repo?.full_name || payload.repository?.full_name || ""
+  };
+}
+function gitHubWebhookCommentBody(payload = {}) {
+  return String(payload.comment?.body || payload.review?.body || payload.pull_request?.body || "").trim();
+}
+function formatGitHubWebhookPrompt({ event = "", action = "", pr = {}, payload = {}, taskId = "" } = {}) {
+  const sender = payload.sender?.login || payload.comment?.user?.login || payload.review?.user?.login || "unknown";
+  const reviewState = String(payload.review?.state || "").trim();
+  const commentBody = gitHubWebhookCommentBody(payload);
+  const lines = [
+    "[GitHub Webhook Event]",
+    `Event: ${event}`,
+    `Action: ${action || "unknown"}`,
+    `Task ID: ${taskId || pr.taskId || "unknown"}`,
+    `Pull Request: #${pr.number || "unknown"} ${pr.url || ""}`.trim(),
+    `PR Branch: ${pr.headRef || "unknown"} -> ${pr.baseRef || "unknown"}`,
+    `Sender: ${sender}`,
+    reviewState ? `Review State: ${reviewState}` : null,
+    commentBody ? ["", "Comment/Review Body:", commentBody].join("\n") : null,
+    "",
+    "Required handling:",
+    "- Answer human GitHub comments in GitHub.",
+    "- If the comment/review implies a change, reply first with what you will do, move the ClickUp task/subtask to in progress, implement/fix in the same branch, push, return ClickUp to validation, update the PR, and reply again with what changed.",
+    "- If this is an approved parent PR by the configured final approver/CTO, continue the merge-to-dev, Vercel preproduction verification, smoke regression, cleanup, and ClickUp completion workflow.",
+    "- Keep Optima runtime/process failures out of ClickUp comments; use local logs for process noise."
+  ].filter(Boolean);
+  return lines.join("\n");
+}
+function mergeGitHubWebhookMetadata(existingMetadata, { pr = {}, event = "", action = "", delivery = "" } = {}) {
+  const current = normalizeAgentMetadataJson(existingMetadata);
+  const next = {
+    ...current,
+    task: {
+      ...isPlainObject(current.task) ? current.task : {},
+      github: {
+        ...isPlainObject(current.task?.github) ? current.task.github : {},
+        pull_request: Object.fromEntries(Object.entries({
+          number: pr.number || void 0,
+          url: pr.url || void 0,
+          source_branch: pr.headRef || void 0,
+          target_branch: pr.baseRef || void 0,
+          repository: pr.repository || void 0
+        }).filter(([, value]) => value !== void 0 && value !== "")),
+        last_webhook: {
+          event,
+          action,
+          delivery,
+          at: (/* @__PURE__ */ new Date()).toISOString()
+        }
+      }
+    }
+  };
+  return JSON.stringify(sortJsonValue(next), null, 2);
+}
+function summarizeGitHubRouteForLog(result = {}, payload = {}, event = "") {
+  return {
+    taskId: result.taskId || null,
+    event: event || null,
+    eventKey: result.eventKey || null,
+    ok: result.ok === true,
+    action: result.action || null,
+    reason: result.reason || null,
+    sessionId: result.sessionId || null,
+    pullRequest: result.prNumber || payload?.pull_request?.number || payload?.issue?.number || null,
+    branch: result.branch || null,
+    worktree: result.worktree || null
+  };
+}
 function getNestedMetadataValue(metadata, dottedKey) {
   const parts = String(dottedKey || "").split(".").filter(Boolean);
   let cursor = metadata;
@@ -11450,9 +11635,9 @@ function buildClickUpWebhookAuditSummary({ method, url, config, handled, error,
     ok: Boolean(handled?.ok),
     reason: handled?.reason || result.reason || (error ? "handler_error" : void 0),
     action: result.action,
-    event: payload ? clickUpEventType(payload) : void 0,
+    event: result.event || (payload ? clickUpEventType(payload) : void 0),
     task: result.taskId || clickUpTaskIdFromPayload(payload || {}),
-    comment: clickUpCommentFromPayload(payload || {})?.id || payload?.comment_id || payload?.commentId,
+    comment: clickUpCommentFromPayload(payload || {})?.id || payload?.comment_id || payload?.commentId || payload?.comment?.id || payload?.review?.id,
     session: result.sessionId,
     base_path: config?.basePath || "",
     request_file: requestFile || void 0
@@ -11466,7 +11651,13 @@ function writeClickUpWebhookAuditLog({ method, url, headers = {}, rawBody = "",
     if (level === "error" && !failed) return;
     const logDir = clickUpWebhookAuditLogDir();
     fs5.mkdirSync(logDir, { recursive: true });
-    const secretValues = [resolveSecretReference(config?.apiToken), state?.secret, config?.webhook?.secret].filter(Boolean);
+    const secretValues = [
+      resolveSecretReference(config?.apiToken),
+      resolveSecretReference(config?.github?.apiToken),
+      state?.secret,
+      config?.webhook?.secret,
+      resolveSecretReference(config?.github?.webhook?.secret)
+    ].filter(Boolean);
     let requestFile;
     if (level === "verbose") {
       const absoluteRequestFile = clickUpWebhookRequestFilePath(at, logDir);
@@ -11928,6 +12119,176 @@ function runClickUpWebhookRouteInBackground({ payload, config, state, worktree,
   });
   return route;
 }
+async function routeGitHubWebhookEventUnlocked({ payload, event = "", delivery = "", config, state = {}, worktree = process.cwd(), clickupClient, githubClient = null, openCodeClient, sendSessionEvent = sendOpenCodeSessionEvent, verifySessionEventDelivery = verifyOpenCodeSessionEventDelivery } = {}) {
+  const normalizedEvent = String(event || payload?.event || "").trim();
+  const action = String(payload?.action || "").trim();
+  const eventKey = gitHubWebhookEventKey({ headers: { "x-github-delivery": delivery, "x-github-event": normalizedEvent }, event: normalizedEvent, payload });
+  if (!config?.github?.webhook?.events?.includes(normalizedEvent)) {
+    return { ok: true, action: "ignored", reason: "unsupported_event", event: normalizedEvent, eventKey };
+  }
+  let pr;
+  try {
+    pr = await gitHubPullRequestContextFromPayload(payload, normalizedEvent, githubClient);
+  } catch (error) {
+    appendClickUpWebhookLocalLog(worktree, { type: "github_pr_context_failed", event: normalizedEvent, delivery, message: error.message });
+    return { ok: false, action: "error", reason: "pull_request_context_failed", event: normalizedEvent, eventKey, message: error.message };
+  }
+  if (!pr) {
+    appendClickUpWebhookLocalLog(worktree, { type: "github_pr_context_unavailable", event: normalizedEvent, delivery, action });
+    return { ok: true, action: "ignored", reason: "pull_request_context_unavailable", event: normalizedEvent, eventKey };
+  }
+  const taskId = String(pr.taskId || "").trim();
+  if (!taskId) {
+    appendClickUpWebhookLocalLog(worktree, { type: "github_task_id_unavailable", event: normalizedEvent, delivery, prNumber: pr.number || null, headRef: pr.headRef || null });
+    return { ok: false, action: "error", reason: "task_id_unavailable", event: normalizedEvent, eventKey, prNumber: pr.number || null };
+  }
+  const task = payload.task || (clickupClient?.getTask ? await clickupClient.getTask(taskId) : null);
+  if (!task) {
+    appendClickUpWebhookLocalLog(worktree, { type: "github_clickup_task_unavailable", taskId, event: normalizedEvent, delivery, prNumber: pr.number || null });
+    return { ok: false, action: "error", reason: "task_unavailable", taskId, event: normalizedEvent, eventKey, prNumber: pr.number || null };
+  }
+  if (isClickUpTaskTerminal(task, {}, config.routing?.ignoredStatuses)) {
+    return { ok: true, action: "ignored", reason: "terminal_status", taskId, event: normalizedEvent, eventKey, prNumber: pr.number || null };
+  }
+  const existingMetadata = clickUpTaskAgentMetadata(task, config.routing.metadataFieldId);
+  const metadata = normalizeAgentMetadataJson(existingMetadata);
+  const rawSessionId = getNestedMetadataValue(metadata, config.routing.metadataKey) || getNestedMetadataValue(metadata, "optima.sessions.product_manager");
+  const sessionId = typeof rawSessionId === "string" && rawSessionId.startsWith("ses_") ? rawSessionId : "";
+  const directory = String(
+    getNestedMetadataValue(metadata, "task.worktree") || getNestedMetadataValue(metadata, "task.subtask_worktree") || ""
+  ).trim();
+  const branch = String(
+    getNestedMetadataValue(metadata, "task.branch") || getNestedMetadataValue(metadata, "task.subtask_branch") || pr.headRef || ""
+  ).trim();
+  if (!sessionId) {
+    appendClickUpWebhookLocalLog(worktree, { type: "github_session_missing", taskId, event: normalizedEvent, delivery, prNumber: pr.number || null, branch: branch || null });
+    return { ok: false, action: "error", reason: "session_missing", taskId, event: normalizedEvent, eventKey, prNumber: pr.number || null, branch: branch || null };
+  }
+  if (!directory) {
+    appendClickUpWebhookLocalLog(worktree, { type: "github_worktree_missing", taskId, event: normalizedEvent, delivery, sessionId, prNumber: pr.number || null });
+    return { ok: false, action: "error", reason: "worktree_missing", taskId, event: normalizedEvent, eventKey, sessionId, prNumber: pr.number || null, branch: branch || null };
+  }
+  const prompt = formatGitHubWebhookPrompt({ event: normalizedEvent, action, pr, payload, taskId });
+  const nextMetadata = mergeGitHubWebhookMetadata(existingMetadata, { pr, event: normalizedEvent, action, delivery });
+  if (typeof clickupClient?.updateTaskMetadata === "function") {
+    await clickupClient.updateTaskMetadata({ taskId, fieldId: config.routing.metadataFieldId, value: nextMetadata });
+  }
+  const deliveryResult = await deliverClickUpSessionEventWithVerification({
+    openCodeClient,
+    sendSessionEvent,
+    clickupClient,
+    worktree,
+    taskId,
+    sessionId,
+    agent: config.routing.targetAgent,
+    text: prompt,
+    directory,
+    opencodeBaseUrl: config.opencode?.baseUrl,
+    directPrompt: config.opencode?.promptDelivery === "http",
+    directDelivery: "steer",
+    acceptPromptAdmission: config.opencode?.acceptPromptAdmission === true,
+    eventMarkers: [taskId, String(pr.number || ""), normalizedEvent].filter(Boolean),
+    verifySessionEventDelivery,
+    applyBlockerOnFailure: false
+  });
+  if (!deliveryResult.ok) {
+    appendClickUpWebhookLocalLog(worktree, { type: "github_message_delivery_failed", taskId, event: normalizedEvent, delivery, sessionId, prNumber: pr.number || null, reason: deliveryResult.reason || "message_delivery_failed" });
+    return { ...deliveryResult, eventKey, taskId, event: normalizedEvent, prNumber: pr.number || null, branch: branch || pr.headRef || null, worktree: directory };
+  }
+  return {
+    ok: true,
+    action: "github_event_delivered",
+    taskId,
+    sessionId,
+    event: normalizedEvent,
+    eventKey,
+    prNumber: pr.number || null,
+    branch: branch || pr.headRef || null,
+    worktree: directory,
+    deliveryVerification: deliveryResult.verification,
+    deliveryAdmission: deliveryResult.admissionVerification,
+    deliveryFallback: deliveryResult.fallback
+  };
+}
+async function routeGitHubWebhookEvent(options = {}) {
+  let taskId = "";
+  try {
+    const pr = await gitHubPullRequestContextFromPayload(options.payload || {}, options.event || "", options.githubClient || null);
+    taskId = pr?.taskId || "";
+  } catch {
+    taskId = "";
+  }
+  return withClickUpTaskRouteLock(taskId, () => routeGitHubWebhookEventUnlocked(options));
+}
+function runGitHubWebhookRouteInBackground({ payload, event, delivery, config, state, worktree, clickupClient, githubClient, openCodeClient, sendSessionEvent, verifySessionEventDelivery } = {}) {
+  const eventKey = gitHubWebhookEventKey({ headers: { "x-github-delivery": delivery, "x-github-event": event }, event, payload });
+  appendClickUpWebhookLocalLog(worktree, { type: "github_webhook_route_started", event, eventKey, async: true, delivery: delivery || null });
+  const route = Promise.resolve().then(() => routeGitHubWebhookEvent({ payload, event, delivery, config, state, worktree, clickupClient, githubClient, openCodeClient, sendSessionEvent, verifySessionEventDelivery })).then((result) => {
+    appendClickUpWebhookLocalLog(worktree, { type: "github_webhook_route_finished", async: true, ...summarizeGitHubRouteForLog(result, payload, event) });
+    return result;
+  }).catch((error) => {
+    appendClickUpWebhookLocalLog(worktree, { type: "github_webhook_route_failed", event, eventKey, async: true, delivery: delivery || null, message: error.message });
+    return { ok: false, action: "error", reason: "background_route_failed", message: error.message };
+  });
+  route.catch(() => {
+  });
+  return route;
+}
+async function handleGitHubWebhookRequest({ method = "POST", url = null, headers = {}, rawBody = "", config, state, worktree, clickupClient, githubClient = null, openCodeClient, saveState, now = () => /* @__PURE__ */ new Date(), sendSessionEvent, verifySessionEventDelivery, asyncRouting = false } = {}) {
+  let payload = null;
+  let handled = null;
+  let authenticatedWebhook = false;
+  let receivedAt = null;
+  let latestPersistedState = state;
+  const persistState = (nextState) => {
+    latestPersistedState = nextState;
+    if (saveState) saveState(nextState);
+  };
+  const finish = (result) => {
+    handled = result;
+    receivedAt ??= now();
+    const auditState = authenticatedWebhook ? { ...latestPersistedState, githubLastWebhookAt: receivedAt.toISOString() } : latestPersistedState;
+    if (saveState && authenticatedWebhook) persistState(auditState);
+    writeClickUpWebhookAuditLog({ method, url, headers, rawBody, config, state: auditState, handled, payload, at: receivedAt });
+    return result;
+  };
+  try {
+    if (method !== "POST") return finish({ ok: false, status: 405, reason: "method_not_allowed" });
+    if (url !== null) {
+      const requestPath = new URL(String(url), config?.github?.webhook?.publicUrl || config?.webhook?.publicUrl || "http://localhost").pathname;
+      if (requestPath !== gitHubWebhookExpectedPath(config)) return finish({ ok: false, status: 404, reason: "wrong_path" });
+    }
+    if (!gitHubWebhookEnabled(config)) return finish({ ok: false, status: 404, reason: "github_webhook_disabled" });
+    const maxBodyBytes = Number(config?.webhook?.maxBodyBytes || CLICKUP_WEBHOOK_MAX_BODY_BYTES);
+    const bodyBytes = Buffer.isBuffer(rawBody) ? rawBody.length : Buffer.byteLength(String(rawBody || ""));
+    if (bodyBytes > maxBodyBytes) return finish({ ok: false, status: 413, reason: "body_too_large" });
+    const signature = headers["x-hub-signature-256"] || headers["X-Hub-Signature-256"];
+    const secret = resolveSecretReference(config.github.webhook.secret);
+    if (!verifyGitHubSignature(rawBody, signature, secret)) return finish({ ok: false, status: 401, reason: "invalid_signature" });
+    authenticatedWebhook = true;
+    receivedAt = now();
+    try {
+      payload = JSON.parse(Buffer.isBuffer(rawBody) ? rawBody.toString("utf8") : String(rawBody));
+    } catch {
+      return finish({ ok: false, status: 400, reason: "invalid_json" });
+    }
+    const event = String(headers["x-github-event"] || headers["X-GitHub-Event"] || "").trim();
+    const delivery = String(headers["x-github-delivery"] || headers["X-GitHub-Delivery"] || "").trim();
+    const eventKey = gitHubWebhookEventKey({ headers, event, payload });
+    const remembered = rememberGitHubWebhookEvent({ ...state, githubLastWebhookAt: receivedAt.toISOString() }, eventKey);
+    persistState(remembered.state);
+    if (remembered.duplicate) return finish({ ok: true, status: 200, reason: "duplicate_event", result: { action: "ignored", reason: "duplicate", event, eventKey } });
+    if (asyncRouting) {
+      runGitHubWebhookRouteInBackground({ payload, event, delivery, config, state: remembered.state, worktree, clickupClient, githubClient, openCodeClient, sendSessionEvent, verifySessionEventDelivery });
+      return finish({ ok: true, status: 200, reason: "accepted", result: { action: "accepted", event, eventKey } });
+    }
+    const result = await routeGitHubWebhookEvent({ payload, event, delivery, config, state: remembered.state, worktree, clickupClient, githubClient, openCodeClient, sendSessionEvent, verifySessionEventDelivery });
+    return finish({ ok: result.ok, status: result.ok ? 200 : 422, result });
+  } catch (error) {
+    writeClickUpWebhookAuditLog({ method, url, headers, rawBody, config, state, handled, error, payload, at: now() });
+    throw error;
+  }
+}
 async function handleClickUpWebhookRequest({ method = "POST", url = null, headers = {}, rawBody = "", config, state, worktree, clickupClient, openCodeClient, saveState, now = () => /* @__PURE__ */ new Date(), sessionExists, createSession, sendSessionEvent, ensureTaskWorktree, verifySessionEventDelivery, asyncRouting = false } = {}) {
   let payload = null;
   let handled = null;
@@ -11990,13 +12351,17 @@ function clickUpListenerFingerprint({ config, state, worktree, clickupClient, op
     teamId: config?.teamId || "",
     publicUrl: config?.webhook?.publicUrl || "",
     path: clickUpWebhookExpectedPath(config),
+    githubPublicUrl: config?.github?.webhook?.publicUrl || "",
+    githubPath: gitHubWebhookExpectedPath(config),
+    githubEnabled: gitHubWebhookEnabled(config),
+    githubEvents: config?.github?.webhook?.events || [],
     location: config?.webhook?.location || {},
     webhookId: state?.webhookId || "",
     secret: state?.secret || "",
     events: config?.webhook?.events || []
   });
 }
-function startClickUpWebhookListener({ config, state, worktree, clickupClient, openCodeClient, listenerRegistry = activeClickUpWebhookListeners } = {}) {
+function startClickUpWebhookListener({ config, state, worktree, clickupClient, githubClient = null, openCodeClient, listenerRegistry = activeClickUpWebhookListeners } = {}) {
   if (!isClickUpWebhookStateActive(state, config)) return { active: false, ready: false, reason: "inactive_state" };
   const key = clickUpListenerKey(config);
   const fingerprint = clickUpListenerFingerprint({ config, state, worktree, clickupClient, openCodeClient });
@@ -12015,7 +12380,9 @@ function startClickUpWebhookListener({ config, state, worktree, clickupClient, o
       return;
     }
     const requestPath = new URL(req.url || "/", config.webhook.publicUrl).pathname;
-    if (requestPath !== clickUpWebhookExpectedPath(config)) {
+    const isClickUpPath = requestPath === clickUpWebhookExpectedPath(config);
+    const isGitHubPath = gitHubWebhookEnabled(config) && requestPath === gitHubWebhookExpectedPath(config);
+    if (!isClickUpPath && !isGitHubPath) {
       res.writeHead(404, { "Content-Type": "application/json" });
       res.end(JSON.stringify({ ok: false, reason: "wrong_path" }));
       return;
@@ -12042,7 +12409,7 @@ function startClickUpWebhookListener({ config, state, worktree, clickupClient, o
       if (overflow || res.writableEnded) return;
       const latestState = readClickUpWebhookState(worktree, config);
       try {
-        const handled = await handleClickUpWebhookRequest({
+        const common = {
           method: req.method,
           url: req.url,
           headers: req.headers,
@@ -12054,7 +12421,8 @@ function startClickUpWebhookListener({ config, state, worktree, clickupClient, o
           openCodeClient,
           saveState: (nextState) => writeClickUpWebhookState(worktree, nextState, config),
           asyncRouting: true
-        });
+        };
+        const handled = isGitHubPath ? await handleGitHubWebhookRequest({ ...common, githubClient }) : await handleClickUpWebhookRequest(common);
         res.writeHead(handled.status, { "Content-Type": "application/json" });
         res.end(JSON.stringify({ ok: handled.ok, reason: handled.reason, result: handled.result?.action }));
       } catch (error) {
@@ -13172,6 +13540,7 @@ async function OptimaPlugin(input = {}, pluginOptions = {}) {
   const operatingTeamMode = getOperatingTeamMode(repoCfg);
   const clickUpWebhookValidation = normalizeClickUpWebhookConfig(pickConfiguredClickUp(input, repoCfg, resolvedPluginOptions), worktree);
   const runtimeClickUpClient = input.clickupClient || (clickUpWebhookValidation.config?.test === true ? createTestClickUpApiClient(clickUpWebhookValidation.config) : createClickUpApiClient(clickUpWebhookValidation.config, input.fetch));
+  const runtimeGitHubClient = input.githubClient || (clickUpWebhookValidation.config?.github?.webhook?.enabled === true ? createGitHubApiClient(clickUpWebhookValidation.config.github, input.fetch) : null);
   let clickUpWebhookRuntime = { active: false, valid: false, reason: "not_configured" };
   if (clickUpWebhookValidation.complete) {
     try {
@@ -13196,6 +13565,7 @@ async function OptimaPlugin(input = {}, pluginOptions = {}) {
         state: listenerState,
         worktree,
         clickupClient: lifecycleClickUpClient,
+        githubClient: runtimeGitHubClient,
         openCodeClient: input.client,
         listenerRegistry
       });
@@ -13871,7 +14241,7 @@ Follow-up: use optima_prompt_workflow with session_id '${sessionId}' to check in
     }
   };
 }
-OptimaPlugin.__internals = { BUNDLE_AGENTS_DIR, BUNDLE_ASSETS_DIR, CLICKUP_DEFINITION_DOC_PARENT, activeClickUpWebhookLifecycleRegistry, cleanupManagedClickUpWebhook, deleteClickUpWebhookBestEffort, BUNDLE_POLICIES_DIR, buildClickUpApplyPayloadResult, buildClickUpCreateSubtasksPayload, buildClickUpReviewAutomationPlan, buildClickUpStartTaskPayload, buildClickUpSummaryPayload, buildClickUpTransitionPayload, buildOptimaAgents, clickUpCommentLedgerKey, clickUpCommentMentionsProductManager, clickUpWebhookAuditLogDir, clickUpWebhookAuditLogPath, compactPromptPath, createClickUpApiClient, createTestClickUpApiClient, createOpenCodeSession, createOpenCodeSessionControl, deliveryEvidencePathForClickUpTask, ensureClickUpTaskWorktree, ensureClickUpTaskWorktreeForWebhook, ensureClickUpTaskWorktreeOpenChamber, ensureClickUpWebhookSubscription, handleClickUpWebhookRequest, inspectOpenCodeSessionActivity, isClickUpDerivedWorktreeSibling, isClickUpSubtaskRoute, isClickUpWebhookStateActive, isSameOrNestedPath, normalizeClickUpWebhookConfig, normalizeClickUpWebhookLogLevel, normalizeOpenCodeBaseUrl, openCodeSessionExists, promptOpenCodeSessionControl, probeOpenCodeSessionControl, readClickUpCommentLedger, readClickUpWebhookState, readOpenCodeSessionControl, readOpenCodeSessionMessages, reconcileClickUpStartup, registerOpenChamberClickUpWorktree, scheduleClickUpAssignmentWatchdog, scheduleClickUpStartupReconciliation, syncOpenChamberWorktreeVisibility, waitForOpenCodeReadiness, recordClickUpCommentVersionProcessed, resyncClickUpWebhookForSignatureDrift, resolveIncludeFile, resolveIncludes, resolveOptimaPluginOptions, resolveSecretReference, routeClickUpWebhookEvent, sendOpenCodeSessionEvent, sendOpenCodeSessionEventDirect, summarizeOpenCodeMessages, verifyOpenCodeSessionEventDelivery, stableClickUpCommentVersionMarker, startClickUpWebhookListener, validateClickUpWebhookState, verifyClickUpSignature, writeClickUpWebhookState, decideClickUpStatusAction, deriveClickUpBranchName, deriveClickUpPendingSubtaskBranch, deriveClickUpPrTarget, deriveClickUpRequiredPullRequest, deriveClickUpWorktree, determineClickUpMergeAuthority, ensureOptimaGitignoreRules, explicitSafeInputWorktree, finalApprovalAssignees, formatRepairResult, formatValidationResult, isIgnoredClickUpTaskType, isOptimaPluginPackageWorktree, isSafeWritableDirectory, loadHumansRegistry, mergeClickUpAgentMetadata, mergeClickUpSessionMetadata, migrateLegacyOptimaLayout, normalizeAgentMetadataJson, normalizeClickUpStatus, normalizeClickUpTaskType, normalizePromptResponseParts, normalizeWorkflowTaskPath, optimaRepairDependencies, parseClickUpSubtasksMarkdown, parseHumansRegistry, parseMarkdownArtifact, parseMarkdownSections, planOptimaRepair, preEstimateClickUpWork, readMarkdownArtifact, resolveHumanRoles, resolveSafeWorktree, safeWorktreeOrFailure, stripRawLogSections, validateMainWorkspaceBranchSafety, workflowFinalMessageFromPromptResponse };
+OptimaPlugin.__internals = { BUNDLE_AGENTS_DIR, BUNDLE_ASSETS_DIR, CLICKUP_DEFINITION_DOC_PARENT, activeClickUpWebhookLifecycleRegistry, cleanupManagedClickUpWebhook, deleteClickUpWebhookBestEffort, BUNDLE_POLICIES_DIR, buildClickUpApplyPayloadResult, buildClickUpCreateSubtasksPayload, buildClickUpReviewAutomationPlan, buildClickUpStartTaskPayload, buildClickUpSummaryPayload, buildClickUpTransitionPayload, buildOptimaAgents, clickUpCommentLedgerKey, clickUpCommentMentionsProductManager, clickUpWebhookAuditLogDir, clickUpWebhookAuditLogPath, compactPromptPath, createClickUpApiClient, createGitHubApiClient, createTestClickUpApiClient, createOpenCodeSession, createOpenCodeSessionControl, deliveryEvidencePathForClickUpTask, ensureClickUpTaskWorktree, ensureClickUpTaskWorktreeForWebhook, ensureClickUpTaskWorktreeOpenChamber, ensureClickUpWebhookSubscription, gitHubPullRequestContextFromPayload, gitHubWebhookExpectedPath, handleClickUpWebhookRequest, handleGitHubWebhookRequest, inspectOpenCodeSessionActivity, isClickUpDerivedWorktreeSibling, isClickUpSubtaskRoute, isClickUpWebhookStateActive, isSameOrNestedPath, normalizeClickUpWebhookConfig, normalizeClickUpWebhookLogLevel, normalizeOpenCodeBaseUrl, openCodeSessionExists, promptOpenCodeSessionControl, probeOpenCodeSessionControl, readClickUpCommentLedger, readClickUpWebhookState, readOpenCodeSessionControl, readOpenCodeSessionMessages, reconcileClickUpStartup, registerOpenChamberClickUpWorktree, routeGitHubWebhookEvent, scheduleClickUpAssignmentWatchdog, scheduleClickUpStartupReconciliation, syncOpenChamberWorktreeVisibility, waitForOpenCodeReadiness, recordClickUpCommentVersionProcessed, resyncClickUpWebhookForSignatureDrift, resolveIncludeFile, resolveIncludes, resolveOptimaPluginOptions, resolveSecretReference, routeClickUpWebhookEvent, sendOpenCodeSessionEvent, sendOpenCodeSessionEventDirect, summarizeOpenCodeMessages, verifyOpenCodeSessionEventDelivery, stableClickUpCommentVersionMarker, startClickUpWebhookListener, validateClickUpWebhookState, verifyClickUpSignature, verifyGitHubSignature, writeClickUpWebhookState, decideClickUpStatusAction, deriveClickUpBranchName, deriveClickUpPendingSubtaskBranch, deriveClickUpPrTarget, deriveClickUpRequiredPullRequest, deriveClickUpWorktree, determineClickUpMergeAuthority, ensureOptimaGitignoreRules, explicitSafeInputWorktree, finalApprovalAssignees, formatRepairResult, formatValidationResult, isIgnoredClickUpTaskType, isOptimaPluginPackageWorktree, isSafeWritableDirectory, loadHumansRegistry, mergeClickUpAgentMetadata, mergeClickUpSessionMetadata, migrateLegacyOptimaLayout, normalizeAgentMetadataJson, normalizeClickUpStatus, normalizeClickUpTaskType, normalizePromptResponseParts, normalizeWorkflowTaskPath, optimaRepairDependencies, parseClickUpSubtasksMarkdown, parseHumansRegistry, parseMarkdownArtifact, parseMarkdownSections, planOptimaRepair, preEstimateClickUpWork, readMarkdownArtifact, resolveHumanRoles, resolveSafeWorktree, safeWorktreeOrFailure, stripRawLogSections, validateMainWorkspaceBranchSafety, workflowFinalMessageFromPromptResponse };
 export {
   OptimaPlugin as default
 };

package/dist/sanitize_cli.js

@@ -8634,6 +8634,7 @@ var activeWorkflows = /* @__PURE__ */ new Map();
 var activeClickUpWebhookListeners = /* @__PURE__ */ new Map();
 var activeClickUpWebhookLifecycleRegistry = /* @__PURE__ */ new Map();
 var activeClickUpTaskRoutes = /* @__PURE__ */ new Map();
+var GITHUB_WEBHOOK_EVENTS = ["pull_request", "pull_request_review", "pull_request_review_comment", "issue_comment"];
 function isRootDirectory(candidate) {
   const resolved = path6.resolve(candidate);
   return resolved === path6.parse(resolved).root;
@@ -9887,9 +9888,48 @@ function normalizeNonNegativeInteger(value, defaultValue) {
   const number = Number(value);
   return Number.isInteger(number) && number >= 0 ? number : defaultValue;
 }
+function defaultGitHubWebhookPublicUrl(clickupPublicUrl = "") {
+  const raw = String(clickupPublicUrl || "").trim();
+  if (!raw) return "";
+  try {
+    const url = new URL(raw);
+    url.pathname = "/optima/github/webhook";
+    url.search = "";
+    url.hash = "";
+    return url.toString();
+  } catch {
+    return raw.replace(/\/optima\/clickup\/webhook\b/, "/optima/github/webhook");
+  }
+}
+function normalizeGitHubWebhookConfig(rawGithub = {}, clickupWebhook = {}) {
+  const github = isPlainObject(rawGithub) ? rawGithub : {};
+  const webhook = isPlainObject(github.webhook) ? github.webhook : {};
+  const enabled = github.enabled === true || webhook.enabled === true;
+  const events = Array.isArray(webhook.events) && webhook.events.length > 0 ? [...new Set(webhook.events.map((event) => String(event || "").trim()).filter(Boolean))] : [...GITHUB_WEBHOOK_EVENTS];
+  const publicUrl = String(webhook.public_url || webhook.publicUrl || github.public_url || github.publicUrl || defaultGitHubWebhookPublicUrl(clickupWebhook.publicUrl)).trim();
+  const secret = String(webhook.secret || github.secret || "").trim();
+  const apiToken = String(github.api_token || github.apiToken || "").trim();
+  const repository = String(github.repository || github.repo || "").trim();
+  const [ownerFromRepo, nameFromRepo] = repository.includes("/") ? repository.split("/", 2) : ["", ""];
+  return {
+    enabled,
+    apiToken,
+    repository,
+    owner: String(github.owner || ownerFromRepo || "").trim(),
+    repo: String(github.repo_name || github.repoName || nameFromRepo || "").trim(),
+    webhook: {
+      enabled,
+      publicUrl,
+      secret,
+      path: publicUrl ? new URL(publicUrl, "http://localhost").pathname : "/optima/github/webhook",
+      events
+    }
+  };
+}
 function normalizeClickUpWebhookConfig(rawClickUp = null, worktree = process.cwd()) {
   const raw = isPlainObject(rawClickUp) ? rawClickUp : {};
   const webhook = isPlainObject(raw.webhook) ? raw.webhook : {};
+  const github = normalizeGitHubWebhookConfig(raw.github, { publicUrl: String(webhook.public_url || webhook.publicUrl || "").trim() });
   const routing = isPlainObject(raw.routing) ? raw.routing : {};
   const opencode = isPlainObject(raw.opencode) ? raw.opencode : {};
   const openchamber = isPlainObject(raw.openchamber) ? raw.openchamber : {};
@@ -9942,6 +9982,7 @@ function normalizeClickUpWebhookConfig(rawClickUp = null, worktree = process.cwd
       },
       events
     },
+    github,
     routing: {
       targetAgent: String(routing.target_agent || routing.targetAgent || "workflow_product_manager").trim(),
       productManagerAssigneeId: String(routing.product_manager_assignee_id || routing.productManagerAssigneeId || "").trim(),
@@ -9963,6 +10004,13 @@ function normalizeClickUpWebhookConfig(rawClickUp = null, worktree = process.cwd
   if (!config.webhook.bindHost) errors.push("clickup.webhook.bind_host is required");
   if (!Number.isInteger(config.webhook.bindPort) || config.webhook.bindPort <= 0) errors.push("clickup.webhook.bind_port must be a positive integer");
   if (!config.webhook.location.list_id && !config.webhook.location.folder_id && !config.webhook.location.space_id) errors.push("one clickup.webhook.location id is required");
+  if (config.github.webhook.enabled) {
+    if (!config.github.webhook.publicUrl) errors.push("clickup.github.webhook.public_url is required when GitHub webhook is enabled");
+    if (!config.github.webhook.secret) errors.push("clickup.github.webhook.secret is required when GitHub webhook is enabled");
+    if (!config.github.webhook.path || config.github.webhook.path === clickUpWebhookExpectedPath(config)) errors.push("clickup.github.webhook.path must be distinct from the ClickUp webhook path");
+    const missingGitHubEvents = GITHUB_WEBHOOK_EVENTS.filter((event) => !config.github.webhook.events.includes(event));
+    if (missingGitHubEvents.length > 0) errors.push(`clickup.github.webhook.events missing: ${missingGitHubEvents.join(", ")}`);
+  }
   if (config.opencode.baseUrl) {
     try {
       new URL(config.opencode.baseUrl);
@@ -10000,6 +10048,8 @@ function sanitizeClickUpWebhookState(state = {}, config = null) {
     listener: isPlainObject(state.listener) ? state.listener : {},
     pendingSessions: isPlainObject(state.pendingSessions) ? state.pendingSessions : {},
     lastWebhookAt: state.lastWebhookAt || state.last_webhook_at || null,
+    githubLastWebhookAt: state.githubLastWebhookAt || state.github_last_webhook_at || null,
+    githubRecentEventKeys: Array.isArray(state.githubRecentEventKeys) ? state.githubRecentEventKeys.slice(-200) : [],
     recentEventKeys
   };
 }
@@ -10116,6 +10166,29 @@ function createClickUpApiClient(config, fetchImpl = globalThis.fetch) {
     }
   };
 }
+function createGitHubApiClient(config = {}, fetchImpl = globalThis.fetch) {
+  const token = resolveSecretReference(config?.apiToken);
+  const owner = String(config?.owner || "").trim();
+  const repo = String(config?.repo || "").trim();
+  const request = async (pathname) => {
+    if (typeof fetchImpl !== "function") throw new Error("fetch is unavailable; inject a GitHub client for live PR lookup");
+    if (!owner || !repo) throw new Error("GitHub repository owner/repo is not configured");
+    const response = await fetchImpl(`https://api.github.com/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}${pathname}`, {
+      headers: {
+        Accept: "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+        ...token ? { Authorization: `Bearer ${token}` } : {}
+      }
+    });
+    if (!response.ok) throw new Error(`GitHub API request failed: ${response.status}`);
+    return response.json();
+  };
+  return {
+    async getPullRequest(number) {
+      return request(`/pulls/${encodeURIComponent(number)}`);
+    }
+  };
+}
 function createTestClickUpApiClient(config) {
   const metadata = /* @__PURE__ */ new Map();
   return {
@@ -10346,6 +10419,19 @@ function verifyClickUpSignature(rawBody, signatureHeader, secret) {
   const wanted = Buffer.from(expected, "hex");
   return given.length === wanted.length && crypto.timingSafeEqual(given, wanted);
 }
+function verifyGitHubSignature(rawBody, signatureHeader, secret) {
+  return verifyClickUpSignature(rawBody, signatureHeader, secret);
+}
+function gitHubWebhookEventKey({ headers = {}, event = "", payload = {} } = {}) {
+  const delivery = headers["x-github-delivery"] || headers["X-GitHub-Delivery"] || payload.delivery || payload.delivery_id || "";
+  const id = delivery || payload.pull_request?.id || payload.comment?.id || payload.review?.id || payload.issue?.id || "unknown";
+  return ["github", event || headers["x-github-event"] || headers["X-GitHub-Event"] || "event", id].filter(Boolean).join(":");
+}
+function rememberGitHubWebhookEvent(state = {}, eventKey, limit = 200) {
+  const recent = Array.isArray(state.githubRecentEventKeys) ? state.githubRecentEventKeys : [];
+  if (recent.includes(eventKey)) return { duplicate: true, state };
+  return { duplicate: false, state: { ...state, githubRecentEventKeys: [...recent, eventKey].slice(-limit) } };
+}
 async function resyncClickUpWebhookForSignatureDrift({ rawBody, signature, config, state = {}, worktree = process.cwd(), clickupClient, saveState } = {}) {
   const validation = clickUpWebhookValidationFromConfig(config);
   if (!clickupClient?.listWebhooks && !clickupClient?.createWebhook) {
@@ -10552,6 +10638,105 @@ function clickUpTaskAgentMetadata(task = {}, fieldId = "") {
   const field = fields.find((item) => String(item?.id || "") === fieldId || String(item?.name || "") === "agent_metadata");
   return field?.value || "";
 }
+function gitHubWebhookExpectedPath(config = {}) {
+  return config?.github?.webhook?.path || "/optima/github/webhook";
+}
+function gitHubWebhookEnabled(config = {}) {
+  return Boolean(config?.github?.webhook?.enabled && resolveSecretReference(config?.github?.webhook?.secret));
+}
+function clickUpTaskIdFromGitHubBranch(branch = "") {
+  const tail = String(branch || "").trim().split("/").filter(Boolean).at(-1) || "";
+  if (!tail) return "";
+  const subtask = tail.match(/-subtask-(.+)$/);
+  return branchSafeClickUpId(subtask ? subtask[1] : tail);
+}
+async function gitHubPullRequestContextFromPayload(payload = {}, event = "", githubClient = null) {
+  let pr = payload.pull_request || null;
+  if (!pr && event === "issue_comment" && payload.issue?.pull_request && githubClient?.getPullRequest) {
+    pr = await githubClient.getPullRequest(payload.issue.number);
+  }
+  if (!pr) return null;
+  const headRef = String(pr.head?.ref || pr.head_ref || "").trim();
+  const baseRef = String(pr.base?.ref || pr.base_ref || "").trim();
+  return {
+    number: pr.number || payload.issue?.number || "",
+    id: pr.id || "",
+    url: pr.html_url || pr.url || "",
+    title: pr.title || payload.issue?.title || "",
+    state: pr.state || "",
+    merged: pr.merged === true,
+    headRef,
+    baseRef,
+    taskId: clickUpTaskIdFromGitHubBranch(headRef),
+    repository: pr.head?.repo?.full_name || pr.base?.repo?.full_name || payload.repository?.full_name || ""
+  };
+}
+function gitHubWebhookCommentBody(payload = {}) {
+  return String(payload.comment?.body || payload.review?.body || payload.pull_request?.body || "").trim();
+}
+function formatGitHubWebhookPrompt({ event = "", action = "", pr = {}, payload = {}, taskId = "" } = {}) {
+  const sender = payload.sender?.login || payload.comment?.user?.login || payload.review?.user?.login || "unknown";
+  const reviewState = String(payload.review?.state || "").trim();
+  const commentBody = gitHubWebhookCommentBody(payload);
+  const lines = [
+    "[GitHub Webhook Event]",
+    `Event: ${event}`,
+    `Action: ${action || "unknown"}`,
+    `Task ID: ${taskId || pr.taskId || "unknown"}`,
+    `Pull Request: #${pr.number || "unknown"} ${pr.url || ""}`.trim(),
+    `PR Branch: ${pr.headRef || "unknown"} -> ${pr.baseRef || "unknown"}`,
+    `Sender: ${sender}`,
+    reviewState ? `Review State: ${reviewState}` : null,
+    commentBody ? ["", "Comment/Review Body:", commentBody].join("\n") : null,
+    "",
+    "Required handling:",
+    "- Answer human GitHub comments in GitHub.",
+    "- If the comment/review implies a change, reply first with what you will do, move the ClickUp task/subtask to in progress, implement/fix in the same branch, push, return ClickUp to validation, update the PR, and reply again with what changed.",
+    "- If this is an approved parent PR by the configured final approver/CTO, continue the merge-to-dev, Vercel preproduction verification, smoke regression, cleanup, and ClickUp completion workflow.",
+    "- Keep Optima runtime/process failures out of ClickUp comments; use local logs for process noise."
+  ].filter(Boolean);
+  return lines.join("\n");
+}
+function mergeGitHubWebhookMetadata(existingMetadata, { pr = {}, event = "", action = "", delivery = "" } = {}) {
+  const current = normalizeAgentMetadataJson(existingMetadata);
+  const next = {
+    ...current,
+    task: {
+      ...isPlainObject(current.task) ? current.task : {},
+      github: {
+        ...isPlainObject(current.task?.github) ? current.task.github : {},
+        pull_request: Object.fromEntries(Object.entries({
+          number: pr.number || void 0,
+          url: pr.url || void 0,
+          source_branch: pr.headRef || void 0,
+          target_branch: pr.baseRef || void 0,
+          repository: pr.repository || void 0
+        }).filter(([, value]) => value !== void 0 && value !== "")),
+        last_webhook: {
+          event,
+          action,
+          delivery,
+          at: (/* @__PURE__ */ new Date()).toISOString()
+        }
+      }
+    }
+  };
+  return JSON.stringify(sortJsonValue(next), null, 2);
+}
+function summarizeGitHubRouteForLog(result = {}, payload = {}, event = "") {
+  return {
+    taskId: result.taskId || null,
+    event: event || null,
+    eventKey: result.eventKey || null,
+    ok: result.ok === true,
+    action: result.action || null,
+    reason: result.reason || null,
+    sessionId: result.sessionId || null,
+    pullRequest: result.prNumber || payload?.pull_request?.number || payload?.issue?.number || null,
+    branch: result.branch || null,
+    worktree: result.worktree || null
+  };
+}
 function getNestedMetadataValue(metadata, dottedKey) {
   const parts = String(dottedKey || "").split(".").filter(Boolean);
   let cursor = metadata;
@@ -11457,9 +11642,9 @@ function buildClickUpWebhookAuditSummary({ method, url, config, handled, error,
     ok: Boolean(handled?.ok),
     reason: handled?.reason || result.reason || (error ? "handler_error" : void 0),
     action: result.action,
-    event: payload ? clickUpEventType(payload) : void 0,
+    event: result.event || (payload ? clickUpEventType(payload) : void 0),
     task: result.taskId || clickUpTaskIdFromPayload(payload || {}),
-    comment: clickUpCommentFromPayload(payload || {})?.id || payload?.comment_id || payload?.commentId,
+    comment: clickUpCommentFromPayload(payload || {})?.id || payload?.comment_id || payload?.commentId || payload?.comment?.id || payload?.review?.id,
     session: result.sessionId,
     base_path: config?.basePath || "",
     request_file: requestFile || void 0
@@ -11473,7 +11658,13 @@ function writeClickUpWebhookAuditLog({ method, url, headers = {}, rawBody = "",
     if (level === "error" && !failed) return;
     const logDir = clickUpWebhookAuditLogDir();
     fs5.mkdirSync(logDir, { recursive: true });
-    const secretValues = [resolveSecretReference(config?.apiToken), state?.secret, config?.webhook?.secret].filter(Boolean);
+    const secretValues = [
+      resolveSecretReference(config?.apiToken),
+      resolveSecretReference(config?.github?.apiToken),
+      state?.secret,
+      config?.webhook?.secret,
+      resolveSecretReference(config?.github?.webhook?.secret)
+    ].filter(Boolean);
     let requestFile;
     if (level === "verbose") {
       const absoluteRequestFile = clickUpWebhookRequestFilePath(at, logDir);
@@ -11935,6 +12126,176 @@ function runClickUpWebhookRouteInBackground({ payload, config, state, worktree,
   });
   return route;
 }
+async function routeGitHubWebhookEventUnlocked({ payload, event = "", delivery = "", config, state = {}, worktree = process.cwd(), clickupClient, githubClient = null, openCodeClient, sendSessionEvent = sendOpenCodeSessionEvent, verifySessionEventDelivery = verifyOpenCodeSessionEventDelivery } = {}) {
+  const normalizedEvent = String(event || payload?.event || "").trim();
+  const action = String(payload?.action || "").trim();
+  const eventKey = gitHubWebhookEventKey({ headers: { "x-github-delivery": delivery, "x-github-event": normalizedEvent }, event: normalizedEvent, payload });
+  if (!config?.github?.webhook?.events?.includes(normalizedEvent)) {
+    return { ok: true, action: "ignored", reason: "unsupported_event", event: normalizedEvent, eventKey };
+  }
+  let pr;
+  try {
+    pr = await gitHubPullRequestContextFromPayload(payload, normalizedEvent, githubClient);
+  } catch (error) {
+    appendClickUpWebhookLocalLog(worktree, { type: "github_pr_context_failed", event: normalizedEvent, delivery, message: error.message });
+    return { ok: false, action: "error", reason: "pull_request_context_failed", event: normalizedEvent, eventKey, message: error.message };
+  }
+  if (!pr) {
+    appendClickUpWebhookLocalLog(worktree, { type: "github_pr_context_unavailable", event: normalizedEvent, delivery, action });
+    return { ok: true, action: "ignored", reason: "pull_request_context_unavailable", event: normalizedEvent, eventKey };
+  }
+  const taskId = String(pr.taskId || "").trim();
+  if (!taskId) {
+    appendClickUpWebhookLocalLog(worktree, { type: "github_task_id_unavailable", event: normalizedEvent, delivery, prNumber: pr.number || null, headRef: pr.headRef || null });
+    return { ok: false, action: "error", reason: "task_id_unavailable", event: normalizedEvent, eventKey, prNumber: pr.number || null };
+  }
+  const task = payload.task || (clickupClient?.getTask ? await clickupClient.getTask(taskId) : null);
+  if (!task) {
+    appendClickUpWebhookLocalLog(worktree, { type: "github_clickup_task_unavailable", taskId, event: normalizedEvent, delivery, prNumber: pr.number || null });
+    return { ok: false, action: "error", reason: "task_unavailable", taskId, event: normalizedEvent, eventKey, prNumber: pr.number || null };
+  }
+  if (isClickUpTaskTerminal(task, {}, config.routing?.ignoredStatuses)) {
+    return { ok: true, action: "ignored", reason: "terminal_status", taskId, event: normalizedEvent, eventKey, prNumber: pr.number || null };
+  }
+  const existingMetadata = clickUpTaskAgentMetadata(task, config.routing.metadataFieldId);
+  const metadata = normalizeAgentMetadataJson(existingMetadata);
+  const rawSessionId = getNestedMetadataValue(metadata, config.routing.metadataKey) || getNestedMetadataValue(metadata, "optima.sessions.product_manager");
+  const sessionId = typeof rawSessionId === "string" && rawSessionId.startsWith("ses_") ? rawSessionId : "";
+  const directory = String(
+    getNestedMetadataValue(metadata, "task.worktree") || getNestedMetadataValue(metadata, "task.subtask_worktree") || ""
+  ).trim();
+  const branch = String(
+    getNestedMetadataValue(metadata, "task.branch") || getNestedMetadataValue(metadata, "task.subtask_branch") || pr.headRef || ""
+  ).trim();
+  if (!sessionId) {
+    appendClickUpWebhookLocalLog(worktree, { type: "github_session_missing", taskId, event: normalizedEvent, delivery, prNumber: pr.number || null, branch: branch || null });
+    return { ok: false, action: "error", reason: "session_missing", taskId, event: normalizedEvent, eventKey, prNumber: pr.number || null, branch: branch || null };
+  }
+  if (!directory) {
+    appendClickUpWebhookLocalLog(worktree, { type: "github_worktree_missing", taskId, event: normalizedEvent, delivery, sessionId, prNumber: pr.number || null });
+    return { ok: false, action: "error", reason: "worktree_missing", taskId, event: normalizedEvent, eventKey, sessionId, prNumber: pr.number || null, branch: branch || null };
+  }
+  const prompt = formatGitHubWebhookPrompt({ event: normalizedEvent, action, pr, payload, taskId });
+  const nextMetadata = mergeGitHubWebhookMetadata(existingMetadata, { pr, event: normalizedEvent, action, delivery });
+  if (typeof clickupClient?.updateTaskMetadata === "function") {
+    await clickupClient.updateTaskMetadata({ taskId, fieldId: config.routing.metadataFieldId, value: nextMetadata });
+  }
+  const deliveryResult = await deliverClickUpSessionEventWithVerification({
+    openCodeClient,
+    sendSessionEvent,
+    clickupClient,
+    worktree,
+    taskId,
+    sessionId,
+    agent: config.routing.targetAgent,
+    text: prompt,
+    directory,
+    opencodeBaseUrl: config.opencode?.baseUrl,
+    directPrompt: config.opencode?.promptDelivery === "http",
+    directDelivery: "steer",
+    acceptPromptAdmission: config.opencode?.acceptPromptAdmission === true,
+    eventMarkers: [taskId, String(pr.number || ""), normalizedEvent].filter(Boolean),
+    verifySessionEventDelivery,
+    applyBlockerOnFailure: false
+  });
+  if (!deliveryResult.ok) {
+    appendClickUpWebhookLocalLog(worktree, { type: "github_message_delivery_failed", taskId, event: normalizedEvent, delivery, sessionId, prNumber: pr.number || null, reason: deliveryResult.reason || "message_delivery_failed" });
+    return { ...deliveryResult, eventKey, taskId, event: normalizedEvent, prNumber: pr.number || null, branch: branch || pr.headRef || null, worktree: directory };
+  }
+  return {
+    ok: true,
+    action: "github_event_delivered",
+    taskId,
+    sessionId,
+    event: normalizedEvent,
+    eventKey,
+    prNumber: pr.number || null,
+    branch: branch || pr.headRef || null,
+    worktree: directory,
+    deliveryVerification: deliveryResult.verification,
+    deliveryAdmission: deliveryResult.admissionVerification,
+    deliveryFallback: deliveryResult.fallback
+  };
+}
+async function routeGitHubWebhookEvent(options = {}) {
+  let taskId = "";
+  try {
+    const pr = await gitHubPullRequestContextFromPayload(options.payload || {}, options.event || "", options.githubClient || null);
+    taskId = pr?.taskId || "";
+  } catch {
+    taskId = "";
+  }
+  return withClickUpTaskRouteLock(taskId, () => routeGitHubWebhookEventUnlocked(options));
+}
+function runGitHubWebhookRouteInBackground({ payload, event, delivery, config, state, worktree, clickupClient, githubClient, openCodeClient, sendSessionEvent, verifySessionEventDelivery } = {}) {
+  const eventKey = gitHubWebhookEventKey({ headers: { "x-github-delivery": delivery, "x-github-event": event }, event, payload });
+  appendClickUpWebhookLocalLog(worktree, { type: "github_webhook_route_started", event, eventKey, async: true, delivery: delivery || null });
+  const route = Promise.resolve().then(() => routeGitHubWebhookEvent({ payload, event, delivery, config, state, worktree, clickupClient, githubClient, openCodeClient, sendSessionEvent, verifySessionEventDelivery })).then((result) => {
+    appendClickUpWebhookLocalLog(worktree, { type: "github_webhook_route_finished", async: true, ...summarizeGitHubRouteForLog(result, payload, event) });
+    return result;
+  }).catch((error) => {
+    appendClickUpWebhookLocalLog(worktree, { type: "github_webhook_route_failed", event, eventKey, async: true, delivery: delivery || null, message: error.message });
+    return { ok: false, action: "error", reason: "background_route_failed", message: error.message };
+  });
+  route.catch(() => {
+  });
+  return route;
+}
+async function handleGitHubWebhookRequest({ method = "POST", url = null, headers = {}, rawBody = "", config, state, worktree, clickupClient, githubClient = null, openCodeClient, saveState, now = () => /* @__PURE__ */ new Date(), sendSessionEvent, verifySessionEventDelivery, asyncRouting = false } = {}) {
+  let payload = null;
+  let handled = null;
+  let authenticatedWebhook = false;
+  let receivedAt = null;
+  let latestPersistedState = state;
+  const persistState = (nextState) => {
+    latestPersistedState = nextState;
+    if (saveState) saveState(nextState);
+  };
+  const finish = (result) => {
+    handled = result;
+    receivedAt ??= now();
+    const auditState = authenticatedWebhook ? { ...latestPersistedState, githubLastWebhookAt: receivedAt.toISOString() } : latestPersistedState;
+    if (saveState && authenticatedWebhook) persistState(auditState);
+    writeClickUpWebhookAuditLog({ method, url, headers, rawBody, config, state: auditState, handled, payload, at: receivedAt });
+    return result;
+  };
+  try {
+    if (method !== "POST") return finish({ ok: false, status: 405, reason: "method_not_allowed" });
+    if (url !== null) {
+      const requestPath = new URL(String(url), config?.github?.webhook?.publicUrl || config?.webhook?.publicUrl || "http://localhost").pathname;
+      if (requestPath !== gitHubWebhookExpectedPath(config)) return finish({ ok: false, status: 404, reason: "wrong_path" });
+    }
+    if (!gitHubWebhookEnabled(config)) return finish({ ok: false, status: 404, reason: "github_webhook_disabled" });
+    const maxBodyBytes = Number(config?.webhook?.maxBodyBytes || CLICKUP_WEBHOOK_MAX_BODY_BYTES);
+    const bodyBytes = Buffer.isBuffer(rawBody) ? rawBody.length : Buffer.byteLength(String(rawBody || ""));
+    if (bodyBytes > maxBodyBytes) return finish({ ok: false, status: 413, reason: "body_too_large" });
+    const signature = headers["x-hub-signature-256"] || headers["X-Hub-Signature-256"];
+    const secret = resolveSecretReference(config.github.webhook.secret);
+    if (!verifyGitHubSignature(rawBody, signature, secret)) return finish({ ok: false, status: 401, reason: "invalid_signature" });
+    authenticatedWebhook = true;
+    receivedAt = now();
+    try {
+      payload = JSON.parse(Buffer.isBuffer(rawBody) ? rawBody.toString("utf8") : String(rawBody));
+    } catch {
+      return finish({ ok: false, status: 400, reason: "invalid_json" });
+    }
+    const event = String(headers["x-github-event"] || headers["X-GitHub-Event"] || "").trim();
+    const delivery = String(headers["x-github-delivery"] || headers["X-GitHub-Delivery"] || "").trim();
+    const eventKey = gitHubWebhookEventKey({ headers, event, payload });
+    const remembered = rememberGitHubWebhookEvent({ ...state, githubLastWebhookAt: receivedAt.toISOString() }, eventKey);
+    persistState(remembered.state);
+    if (remembered.duplicate) return finish({ ok: true, status: 200, reason: "duplicate_event", result: { action: "ignored", reason: "duplicate", event, eventKey } });
+    if (asyncRouting) {
+      runGitHubWebhookRouteInBackground({ payload, event, delivery, config, state: remembered.state, worktree, clickupClient, githubClient, openCodeClient, sendSessionEvent, verifySessionEventDelivery });
+      return finish({ ok: true, status: 200, reason: "accepted", result: { action: "accepted", event, eventKey } });
+    }
+    const result = await routeGitHubWebhookEvent({ payload, event, delivery, config, state: remembered.state, worktree, clickupClient, githubClient, openCodeClient, sendSessionEvent, verifySessionEventDelivery });
+    return finish({ ok: result.ok, status: result.ok ? 200 : 422, result });
+  } catch (error) {
+    writeClickUpWebhookAuditLog({ method, url, headers, rawBody, config, state, handled, error, payload, at: now() });
+    throw error;
+  }
+}
 async function handleClickUpWebhookRequest({ method = "POST", url = null, headers = {}, rawBody = "", config, state, worktree, clickupClient, openCodeClient, saveState, now = () => /* @__PURE__ */ new Date(), sessionExists, createSession, sendSessionEvent, ensureTaskWorktree, verifySessionEventDelivery, asyncRouting = false } = {}) {
   let payload = null;
   let handled = null;
@@ -11997,13 +12358,17 @@ function clickUpListenerFingerprint({ config, state, worktree, clickupClient, op
     teamId: config?.teamId || "",
     publicUrl: config?.webhook?.publicUrl || "",
     path: clickUpWebhookExpectedPath(config),
+    githubPublicUrl: config?.github?.webhook?.publicUrl || "",
+    githubPath: gitHubWebhookExpectedPath(config),
+    githubEnabled: gitHubWebhookEnabled(config),
+    githubEvents: config?.github?.webhook?.events || [],
     location: config?.webhook?.location || {},
     webhookId: state?.webhookId || "",
     secret: state?.secret || "",
     events: config?.webhook?.events || []
   });
 }
-function startClickUpWebhookListener({ config, state, worktree, clickupClient, openCodeClient, listenerRegistry = activeClickUpWebhookListeners } = {}) {
+function startClickUpWebhookListener({ config, state, worktree, clickupClient, githubClient = null, openCodeClient, listenerRegistry = activeClickUpWebhookListeners } = {}) {
   if (!isClickUpWebhookStateActive(state, config)) return { active: false, ready: false, reason: "inactive_state" };
   const key = clickUpListenerKey(config);
   const fingerprint = clickUpListenerFingerprint({ config, state, worktree, clickupClient, openCodeClient });
@@ -12022,7 +12387,9 @@ function startClickUpWebhookListener({ config, state, worktree, clickupClient, o
       return;
     }
     const requestPath = new URL(req.url || "/", config.webhook.publicUrl).pathname;
-    if (requestPath !== clickUpWebhookExpectedPath(config)) {
+    const isClickUpPath = requestPath === clickUpWebhookExpectedPath(config);
+    const isGitHubPath = gitHubWebhookEnabled(config) && requestPath === gitHubWebhookExpectedPath(config);
+    if (!isClickUpPath && !isGitHubPath) {
       res.writeHead(404, { "Content-Type": "application/json" });
       res.end(JSON.stringify({ ok: false, reason: "wrong_path" }));
       return;
@@ -12049,7 +12416,7 @@ function startClickUpWebhookListener({ config, state, worktree, clickupClient, o
       if (overflow || res.writableEnded) return;
       const latestState = readClickUpWebhookState(worktree, config);
       try {
-        const handled = await handleClickUpWebhookRequest({
+        const common = {
           method: req.method,
           url: req.url,
           headers: req.headers,
@@ -12061,7 +12428,8 @@ function startClickUpWebhookListener({ config, state, worktree, clickupClient, o
           openCodeClient,
           saveState: (nextState) => writeClickUpWebhookState(worktree, nextState, config),
           asyncRouting: true
-        });
+        };
+        const handled = isGitHubPath ? await handleGitHubWebhookRequest({ ...common, githubClient }) : await handleClickUpWebhookRequest(common);
         res.writeHead(handled.status, { "Content-Type": "application/json" });
         res.end(JSON.stringify({ ok: handled.ok, reason: handled.reason, result: handled.result?.action }));
       } catch (error) {
@@ -13179,6 +13547,7 @@ async function OptimaPlugin(input = {}, pluginOptions = {}) {
   const operatingTeamMode = getOperatingTeamMode(repoCfg);
   const clickUpWebhookValidation = normalizeClickUpWebhookConfig(pickConfiguredClickUp(input, repoCfg, resolvedPluginOptions), worktree);
   const runtimeClickUpClient = input.clickupClient || (clickUpWebhookValidation.config?.test === true ? createTestClickUpApiClient(clickUpWebhookValidation.config) : createClickUpApiClient(clickUpWebhookValidation.config, input.fetch));
+  const runtimeGitHubClient = input.githubClient || (clickUpWebhookValidation.config?.github?.webhook?.enabled === true ? createGitHubApiClient(clickUpWebhookValidation.config.github, input.fetch) : null);
   let clickUpWebhookRuntime = { active: false, valid: false, reason: "not_configured" };
   if (clickUpWebhookValidation.complete) {
     try {
@@ -13203,6 +13572,7 @@ async function OptimaPlugin(input = {}, pluginOptions = {}) {
         state: listenerState,
         worktree,
         clickupClient: lifecycleClickUpClient,
+        githubClient: runtimeGitHubClient,
         openCodeClient: input.client,
         listenerRegistry
       });
@@ -13878,7 +14248,7 @@ Follow-up: use optima_prompt_workflow with session_id '${sessionId}' to check in
     }
   };
 }
-OptimaPlugin.__internals = { BUNDLE_AGENTS_DIR, BUNDLE_ASSETS_DIR, CLICKUP_DEFINITION_DOC_PARENT, activeClickUpWebhookLifecycleRegistry, cleanupManagedClickUpWebhook, deleteClickUpWebhookBestEffort, BUNDLE_POLICIES_DIR, buildClickUpApplyPayloadResult, buildClickUpCreateSubtasksPayload, buildClickUpReviewAutomationPlan, buildClickUpStartTaskPayload, buildClickUpSummaryPayload, buildClickUpTransitionPayload, buildOptimaAgents, clickUpCommentLedgerKey, clickUpCommentMentionsProductManager, clickUpWebhookAuditLogDir, clickUpWebhookAuditLogPath, compactPromptPath, createClickUpApiClient, createTestClickUpApiClient, createOpenCodeSession, createOpenCodeSessionControl, deliveryEvidencePathForClickUpTask, ensureClickUpTaskWorktree, ensureClickUpTaskWorktreeForWebhook, ensureClickUpTaskWorktreeOpenChamber, ensureClickUpWebhookSubscription, handleClickUpWebhookRequest, inspectOpenCodeSessionActivity, isClickUpDerivedWorktreeSibling, isClickUpSubtaskRoute, isClickUpWebhookStateActive, isSameOrNestedPath, normalizeClickUpWebhookConfig, normalizeClickUpWebhookLogLevel, normalizeOpenCodeBaseUrl, openCodeSessionExists, promptOpenCodeSessionControl, probeOpenCodeSessionControl, readClickUpCommentLedger, readClickUpWebhookState, readOpenCodeSessionControl, readOpenCodeSessionMessages, reconcileClickUpStartup, registerOpenChamberClickUpWorktree, scheduleClickUpAssignmentWatchdog, scheduleClickUpStartupReconciliation, syncOpenChamberWorktreeVisibility, waitForOpenCodeReadiness, recordClickUpCommentVersionProcessed, resyncClickUpWebhookForSignatureDrift, resolveIncludeFile, resolveIncludes, resolveOptimaPluginOptions, resolveSecretReference, routeClickUpWebhookEvent, sendOpenCodeSessionEvent, sendOpenCodeSessionEventDirect, summarizeOpenCodeMessages, verifyOpenCodeSessionEventDelivery, stableClickUpCommentVersionMarker, startClickUpWebhookListener, validateClickUpWebhookState, verifyClickUpSignature, writeClickUpWebhookState, decideClickUpStatusAction, deriveClickUpBranchName, deriveClickUpPendingSubtaskBranch, deriveClickUpPrTarget, deriveClickUpRequiredPullRequest, deriveClickUpWorktree, determineClickUpMergeAuthority, ensureOptimaGitignoreRules, explicitSafeInputWorktree, finalApprovalAssignees, formatRepairResult, formatValidationResult, isIgnoredClickUpTaskType, isOptimaPluginPackageWorktree, isSafeWritableDirectory, loadHumansRegistry, mergeClickUpAgentMetadata, mergeClickUpSessionMetadata, migrateLegacyOptimaLayout, normalizeAgentMetadataJson, normalizeClickUpStatus, normalizeClickUpTaskType, normalizePromptResponseParts, normalizeWorkflowTaskPath, optimaRepairDependencies, parseClickUpSubtasksMarkdown, parseHumansRegistry, parseMarkdownArtifact, parseMarkdownSections, planOptimaRepair, preEstimateClickUpWork, readMarkdownArtifact, resolveHumanRoles, resolveSafeWorktree, safeWorktreeOrFailure, stripRawLogSections, validateMainWorkspaceBranchSafety, workflowFinalMessageFromPromptResponse };
+OptimaPlugin.__internals = { BUNDLE_AGENTS_DIR, BUNDLE_ASSETS_DIR, CLICKUP_DEFINITION_DOC_PARENT, activeClickUpWebhookLifecycleRegistry, cleanupManagedClickUpWebhook, deleteClickUpWebhookBestEffort, BUNDLE_POLICIES_DIR, buildClickUpApplyPayloadResult, buildClickUpCreateSubtasksPayload, buildClickUpReviewAutomationPlan, buildClickUpStartTaskPayload, buildClickUpSummaryPayload, buildClickUpTransitionPayload, buildOptimaAgents, clickUpCommentLedgerKey, clickUpCommentMentionsProductManager, clickUpWebhookAuditLogDir, clickUpWebhookAuditLogPath, compactPromptPath, createClickUpApiClient, createGitHubApiClient, createTestClickUpApiClient, createOpenCodeSession, createOpenCodeSessionControl, deliveryEvidencePathForClickUpTask, ensureClickUpTaskWorktree, ensureClickUpTaskWorktreeForWebhook, ensureClickUpTaskWorktreeOpenChamber, ensureClickUpWebhookSubscription, gitHubPullRequestContextFromPayload, gitHubWebhookExpectedPath, handleClickUpWebhookRequest, handleGitHubWebhookRequest, inspectOpenCodeSessionActivity, isClickUpDerivedWorktreeSibling, isClickUpSubtaskRoute, isClickUpWebhookStateActive, isSameOrNestedPath, normalizeClickUpWebhookConfig, normalizeClickUpWebhookLogLevel, normalizeOpenCodeBaseUrl, openCodeSessionExists, promptOpenCodeSessionControl, probeOpenCodeSessionControl, readClickUpCommentLedger, readClickUpWebhookState, readOpenCodeSessionControl, readOpenCodeSessionMessages, reconcileClickUpStartup, registerOpenChamberClickUpWorktree, routeGitHubWebhookEvent, scheduleClickUpAssignmentWatchdog, scheduleClickUpStartupReconciliation, syncOpenChamberWorktreeVisibility, waitForOpenCodeReadiness, recordClickUpCommentVersionProcessed, resyncClickUpWebhookForSignatureDrift, resolveIncludeFile, resolveIncludes, resolveOptimaPluginOptions, resolveSecretReference, routeClickUpWebhookEvent, sendOpenCodeSessionEvent, sendOpenCodeSessionEventDirect, summarizeOpenCodeMessages, verifyOpenCodeSessionEventDelivery, stableClickUpCommentVersionMarker, startClickUpWebhookListener, validateClickUpWebhookState, verifyClickUpSignature, verifyGitHubSignature, writeClickUpWebhookState, decideClickUpStatusAction, deriveClickUpBranchName, deriveClickUpPendingSubtaskBranch, deriveClickUpPrTarget, deriveClickUpRequiredPullRequest, deriveClickUpWorktree, determineClickUpMergeAuthority, ensureOptimaGitignoreRules, explicitSafeInputWorktree, finalApprovalAssignees, formatRepairResult, formatValidationResult, isIgnoredClickUpTaskType, isOptimaPluginPackageWorktree, isSafeWritableDirectory, loadHumansRegistry, mergeClickUpAgentMetadata, mergeClickUpSessionMetadata, migrateLegacyOptimaLayout, normalizeAgentMetadataJson, normalizeClickUpStatus, normalizeClickUpTaskType, normalizePromptResponseParts, normalizeWorkflowTaskPath, optimaRepairDependencies, parseClickUpSubtasksMarkdown, parseHumansRegistry, parseMarkdownArtifact, parseMarkdownSections, planOptimaRepair, preEstimateClickUpWork, readMarkdownArtifact, resolveHumanRoles, resolveSafeWorktree, safeWorktreeOrFailure, stripRawLogSections, validateMainWorkspaceBranchSafety, workflowFinalMessageFromPromptResponse };
 
 // src/sanitize_cli.js
 var { migrateLegacyOptimaLayout: migrateLegacyOptimaLayout2 } = OptimaPlugin.__internals;

package/docs/core/agent_orchestration.md

@@ -25,9 +25,11 @@
 - Status actions are deterministic: `backlog` ignore, `plan` plan plus `Story Points`, test strategy, and `Definition`, `in progress` execute, `validation` split Tech Lead and Validator/QA gates, `merge` parent post-approval automation, and `completed`/`Closed` ignore unless reopened.
 - Human approval assignment is prohibited except for the strict allowlist: parent `plan` with clear questions already posted in ClickUp comments; `in progress` blocked by missing credentials, permissions, external tools, or access; or parent `validation` with a functional preview URL such as `https://<taskid>-preview.defend.tech`. Do not assign `CTO`/`PO` for generic handoff, routine validation, cleanup, subtask planning/validation, or partial-phase stops.
 - Store ClickUp `agent_metadata` JSON with session IDs per agent/type/task/subtask; keep `Definition` as the plan contract and final Documentation as delivered behavior docs.
+- Validation is not complete until the model leaves the current GitHub PR link visible in ClickUp with source branch, target branch, and validation owner; Optima runtime must still limit its own ClickUp writes to metadata.
 - `workflow_product_manager` is registered only when explicit ClickUp webhook mode is configured and the local webhook subscription state is active/valid.
-- Webhook mode is opt-in: Optima validates signed `X-Signature` HMAC SHA-256 requests, routes status/assignee events only for Product Manager-assigned non-terminal tasks, routes comments only when they mention `@Defend Tech Product Manager`, stores new `ses_...` ids in ClickUp `agent_metadata`, and reports stale/missing sessions to ClickUp without creating replacements.
-- The listener is a gated in-process HTTP listener for local runtime use; deployments still need a stable public URL/tunnel and local `.optima/.config/runtime/` state containing the ClickUp webhook id/secret. When a ClickUp client exposes webhook validation, Optima validates remote state; otherwise local-only validation is limited to ignored runtime state with matching URL/events and present id/secret.
+- Webhook mode is opt-in: Optima validates signed `X-Signature` HMAC SHA-256 ClickUp requests, routes status/assignee events only for Product Manager-assigned non-terminal tasks, routes comments only when they mention `@Defend Tech Product Manager`, and stores new `ses_...` ids in ClickUp `agent_metadata`. Runtime/process failures stay in local logs and must not create ClickUp comments or tags.
+- The same gated in-process listener can also accept signed GitHub `X-Hub-Signature-256` PR/review/comment events at `/optima/github/webhook` when `clickup.github.webhook` is enabled. GitHub events resolve the ClickUp task from the PR source branch, update only `agent_metadata.task.github`, and steer the existing `workflow_product_manager` session; they do not create replacement sessions or ClickUp runtime comments.
+- Deployments still need a stable public URL/tunnel and local `.optima/.config/runtime/` state containing the ClickUp webhook id/secret. When a ClickUp client exposes webhook validation, Optima validates remote state; otherwise local-only validation is limited to ignored runtime state with matching URL/events and present id/secret.
 
 ## Shared Worktree And Git
 

package/docs/core/agent_orchestration.prompt.md

@@ -18,9 +18,10 @@
 - Shared-worktree rule: one active `implementation` task at a time; isolated `investigation`/`spec` may run in parallel if non-conflicting.
 - Git rules: principal workspace stays on `dev`, never `main`; parent branches use `<type>/<parent-id>`; subtask branches use non-nested `<type>/<parent-id>-subtask-<subtask-id>` and pending subtasks use `<type>/<parent-id>-pending-<title-slug>`; parent task pulls remote once at start; subtasks start from and PR to the parent local branch, bootstrapping the parent from `dev`/`origin/dev` first when missing; PoC branches stay `poc/<clickup-task-id>`; parents PR to `dev`, releases PR `dev` -> `main`; failed/conflicted subtask or parent merges return the affected item to `in progress` for the coding owner; no direct `main` pushes.
 - Store `agent_metadata` session JSON; `Definition` is the plan contract, final Documentation is delivered behavior docs.
+- Validation requires a model-owned ClickUp status comment with the current GitHub PR link, source branch, target branch, and validation owner; Optima runtime itself writes only metadata/logs.
 - `workflow_product_manager` is registered only when opt-in ClickUp webhook mode is complete and active/valid.
-- Webhook mode validates `X-Signature` HMAC SHA-256, routes only PM-assigned non-terminal status/assignee events, routes comments only on `@Defend Tech Product Manager`, writes new `ses_...` ids to `agent_metadata`, and reports stale/missing sessions to ClickUp without replacement.
-- The listener is gated in-process local runtime; production needs a stable public URL/tunnel and ignored `.optima/.config/runtime/` webhook state. Remote webhook validation is used when the injected ClickUp client supports it; otherwise local-only validation is limited to matching id/secret/URL/events state.
+- Webhook mode validates ClickUp `X-Signature` HMAC SHA-256, routes only PM-assigned non-terminal status/assignee events, routes comments only on `@Defend Tech Product Manager`, writes new `ses_...` ids to `agent_metadata`, and keeps runtime/process failures in local logs, never ClickUp comments/tags.
+- The listener is gated in-process local runtime; production needs a stable public URL/tunnel and ignored `.optima/.config/runtime/` webhook state. It can also accept GitHub `X-Hub-Signature-256` PR/review/comment webhooks at `/optima/github/webhook`; these update only `agent_metadata.task.github` and steer the existing WPM session resolved from the PR source branch.
 - Communication: questions, blockers, reviews, dependencies, and escalation go through PMA. Tech Lead reviews architecture/code/PR/standards/repo skills; Validator/QA verifies tests/regression/coverage/evidence/docs.
 - Reopen same-scope discrepancies by reactivating the same task file, adding `Reopen History`, and reusing existing Task/Workflow Runner session IDs when possible.
 - Blockers move to `.optima/tasks/blocked/` with a clear blocker report and PO-facing resolution need.

package/docs/guides/AGENTS.md

@@ -68,6 +68,7 @@ For ClickUp-first delivery, Validation is a GitHub PR state, not a comment-only
 
 - Subtasks open/update a PR from the subtask branch into the parent task branch before entering Validation.
 - Parent tasks open/update a PR from the task branch into `dev` before entering Validation.
+- The model must leave the current PR link visible in ClickUp when it moves a task/subtask to Validation, including source/target branch and validation owner. Optima runtime still writes only metadata/logs; the ClickUp comment is model-owned work status.
 - GitHub review/comment webhooks wake the workflow owner. The agent replies in GitHub; if a comment requires a change, it moves ClickUp back to `in progress`, fixes/pushes the same branch, returns ClickUp to `validation`, updates the PR, and replies again with the result.
 - The configured final approver/CTO approving the parent PR is the merge trigger. After merge to `dev`, Vercel preproduction must deploy automatically and pass a small smoke/regression check before cleanup and ClickUp `completed`.
 - If merge, Vercel deployment, or regression fails, create Bug subtasks under the parent and return the parent to `in progress`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defend-tech/opencode-optima",
-  "version": "0.1.72",
+  "version": "0.1.74",
   "repository": {
     "type": "git",
     "url": "git+ssh://git@github.com/defend-tech/opencode-optima.git"