@cursor/july 0.1.1

package/src/internal/cli-github.ts

@@ -0,0 +1,849 @@
+/**
+ * `agent-serve github …` CLI — forward live GitHub webhooks to a locally
+ * served agent via the `cli/gh-webhook` extension, plus a doctor and an
+ * events lister.
+ *
+ * @see https://docs.github.com/en/webhooks/testing-and-troubleshooting-webhooks/using-the-github-cli-to-forward-webhooks-for-testing
+ */
+
+import { execFile, spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join, resolve as resolvePath } from "node:path";
+import { promisify } from "node:util";
+import {
+  buildGitHubForwardArgs,
+  channelForwardUrl,
+  detectGitHubEnvTokenOverride,
+  findGitHubChannelTargets,
+  GITHUB_WEBHOOK_EXTENSION,
+  GITHUB_WEBHOOK_EXTENSION_PIN,
+  type GitHubChannelTarget,
+  type GitHubForwardTarget,
+  ghWebhookExtensionInstallArgs,
+  ghWebhookExtensionPinSatisfied,
+  githubEnvTokenHint,
+  parseGhWebhookExtensionInstalled,
+  parseGhWebhookExtensionVersion,
+  parseRepoFromRemoteUrl,
+  type ResolveGitHubForwardTargetsInput,
+  resolveGitHubForwardTargets,
+  targetLabel,
+  unionForwardEvents,
+} from "../channels/github/forward.js";
+import {
+  parseGitHubPrRef,
+  type ReplayCheck,
+  type ReplayPull,
+  type ReplayRepo,
+  type SynthesizedEvent,
+  selectReplayEvents,
+  signGitHubWebhookBody,
+  synthesizeGitHubEvent,
+} from "../channels/github/replay.js";
+import { resolveAgentMounts } from "./discovery.js";
+import { startFanoutServer } from "./github-fanout.js";
+
+const execFileAsync = promisify(execFile);
+
+const DEFAULT_HOST = "127.0.0.1";
+const DEFAULT_PORT = 3000;
+
+export interface GithubCliOptions {
+  dir: string;
+  /** Select one agent mount by slug. */
+  slug?: string;
+  /** Select one channel id (when an agent has several GitHub channels). */
+  channel?: string;
+  /** Local server host (default 127.0.0.1). */
+  host?: string;
+  /** Local server port (default 3000). */
+  port?: number;
+  /** Explicit forward URL (skips URL derivation). */
+  url?: string;
+  /** Comma/space-separated event override. */
+  events?: string;
+  /** `owner/repo` to forward from. */
+  repo?: string;
+  /** Organization login (org-level hooks). */
+  org?: string;
+  /** Webhook signing secret (defaults to GITHUB_WEBHOOK_SECRET). */
+  secret?: string;
+  /** Install the `cli/gh-webhook` extension if missing. */
+  install?: boolean;
+  json?: boolean;
+  /** replay: PR URL or `owner/repo#N`. */
+  prUrl?: string;
+  /** replay: override the event action (e.g. opened, synchronize). */
+  action?: string;
+  /** replay: CI conclusion for check_run/check_suite/workflow_run. */
+  conclusion?: string;
+  /** replay: commit-status context. */
+  context?: string;
+  /** replay: comment body for issue_comment / review comment. */
+  comment?: string;
+  /** replay: print synthesized payloads instead of POSTing. */
+  dryRun?: boolean;
+  /** replay: write synthesized payloads as fixtures into this dir. */
+  out?: string;
+}
+
+const GITHUB_HELP = `agent-serve github — forward live GitHub webhooks to a local agent
+
+Usage:
+  agent-serve github forward  [--dir .] [--slug S] [--channel C]
+                              [--repo owner/repo | --org ORG]
+                              [--events a,b,c] [--url URL]
+                              [--host 127.0.0.1] [--port 3000]
+                              [--secret S] [--install]
+  agent-serve github replay   <pr_url|owner/repo#N> [--events a,b,c | *]
+                              [--action A] [--conclusion C] [--comment "…"]
+                              [--context CTX] [--dir .] [--slug S] [--channel C]
+                              [--host H] [--port N] [--url URL] [--secret S]
+                              [--dry-run] [--out DIR] [--json]
+  agent-serve github events   [--dir .] [--host H] [--port N] [--json]
+  agent-serve github doctor   [--install] [--json]
+
+Commands:
+  forward   Run \`gh webhook forward\` for the discovered githubChannel()s.
+            URL + events are derived per channel; the repo is inferred from the
+            git remote when --repo/--org are omitted. When several channels
+            match, one forwarder fans out to all of them (each delivery is
+            re-posted to the channels whose event set matches). Use --slug /
+            --channel to forward to just one.
+  replay    Synthesize webhook payloads from a PR you can *read* (no repo admin,
+            no relay) and POST them to the discovered channel(s). Reads the PR
+            via \`gh api\`, builds GitHub-shaped payloads for --events (default
+            pull_request; \`*\` = the channel's declared events), signs them with
+            --secret / GITHUB_WEBHOOK_SECRET, and fans out like forward.
+            --dry-run prints them; --out writes them as fixtures.
+  events    List discovered GitHub channels and the webhook events each accepts.
+  doctor    Check gh, auth, and the ${GITHUB_WEBHOOK_EXTENSION} extension.
+
+Prerequisites:
+  - gh CLI logged in (\`gh auth login\`).
+  - ${GITHUB_WEBHOOK_EXTENSION} extension (\`agent-serve github doctor --install\`).
+  - The agent already serving (\`agent-serve serve --dir . --dev\`).
+
+Notes:
+  - Set GITHUB_WEBHOOK_SECRET (or pass --secret) so the forwarded deliveries
+    are signed and each channel's signature check passes.
+  - Only one forwarder per repo/org at a time (GitHub limitation) — hence the
+    single-forwarder fan-out rather than one process per channel.
+
+See also: docs/guides/github.md, skills/github/SKILL.md
+`;
+
+export async function cmdGithub(
+  subcommand: string | undefined,
+  options: GithubCliOptions
+): Promise<number> {
+  switch (subcommand) {
+    case undefined:
+    case "help":
+    case "--help":
+    case "-h":
+      process.stdout.write(GITHUB_HELP);
+      return subcommand === undefined ? 1 : 0;
+    case "forward":
+      return cmdGithubForward(options);
+    case "replay":
+      return cmdGithubReplay(options);
+    case "events":
+      return cmdGithubEvents(options);
+    case "doctor":
+      return cmdGithubDoctor(options);
+    default:
+      process.stderr.write(`Unknown github subcommand: ${subcommand}\n`);
+      process.stdout.write(GITHUB_HELP);
+      return 1;
+  }
+}
+
+async function cmdGithubForward(options: GithubCliOptions): Promise<number> {
+  const dir = resolvePath(options.dir);
+  const channels = findGitHubChannelTargets(await resolveAgentMounts(dir));
+
+  const resolveInput: ResolveGitHubForwardTargetsInput = {
+    targets: channels,
+    slug: options.slug,
+    channel: options.channel,
+    host: options.host ?? DEFAULT_HOST,
+    port: options.port ?? DEFAULT_PORT,
+    url: options.url,
+    events: parseEventList(options.events),
+  };
+  const resolved = resolveGitHubForwardTargets(resolveInput);
+  if (!resolved.ok) {
+    process.stderr.write(`${resolved.error}\n`);
+    return 1;
+  }
+  const targets = resolved.targets;
+
+  const extension = await ensureWebhookExtension(options.install === true);
+  if (!extension.ok) {
+    process.stderr.write(`${extension.message}\n`);
+    return 1;
+  }
+
+  let repo = options.repo;
+  const org = options.org;
+  if (repo === undefined && org === undefined) {
+    repo = await inferRepo(dir);
+    if (repo === undefined) {
+      process.stderr.write(
+        "could not infer the repository — pass --repo owner/repo (or --org <org>)\n"
+      );
+      return 1;
+    }
+    process.stderr.write(`[agent-serve] inferred --repo ${repo}\n`);
+  }
+
+  const secret = options.secret ?? process.env.GITHUB_WEBHOOK_SECRET;
+
+  // `gh webhook forward` targets a single URL, and GitHub allows only one
+  // forwarder per repo/org. To feed several channels at once, run one
+  // forwarder into a local proxy that re-delivers each raw (still-signed)
+  // delivery to every matching channel. A single channel needs no proxy.
+  const fanout = targets.length > 1;
+  const proxy = fanout ? await startFanoutServer(targets) : undefined;
+  const forwardUrl = proxy?.url ?? targets[0].url;
+  const events = fanout ? unionForwardEvents(targets) : targets[0].events;
+
+  const args = buildGitHubForwardArgs({
+    url: forwardUrl,
+    events,
+    repo,
+    org,
+    secret,
+  });
+
+  process.stderr.write(
+    `[agent-serve] forwarding ${org !== undefined ? `org ${org}` : `repo ${repo}`} to ${targets.length} channel${targets.length === 1 ? "" : "s"}:\n`
+  );
+  for (const target of targets) {
+    process.stderr.write(
+      `[agent-serve]   → ${targetLabel(target)}  ${target.url}  (${target.events.join(", ")})\n`
+    );
+  }
+  if (fanout) {
+    process.stderr.write(
+      `[agent-serve] fan-out proxy on ${forwardUrl} (union events: ${events.join(", ")})\n`
+    );
+  }
+  if (secret === undefined || secret === "") {
+    process.stderr.write(
+      "[agent-serve] no signing secret — deliveries are unsigned. A `serve --dev` github channel accepts them; set GITHUB_WEBHOOK_SECRET on both sides to verify signatures (required for a non-dev target).\n"
+    );
+  }
+  const envToken = detectGitHubEnvTokenOverride();
+  if (envToken !== undefined) {
+    process.stderr.write(
+      `[agent-serve] warning: ${githubEnvTokenHint(envToken)}\n`
+    );
+  }
+  process.stderr.write(`[agent-serve] running: gh ${redact(args)}\n`);
+
+  try {
+    return await spawnGh(args);
+  } finally {
+    proxy?.close();
+  }
+}
+
+async function cmdGithubReplay(options: GithubCliOptions): Promise<number> {
+  const prUrl = options.prUrl;
+  if (prUrl === undefined || prUrl === "") {
+    process.stderr.write("github replay needs a PR URL or owner/repo#N\n");
+    return 1;
+  }
+  const ref = parseGitHubPrRef(prUrl);
+  if (ref === undefined) {
+    process.stderr.write(`could not parse PR ref: ${prUrl}\n`);
+    return 1;
+  }
+
+  // Which channel(s) to deliver to — reuse forward's discovery + URL builder,
+  // but keep each channel's *declared* events so `--events=*` can expand them.
+  const dir = resolvePath(options.dir);
+  const channels = findGitHubChannelTargets(await resolveAgentMounts(dir));
+  const host = options.host ?? DEFAULT_HOST;
+  const port = options.port ?? DEFAULT_PORT;
+  let candidates = channels;
+  if (options.slug !== undefined) {
+    candidates = candidates.filter((c) => c.slug === options.slug);
+  }
+  if (options.channel !== undefined) {
+    candidates = candidates.filter((c) => c.channelId === options.channel);
+  }
+  if (options.url !== undefined && candidates.length > 1) {
+    process.stderr.write(
+      "--url targets a single channel; narrow with --slug/--channel\n"
+    );
+    return 1;
+  }
+  if (candidates.length === 0 && options.url === undefined) {
+    process.stderr.write(
+      "no GitHub channel found. Author agent/channels/github.ts with githubChannel(), or pass --url.\n"
+    );
+    return 1;
+  }
+  const targets: GitHubForwardTarget[] =
+    options.url === undefined
+      ? candidates.map((c) => ({
+          slug: c.slug,
+          channelId: c.channelId,
+          url: channelForwardUrl({
+            host,
+            port,
+            slug: c.slug,
+            channelId: c.channelId,
+            routePath: c.routePath,
+          }),
+          events: c.events,
+        }))
+      : [
+          {
+            slug: candidates[0]?.slug ?? "",
+            channelId: candidates[0]?.channelId ?? "",
+            url: options.url,
+            events: candidates[0]?.events ?? [],
+          },
+        ];
+
+  const requested = parseEventList(options.events);
+  const { events: eventsToReplay, unsupported } = selectReplayEvents(
+    requested,
+    unionForwardEvents(targets)
+  );
+  if (unsupported.length > 0) {
+    process.stderr.write(
+      `[agent-serve] cannot synthesize (skipped): ${unsupported.join(", ")}\n`
+    );
+  }
+  if (eventsToReplay.length === 0) {
+    process.stderr.write("no synthesizable events selected\n");
+    return 1;
+  }
+
+  // Read the PR — pull access is enough (no admin, no relay).
+  let repo: ReplayRepo;
+  let pull: ReplayPull;
+  try {
+    repo = await ghApiJson<ReplayRepo>(`repos/${ref.owner}/${ref.repo}`);
+    pull = await ghApiJson<ReplayPull>(
+      `repos/${ref.owner}/${ref.repo}/pulls/${ref.number}`
+    );
+  } catch (error) {
+    process.stderr.write(
+      `failed to read ${ref.label} via gh api: ${
+        error instanceof Error ? error.message : String(error)
+      }\n`
+    );
+    return 1;
+  }
+
+  // Best-effort: mirror a real CI check (app slug / conclusion) for CI events.
+  const wantsCi = eventsToReplay.some((event) =>
+    ["check_run", "check_suite", "workflow_run", "status"].includes(event)
+  );
+  const check = wantsCi
+    ? await fetchReplayCheck(ref, pull.head.sha)
+    : undefined;
+
+  const synthesized: SynthesizedEvent[] = [];
+  for (const event of eventsToReplay) {
+    const result = synthesizeGitHubEvent({
+      event,
+      repo,
+      pull,
+      action: options.action,
+      conclusion: options.conclusion,
+      context: options.context,
+      comment: options.comment,
+      check,
+    });
+    if ("error" in result) {
+      process.stderr.write(
+        `[agent-serve] skipping ${event}: ${result.error}\n`
+      );
+      continue;
+    }
+    synthesized.push(result);
+  }
+  if (synthesized.length === 0) {
+    process.stderr.write("nothing to replay after synthesis\n");
+    return 1;
+  }
+
+  const secret = options.secret ?? process.env.GITHUB_WEBHOOK_SECRET;
+  process.stderr.write(
+    `[agent-serve] replaying ${ref.label} (${synthesized
+      .map((s) => s.eventName)
+      .join(
+        ", "
+      )}) → ${targets.length} channel${targets.length === 1 ? "" : "s"}\n`
+  );
+
+  const report: Array<Record<string, unknown>> = [];
+  let anyRejected = false;
+  for (const event of synthesized) {
+    const body = Buffer.from(JSON.stringify(event.payload));
+    const headers: Record<string, string> = {
+      "content-type": "application/json",
+      "x-github-event": event.eventName,
+      "x-github-delivery": randomUUID(),
+    };
+    if (secret !== undefined && secret !== "") {
+      headers["x-hub-signature-256"] =
+        `sha256=${signGitHubWebhookBody({ secret, body })}`;
+    }
+
+    if (options.out !== undefined) {
+      const file = await writeReplayFixture(options.out, event);
+      process.stderr.write(`[agent-serve] wrote ${file}\n`);
+    }
+
+    const label = eventLabel(event);
+    if (options.dryRun === true) {
+      report.push({ ...eventReport(event), payload: event.payload });
+      if (options.json !== true) {
+        process.stdout.write(
+          `--- ${label} ---\n${JSON.stringify(event.payload, null, 2)}\n`
+        );
+      }
+      continue;
+    }
+
+    const deliveries = await deliverReplayEvent(
+      body,
+      headers,
+      event.eventName,
+      targets
+    );
+    if (
+      deliveries.length === 0 ||
+      deliveries.some((delivery) => !delivery.ok)
+    ) {
+      anyRejected = true;
+    }
+    report.push({ ...eventReport(event), deliveries });
+    if (options.json !== true) {
+      const summary =
+        deliveries
+          .map(
+            (delivery) =>
+              `${delivery.label} ${delivery.status || "ERR"}${delivery.ok ? "" : " (rejected)"}`
+          )
+          .join(", ") || "(no matching channel)";
+      process.stderr.write(`[agent-serve]   ${label} → ${summary}\n`);
+    }
+  }
+
+  if (options.json === true) {
+    process.stdout.write(
+      `${JSON.stringify(
+        { pr: ref.label, dryRun: options.dryRun === true, events: report },
+        null,
+        2
+      )}\n`
+    );
+  }
+  return anyRejected ? 1 : 0;
+}
+
+interface ReplayDelivery {
+  label: string;
+  /** HTTP status from the channel (0 when the request threw). */
+  status: number;
+  ok: boolean;
+  error?: string;
+}
+
+/** POST one synthesized event to every channel whose event set matches. */
+async function deliverReplayEvent(
+  body: Buffer,
+  headers: Record<string, string>,
+  eventName: string,
+  targets: readonly GitHubForwardTarget[]
+): Promise<ReplayDelivery[]> {
+  const recipients = targets.filter(
+    (target) => target.events.length === 0 || target.events.includes(eventName)
+  );
+  const payload = new Uint8Array(body);
+  // Bounded by the channel count (a handful) — see fanoutDelivery.
+  return Promise.all(
+    recipients.map(async (target) => {
+      try {
+        const response = await fetch(target.url, {
+          method: "POST",
+          headers,
+          body: payload,
+        });
+        return {
+          label: targetLabel(target),
+          status: response.status,
+          ok: response.ok,
+        };
+      } catch (error) {
+        return {
+          label: targetLabel(target),
+          status: 0,
+          ok: false,
+          error: error instanceof Error ? error.message : String(error),
+        };
+      }
+    })
+  );
+}
+
+function eventLabel(event: SynthesizedEvent): string {
+  return event.action === undefined
+    ? event.eventName
+    : `${event.eventName}.${event.action}`;
+}
+
+function eventReport(event: SynthesizedEvent): Record<string, unknown> {
+  return { event: event.eventName, action: event.action };
+}
+
+/** GET `gh api <path>` and parse JSON (throws on non-zero exit). */
+async function ghApiJson<T>(path: string): Promise<T> {
+  const { stdout } = await execFileAsync("gh", [
+    "api",
+    path,
+    "-H",
+    "Accept: application/vnd.github+json",
+  ]);
+  return JSON.parse(stdout) as T;
+}
+
+async function fetchReplayCheck(
+  ref: { owner: string; repo: string },
+  sha: string
+): Promise<ReplayCheck | undefined> {
+  try {
+    const data = await ghApiJson<{
+      check_runs?: Array<{
+        id: number;
+        name?: string;
+        conclusion?: string | null;
+        app?: { slug?: string; name?: string } | null;
+      }>;
+    }>(`repos/${ref.owner}/${ref.repo}/commits/${sha}/check-runs?per_page=100`);
+    const runs = data.check_runs ?? [];
+    const chosen = runs.find((run) => run.conclusion === "failure") ?? runs[0];
+    if (chosen === undefined) {
+      return undefined;
+    }
+    return {
+      id: chosen.id,
+      name: chosen.name,
+      conclusion: chosen.conclusion,
+      app: chosen.app,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+async function writeReplayFixture(
+  outDir: string,
+  event: SynthesizedEvent
+): Promise<string> {
+  const dir = resolvePath(outDir);
+  await mkdir(dir, { recursive: true });
+  const file = join(dir, `${eventLabel(event)}.json`);
+  await writeFile(file, `${JSON.stringify(event.payload, null, 2)}\n`);
+  return file;
+}
+
+async function cmdGithubEvents(options: GithubCliOptions): Promise<number> {
+  const dir = resolvePath(options.dir);
+  const targets = findGitHubChannelTargets(await resolveAgentMounts(dir));
+  const host = options.host ?? DEFAULT_HOST;
+  const port = options.port ?? DEFAULT_PORT;
+  const urlFor = (t: GitHubChannelTarget): string =>
+    channelForwardUrl({
+      host,
+      port,
+      slug: t.slug,
+      channelId: t.channelId,
+      routePath: t.routePath,
+    });
+
+  if (options.json) {
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          channels: targets.map((t) => ({
+            slug: t.slug,
+            channelId: t.channelId,
+            url: urlFor(t),
+            events: t.events,
+          })),
+        },
+        null,
+        2
+      )}\n`
+    );
+    return 0;
+  }
+
+  if (targets.length === 0) {
+    process.stdout.write(
+      "no GitHub channels found (author agent/channels/github.ts with githubChannel())\n"
+    );
+    return 0;
+  }
+  for (const t of targets) {
+    const label = t.slug === "" ? t.channelId : `${t.slug}/${t.channelId}`;
+    process.stdout.write(
+      `${label}\n  url:    ${urlFor(t)}\n  events: ${t.events.join(", ") || "none"}\n`
+    );
+  }
+  return 0;
+}
+
+interface GithubDoctorCheck {
+  id: string;
+  ok: boolean;
+  message: string;
+  /** Non-fatal: surfaced as a warning, not counted toward `doctor: fail`. */
+  warn?: boolean;
+}
+
+async function cmdGithubDoctor(options: GithubCliOptions): Promise<number> {
+  const checks: GithubDoctorCheck[] = [];
+
+  const version = await tryExec({ command: "gh", args: ["--version"] });
+  if (version === undefined) {
+    checks.push({
+      id: "gh",
+      ok: false,
+      message: "gh CLI not found — install from https://cli.github.com",
+    });
+    return reportDoctor(checks, options.json);
+  }
+  checks.push({
+    id: "gh",
+    ok: true,
+    message: version.split("\n")[0]?.trim() ?? "gh present",
+  });
+
+  const auth = await tryExec({ command: "gh", args: ["auth", "status"] });
+  checks.push({
+    id: "auth",
+    ok: auth !== undefined,
+    message:
+      auth !== undefined
+        ? "gh auth status ok"
+        : "not logged in — run `gh auth login`",
+  });
+
+  let extensionList =
+    (await tryExec({ command: "gh", args: ["extension", "list"] })) ?? "";
+  let installed = parseGhWebhookExtensionInstalled(extensionList);
+  let pinOk = installed && ghWebhookExtensionPinSatisfied(extensionList);
+  if ((!installed || !pinOk) && options.install === true) {
+    const install = await tryExec({
+      command: "gh",
+      args: ghWebhookExtensionInstallArgs({ force: installed && !pinOk }),
+    });
+    if (install !== undefined) {
+      extensionList =
+        (await tryExec({ command: "gh", args: ["extension", "list"] })) ?? "";
+      installed = parseGhWebhookExtensionInstalled(extensionList);
+      pinOk = installed && ghWebhookExtensionPinSatisfied(extensionList);
+    } else {
+      installed = false;
+      pinOk = false;
+    }
+    checks.push({
+      id: "install",
+      ok: installed && pinOk,
+      message:
+        installed && pinOk
+          ? `installed ${GITHUB_WEBHOOK_EXTENSION}@${GITHUB_WEBHOOK_EXTENSION_PIN}`
+          : `failed to install ${GITHUB_WEBHOOK_EXTENSION}@${GITHUB_WEBHOOK_EXTENSION_PIN}`,
+    });
+  }
+  checks.push({
+    id: "extension",
+    ok: installed && pinOk,
+    message:
+      installed && pinOk
+        ? `${GITHUB_WEBHOOK_EXTENSION}@${GITHUB_WEBHOOK_EXTENSION_PIN} installed`
+        : !installed
+          ? `${GITHUB_WEBHOOK_EXTENSION} missing — run \`agent-serve github doctor --install\``
+          : `${GITHUB_WEBHOOK_EXTENSION} is ${parseGhWebhookExtensionVersion(extensionList) ?? "unknown"} (need ${GITHUB_WEBHOOK_EXTENSION_PIN}) — run \`agent-serve github doctor --install\``,
+  });
+
+  const envToken = detectGitHubEnvTokenOverride();
+  checks.push(
+    envToken === undefined
+      ? {
+          id: "env_token",
+          ok: true,
+          message: "no GITHUB_TOKEN/GH_TOKEN override (gh uses its own login)",
+        }
+      : {
+          id: "env_token",
+          ok: false,
+          warn: true,
+          message: githubEnvTokenHint(envToken),
+        }
+  );
+
+  return reportDoctor(checks, options.json);
+}
+
+function reportDoctor(
+  checks: GithubDoctorCheck[],
+  json: boolean | undefined
+): number {
+  // Warnings (e.g. an env-token override) are advisory and do not fail doctor.
+  const ok = checks.every((check) => check.ok || check.warn === true);
+  if (json === true) {
+    process.stdout.write(`${JSON.stringify({ ok, checks }, null, 2)}\n`);
+  } else {
+    for (const check of checks) {
+      const marker = check.ok ? "ok" : check.warn === true ? "!!warn" : "!!";
+      process.stdout.write(`${marker}  ${check.id}: ${check.message}\n`);
+    }
+    process.stdout.write(ok ? "doctor: pass\n" : "doctor: fail\n");
+  }
+  return ok ? 0 : 1;
+}
+
+interface ExtensionCheck {
+  ok: boolean;
+  message: string;
+}
+
+async function ensureWebhookExtension(
+  install: boolean
+): Promise<ExtensionCheck> {
+  if ((await tryExec({ command: "gh", args: ["--version"] })) === undefined) {
+    return {
+      ok: false,
+      message:
+        "gh CLI not found — install from https://cli.github.com, then `gh auth login`",
+    };
+  }
+  const list =
+    (await tryExec({ command: "gh", args: ["extension", "list"] })) ?? "";
+  const installed = parseGhWebhookExtensionInstalled(list);
+  const pinOk = installed && ghWebhookExtensionPinSatisfied(list);
+  if (installed && pinOk) {
+    return { ok: true, message: "" };
+  }
+  if (!install) {
+    return {
+      ok: false,
+      message: !installed
+        ? `${GITHUB_WEBHOOK_EXTENSION} not installed — run \`gh extension install ${GITHUB_WEBHOOK_EXTENSION} --pin ${GITHUB_WEBHOOK_EXTENSION_PIN}\` or re-run with --install`
+        : `${GITHUB_WEBHOOK_EXTENSION} is ${parseGhWebhookExtensionVersion(list) ?? "unknown"} (need ${GITHUB_WEBHOOK_EXTENSION_PIN}) — re-run with --install`,
+    };
+  }
+  process.stderr.write(
+    `[agent-serve] installing ${GITHUB_WEBHOOK_EXTENSION}@${GITHUB_WEBHOOK_EXTENSION_PIN}…\n`
+  );
+  if (
+    (await tryExec({
+      command: "gh",
+      args: ghWebhookExtensionInstallArgs({ force: installed && !pinOk }),
+    })) === undefined
+  ) {
+    return {
+      ok: false,
+      message: `failed to install ${GITHUB_WEBHOOK_EXTENSION}@${GITHUB_WEBHOOK_EXTENSION_PIN}`,
+    };
+  }
+  const listAfter =
+    (await tryExec({ command: "gh", args: ["extension", "list"] })) ?? "";
+  const installedAfter = parseGhWebhookExtensionInstalled(listAfter);
+  const pinOkAfter =
+    installedAfter && ghWebhookExtensionPinSatisfied(listAfter);
+  if (!installedAfter || !pinOkAfter) {
+    return {
+      ok: false,
+      message: !installedAfter
+        ? `${GITHUB_WEBHOOK_EXTENSION} missing after install`
+        : `${GITHUB_WEBHOOK_EXTENSION} is ${parseGhWebhookExtensionVersion(listAfter) ?? "unknown"} after install (need ${GITHUB_WEBHOOK_EXTENSION_PIN})`,
+    };
+  }
+  return { ok: true, message: "" };
+}
+
+async function inferRepo(dir: string): Promise<string | undefined> {
+  const viaGh = await tryExec({
+    command: "gh",
+    args: ["repo", "view", "--json", "nameWithOwner", "-q", ".nameWithOwner"],
+    cwd: dir,
+  });
+  const trimmed = viaGh?.trim();
+  if (trimmed !== undefined && trimmed !== "") {
+    return trimmed;
+  }
+  const remote = await tryExec({
+    command: "git",
+    args: ["-C", dir, "remote", "get-url", "origin"],
+  });
+  return remote === undefined ? undefined : parseRepoFromRemoteUrl(remote);
+}
+
+/** Run a command, returning stdout on success or undefined on any failure. */
+async function tryExec(options: {
+  command: string;
+  args: string[];
+  cwd?: string;
+}): Promise<string | undefined> {
+  try {
+    const { stdout } = await execFileAsync(options.command, options.args, {
+      ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+    });
+    return stdout;
+  } catch {
+    return undefined;
+  }
+}
+
+function spawnGh(args: string[]): Promise<number> {
+  return new Promise((resolve) => {
+    const child = spawn("gh", args, { stdio: "inherit" });
+    const forward = (signal: NodeJS.Signals): void => {
+      if (!child.killed) {
+        child.kill(signal);
+      }
+    };
+    process.on("SIGINT", forward);
+    process.on("SIGTERM", forward);
+    child.on("error", (error) => {
+      process.stderr.write(`failed to run gh: ${error.message}\n`);
+      resolve(1);
+    });
+    child.on("exit", (code, signal) => {
+      resolve(code ?? (signal === null ? 0 : 130));
+    });
+  });
+}
+
+/** Split a comma/whitespace-separated list; undefined when empty/unset. */
+function parseEventList(value: string | undefined): string[] | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  const events = value
+    .split(/[\s,]+/)
+    .map((event) => event.trim())
+    .filter(Boolean);
+  return events.length === 0 ? undefined : events;
+}
+
+/** Render the gh argv for logging with the signing secret masked. */
+function redact(args: string[]): string {
+  return args
+    .map((arg) => (arg.startsWith("--secret=") ? "--secret=***" : arg))
+    .join(" ");
+}