@blogic-cz/agent-tools 0.14.62 → 0.15.2

package/README.md

@@ -178,6 +178,10 @@ bun run agent-tools/example-tool/index.ts ping
       // auto defaults to true:
       // darwin -> macos-scutil, linux -> linux-nmcli, win32 -> windows-rasdial
       name: "ExampleVPN",
+      // Reuse package-managed connections for 30 seconds after the last command. Set 0 for immediate cleanup.
+      idleDisconnectMs: 30000,
+      // Total window for stop plus disconnected-status confirmation.
+      disconnectTimeoutMs: 10000,
       // Optional: pass IPSec shared secret to macOS scutil from env without storing the value in config.
       secretEnvVar: "EXAMPLE_VPN_IPSEC_SHARED_SECRET",
     },
@@ -187,8 +191,7 @@ bun run agent-tools/example-tool/index.ts ping
       clusterId: "your-cluster-id",
       namespaces: { test: "your-ns-test", prod: "your-ns-prod" },
       prerequisites: [{ type: "vpn", key: "exampleVpn" }],
-      // Prerequisites are currently decoded and validated as config metadata;
-      // automatic VPN connect/disconnect execution is planned for a follow-up release.
+      // agent-tools starts disconnected VPNs, shares package-local leases, and disconnects only connections it owns.
     },
   },
   logs: {
@@ -262,13 +265,14 @@ Pod `exec` is limited to direct `redis-cli PING/INFO` and `ls` diagnostics. Gene
 
 `pr view` adds `headSha` and `baseSha`; failed-check evidence adds the same SHA pair. Review summaries, inline comments, and threads add `commitSha` plus `feedbackOrigin`: `current_head` only for an exact `commitSha === headSha`, `pre_existing` for a different known SHA (not an obsolescence verdict), and `unknown` when either SHA is absent. Issue comments always use `commitSha: null` and `feedbackOrigin: unknown`. `review-triage` preserves existing fields and adds `inlineComments` plus per-kind `feedbackOriginCounts`; batch triage returns the same object per PR.
 
-`pr watch --prs 12,34 --until terminal --format jsonl` accepts at most 50 unique, digits-only PR numbers and emits only JSONL state transitions. Identity uses `repo/pr/headSha/runId/attempt/jobId`; `checkId` is nullable and reserved for actual check-run IDs. State/bucket revisions emit even when identity stays stable; `supersedes` appears only when identity changes. Open PRs with no checks become terminal only after three stable empty snapshots, allowing bounded GitHub eventual consistency. `pr checks`, batch checks, triage, and batch triage keep stderr silent with `--format json`; JSONL watch is also informationally silent. Failures still return structured nonzero errors on stderr.
+`pr watch --prs 12,34 --until terminal --format jsonl` accepts at most 50 unique, digits-only PR numbers and emits only JSONL state transitions. Identity uses `repo/pr/headSha/runId/attempt/jobId`; `runId`, `attempt`, and `jobId` are omitted from an event rather than emitted as `null`, and `checkId` is no longer emitted. State/bucket revisions emit even when identity stays stable; `supersedes` appears only when identity changes. Open PRs with no checks become terminal only after three stable empty snapshots, allowing bounded GitHub eventual consistency, and carry `checksObserved: false` — a terminal snapshot with no observed check is never green evidence. `pr checks`, batch checks, triage, and batch triage keep stderr silent with `--format json`; JSONL watch is also informationally silent. Failures still return structured nonzero errors on stderr.
 
 Useful flows:
 
 ```bash
 bun gh-tool pr checks-failed --pr 123 --with-logs --format json # includes diagnosis
 bun gh-tool pr rerun-checks --pr 123 --failed-only --watch --timeout 600
+bun gh-tool pr trigger-checks --pr 123 --workflow dotnet-pull-request.yml # only when zero checks reported
 bun gh-tool pr watch --prs 123,124 --format jsonl --timeout 600
 bun gh-tool pr reply-and-resolve --comment-id 456 --body "Done" # infers PR and thread
 # Optional --pr/--thread-id retain legacy flow and are validated before either mutation.
@@ -276,6 +280,12 @@ bun gh-tool pr reply-and-resolve --comment-id 456 --body "Done" # infers PR and
 
 Reruns preflight every target before mutation and fail closed with `evidence_unavailable` when attempt jobs or logs cannot be read. Failed jobs use one `gh run rerun RUN --failed` mutation per workflow run. Without `--watch`, output returns current attempt metadata immediately; with `--watch`, discovery and watching share one absolute `--timeout` deadline and report `discovery_timeout` or `watch_timeout` with latest attempt state. Repeated matching pre-test infrastructure failures return `escalation_required` without mutation. See [`skills/gh-tool/SKILL.md`](skills/gh-tool/SKILL.md) for operating guidance; this section is canonical for added output fields.
 
+Zero reported checks is a state, not an error: `gh pr checks` exits nonzero on an empty result, and every command that reads checks maps that to `[]`. `pr trigger-checks` covers the case where GitHub dropped the `pull_request` event and no run exists at all — it dispatches the named `workflow_dispatch` workflow **on the PR head branch**, then compares the created run's `headSha` back to the PR head and reports `matchesPrHead`. A run dispatched on the wrong ref goes green for another branch and must never be read as PR evidence, so `workflow run` also returns the discovered `runId`/`headSha` instead of a bare `dispatched: true`.
+
+`pr feedback` returns the whole inventory by default. Narrow it with `--only visible-open|needs-human-reply|current-head` (narrowed filters drop issue comments), drop bots with `--exclude-authors github-actions,dependabot`, and read `omitted` for what each filter removed. Base64 report payloads in bodies are replaced with `[base64 payload omitted]`; pass `--raw-bodies` to keep them. `review-triage --omit reviews,inlineComments` trims a repeated snapshot to the verdict and check state, and lists what it left out in `omittedSections`.
+
+Call the wrappers through `bun run --silent <tool>` in repos that expose them as package scripts; without `--silent` every invocation echoes the resolved command line into the agent's context.
+
 `audit-tool` reads the same SQLite file the wrappers write to. By default that file lives at `~/.agent-tools/audit.sqlite`, and you can override both path and retention per repo with the global `audit` config section.
 
 ## Audit Logging
@@ -420,7 +430,7 @@ Secrets are **never** stored in the config file. The `db-tool` config references
 }
 ```
 
-Database VPN prerequisites can be set at the database profile or environment level. If an environment declares `vpn` or `prerequisites`, that environment config replaces the profile prerequisites; `prerequisites: []` explicitly disables inherited VPN setup. DB commands try the query directly first and only connect VPN prerequisites if direct access fails.
+Database VPN prerequisites can be set at the database profile or environment level. If an environment declares `vpn` or `prerequisites`, that environment config replaces the profile prerequisites; `prerequisites: []` explicitly disables inherited VPN setup. DB commands try the query directly first and only connect VPN prerequisites if direct access fails. Package-managed VPNs remain reusable for `idleDisconnectMs` (default 30000) after the last lease; `0` restores immediate cleanup. Preconnected or `leave-running` connections are treated as external and never stopped automatically. If runtime state is corrupt, unknown, or contains legacy artifacts, first stop all agent-tools processes using the VPN, then remove that VPN state directory under `~/.agent-tools/runtime/vpn-prerequisites`.
 
 ```json5
 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blogic-cz/agent-tools",
-  "version": "0.14.62",
+  "version": "0.15.2",
   "description": "CLI tools for AI coding agent workflows — GitHub, database, Kubernetes, Azure DevOps, logs, sessions, and audit",
   "keywords": [
     "agent",

package/schemas/agent-tools.schema.json

@@ -558,16 +558,25 @@
           "enum": ["leave-running", "stop-if-started"]
         },
         "connectTimeoutMs": {
-          "type": "number"
+          "type": "number",
+          "minimum": 0,
+          "maximum": 2147483647,
+          "multipleOf": 1
         },
         "disconnectTimeoutMs": {
-          "type": "number"
-        },
-        "cooldownMs": {
-          "type": "number"
-        },
-        "leaseTtlMs": {
-          "type": "number"
+          "type": "number",
+          "minimum": 0,
+          "maximum": 2147483647,
+          "multipleOf": 1,
+          "description": "Total bounded stop-and-confirm window in milliseconds."
+        },
+        "idleDisconnectMs": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 2147483647,
+          "multipleOf": 1,
+          "default": 30000,
+          "description": "Managed VPN reuse window after the last lease. Set to 0 for immediate cleanup."
         },
         "secretEnvVar": {
           "type": "string",

package/src/config/loader.ts

@@ -18,6 +18,20 @@ const CredentialGuardConfigSchema = Schema.Struct({
 });
 
 const CleanupPolicySchema = Schema.Literals(["leave-running", "stop-if-started"]);
+const VPN_TIMER_FIELDS = ["connectTimeoutMs", "disconnectTimeoutMs", "idleDisconnectMs"] as const;
+const MAX_TIMER_MS = 2_147_483_647;
+
+function validateVpnTimer(key: string, field: (typeof VPN_TIMER_FIELDS)[number], value: unknown) {
+  if (
+    typeof value !== "number" ||
+    !Number.isFinite(value) ||
+    !Number.isInteger(value) ||
+    value < 0 ||
+    value > MAX_TIMER_MS
+  ) {
+    throw new Error(`VPN "${key}" ${field} must be an integer from 0 to ${MAX_TIMER_MS}.`);
+  }
+}
 
 const VpnPrerequisiteSchema = Schema.Struct({
   type: Schema.Literal("vpn"),
@@ -56,8 +70,7 @@ const VpnConfigSchema = Schema.Struct({
   defaultCleanup: Schema.optionalKey(CleanupPolicySchema),
   connectTimeoutMs: Schema.optionalKey(Schema.Number),
   disconnectTimeoutMs: Schema.optionalKey(Schema.Number),
-  cooldownMs: Schema.optionalKey(Schema.Number),
-  leaseTtlMs: Schema.optionalKey(Schema.Number),
+  idleDisconnectMs: Schema.optionalKey(Schema.Number),
   secretEnvVar: Schema.optionalKey(Schema.String),
   drivers: Schema.optionalKey(
     Schema.Struct({
@@ -215,8 +228,29 @@ export function decodeConfig(
   const sanitized = stripUnknownTopLevelKeys(parsed);
 
   try {
-    const decoded = Schema.decodeUnknownSync(AgentToolsConfigSchema)(sanitized);
-    return decoded as AgentToolsConfig;
+    if (isRecord(sanitized) && isRecord(sanitized.vpns)) {
+      for (const [key, value] of Object.entries(sanitized.vpns)) {
+        if (!isRecord(value)) continue;
+        if ("cooldownMs" in value || "leaseTtlMs" in value) {
+          throw new Error(`VPN "${key}" uses removed cooldownMs or leaseTtlMs configuration.`);
+        }
+        for (const field of VPN_TIMER_FIELDS) {
+          if (value[field] !== undefined) validateVpnTimer(key, field, value[field]);
+        }
+      }
+    }
+    const decoded = Schema.decodeUnknownSync(AgentToolsConfigSchema)(sanitized) as AgentToolsConfig;
+    return decoded.vpns
+      ? {
+          ...decoded,
+          vpns: Object.fromEntries(
+            Object.entries(decoded.vpns).map(([key, vpn]) => [
+              key,
+              { idleDisconnectMs: 30_000, ...vpn },
+            ]),
+          ),
+        }
+      : decoded;
   } catch (error) {
     throw new Error(
       `Invalid agent-tools config at ${configPath}: ${

package/src/config/types.ts

@@ -43,9 +43,10 @@ export type VpnConfig = {
   auto?: boolean;
   defaultCleanup?: CleanupPolicy;
   connectTimeoutMs?: number;
+  /** Total bounded stop-and-confirm window in milliseconds. */
   disconnectTimeoutMs?: number;
-  cooldownMs?: number;
-  leaseTtlMs?: number;
+  /** Managed VPN reuse window after the last lease. Defaults to 30000; 0 disconnects immediately. */
+  idleDisconnectMs?: number;
   /** Name of environment variable holding the VPN shared secret for supported drivers. */
   secretEnvVar?: string;
   drivers?: {

package/src/gh-tool/index.ts

@@ -40,6 +40,7 @@ import {
   prChecksCommand,
   prChecksFailedCommand,
   prRerunChecksCommand,
+  prTriggerChecksCommand,
   prReplyAndResolveCommand,
   prReviewTriageBatchCommand,
   prReviewTriageCommand,
@@ -97,6 +98,7 @@ const prCommand = Command.make("pr", {}).pipe(
     prChecksFailedCommand,
     prWatchCommand,
     prRerunChecksCommand,
+    prTriggerChecksCommand,
     prReplyAndResolveCommand,
     prReviewTriageCommand,
     prReviewTriageBatchCommand,
@@ -174,7 +176,7 @@ WORKFLOW FOR AI AGENTS:
   2. Use 'pr discussion-summary' for overview (counts + latest discussion comment)
   3. Use 'pr threads' and 'pr issue-comments-latest --author <username> --body-contains "Review"' for review context
   4. Use 'pr submit-review', 'pr reply', 'pr comment' and 'pr resolve' to handle feedback
-  5. Use 'pr checks' to monitor CI status
+  5. Use 'pr checks' to monitor CI status; 'pr trigger-checks --workflow <file.yml>' when zero checks were reported
   6. Use 'pr merge' to merge (dry-run by default)
   7. Use 'issue list' to list open/closed issues
   8. Use 'issue triage --issue N --verbosity full' to inspect one issue in one call

package/src/gh-tool/pr/commands.ts

@@ -1,4 +1,4 @@
-import { Command, Flag } from "effect/unstable/cli";
+import { Command, Flag, Param } from "effect/unstable/cli";
 import { Console, Effect, Option } from "effect";
 
 import type { CheckResult, PRStatusResult } from "#gh/types";
@@ -39,6 +39,7 @@ import {
   listPRs,
   mergePR,
   rerunChecks,
+  triggerChecks,
   watchPRs,
   viewPR,
   waitForMergeable,
@@ -182,6 +183,101 @@ export const fetchCurrentFeedback = (pr: number | null) =>
     command: "gh-tool pr feedback",
   }).pipe(Effect.map(({ value }) => value));
 
+// Bot bodies carry base64 report payloads that no agent reads but every agent pays for.
+const BASE64_PAYLOAD_RE = /data:[a-z0-9.+-]+\/[a-z0-9.+-]+;base64,[A-Za-z0-9+/=]{40,}/gi;
+
+export const trimNoisyBody = (body: string): string =>
+  body.replace(BASE64_PAYLOAD_RE, "[base64 payload omitted]");
+
+export const FEEDBACK_FILTERS = [
+  "all",
+  "visible-open",
+  "needs-human-reply",
+  "current-head",
+] as const;
+
+export type FeedbackFilter = (typeof FEEDBACK_FILTERS)[number];
+
+type FeedbackInventory = {
+  readonly reviews: ReadonlyArray<{ author: string; body: string; feedbackOrigin: string }>;
+  readonly threads: ReadonlyArray<{
+    commentId: number;
+    body: string;
+    feedbackOrigin: string;
+    isVisibleOpen: boolean;
+    needsHumanReply: boolean;
+  }>;
+  readonly inlineComments: ReadonlyArray<{
+    id: number;
+    inReplyToId: number | null;
+    author: string;
+    body: string;
+    feedbackOrigin: string;
+  }>;
+  readonly issueComments: ReadonlyArray<{ author: string; body: string; feedbackOrigin: string }>;
+};
+
+export const filterFeedback = <T extends FeedbackInventory>(
+  feedback: T,
+  options: {
+    only: FeedbackFilter;
+    excludeAuthors: ReadonlyArray<string>;
+    rawBodies: boolean;
+  },
+) => {
+  const excluded = options.excludeAuthors
+    .map((author) => author.toLowerCase())
+    .filter((a) => a !== "");
+  const keepAuthor = (author: string) =>
+    !excluded.some((needle) => author.toLowerCase().includes(needle));
+
+  const threads = feedback.threads.filter((thread) =>
+    options.only === "visible-open"
+      ? thread.isVisibleOpen
+      : options.only === "needs-human-reply"
+        ? thread.needsHumanReply
+        : options.only === "current-head"
+          ? thread.feedbackOrigin === "current_head"
+          : true,
+  );
+  const keptThreadRoots = new Set(threads.map((thread) => thread.commentId));
+
+  const inlineComments = feedback.inlineComments
+    .filter((comment) =>
+      options.only === "all"
+        ? true
+        : options.only === "current-head"
+          ? comment.feedbackOrigin === "current_head"
+          : keptThreadRoots.has(comment.inReplyToId ?? comment.id),
+    )
+    .filter((comment) => keepAuthor(comment.author));
+
+  const reviews = feedback.reviews
+    .filter((review) => options.only !== "current-head" || review.feedbackOrigin === "current_head")
+    .filter((review) => keepAuthor(review.author));
+
+  const issueComments = (options.only === "all" ? feedback.issueComments : []).filter((comment) =>
+    keepAuthor(comment.author),
+  );
+
+  const body = <I extends { body: string }>(item: I): I =>
+    options.rawBodies ? item : { ...item, body: trimNoisyBody(item.body) };
+
+  return {
+    filter: options.only,
+    omitted: {
+      reviews: feedback.reviews.length - reviews.length,
+      threads: feedback.threads.length - threads.length,
+      inlineComments: feedback.inlineComments.length - inlineComments.length,
+      issueComments: feedback.issueComments.length - issueComments.length,
+    },
+    reviews: reviews.map(body),
+    threads: threads.map(body),
+    inlineComments: inlineComments.map(body),
+    issueComments: issueComments.map(body),
+  };
+};
+
 const countFeedbackOrigins = (items: ReadonlyArray<{ feedbackOrigin: string }>) => ({
   current_head: items.filter((item) => item.feedbackOrigin === "current_head").length,
   pre_existing: items.filter((item) => item.feedbackOrigin === "pre_existing").length,
@@ -720,6 +816,39 @@ export const prRerunChecksCommand = Command.make(
   Command.withDescription("Rerun CI checks for a PR (GitHub Actions only, failed by default)"),
 );
 
+export const prTriggerChecksCommand = Command.make(
+  "trigger-checks",
+  {
+    field: Param.variadic(
+      Param.string(Param.flagKind, "field").pipe(
+        Param.withAlias("f"),
+        Param.withDescription("Workflow input as key=value; may be repeated"),
+      ),
+    ),
+    format: formatOption,
+    pr: Flag.integer("pr").pipe(
+      Flag.withDescription("PR number (default: current branch PR)"),
+      Flag.optional,
+    ),
+    repo: repoOption,
+    workflow: Flag.string("workflow").pipe(
+      Flag.withDescription("workflow_dispatch workflow file to run against the PR head branch"),
+    ),
+  },
+  ({ field, format, pr, repo, workflow }) =>
+    withRepo(
+      repo,
+      Effect.gen(function* () {
+        const result = yield* triggerChecks(Option.getOrNull(pr), workflow, field);
+        yield* logFormatted(result, format);
+      }),
+    ),
+).pipe(
+  Command.withDescription(
+    "Dispatch a workflow against the PR head branch when no checks were reported, and verify the created run matches the PR head",
+  ),
+);
+
 export const prThreadsCommand = Command.make(
   "threads",
   {
@@ -851,24 +980,50 @@ export const prReviewsCommand = Command.make(
 export const prFeedbackCommand = Command.make(
   "feedback",
   {
+    excludeAuthors: Flag.string("exclude-authors").pipe(
+      Flag.withDescription(
+        "Comma-separated author substrings to drop (e.g. github-actions,dependabot)",
+      ),
+      Flag.optional,
+    ),
     format: formatOption,
+    only: Flag.choice("only", FEEDBACK_FILTERS).pipe(
+      Flag.withDefault("all" as FeedbackFilter),
+      Flag.withDescription(
+        "all (default) | visible-open | needs-human-reply | current-head; narrowed filters drop issue comments",
+      ),
+    ),
     pr: Flag.integer("pr").pipe(
       Flag.withDescription("PR number (default: current branch PR)"),
       Flag.optional,
     ),
+    rawBodies: Flag.boolean("raw-bodies").pipe(
+      Flag.withDefault(false),
+      Flag.withDescription("Keep base64 report payloads in bodies instead of omitting them"),
+    ),
     repo: repoOption,
   },
-  ({ format, pr, repo }) =>
+  ({ excludeAuthors, format, only, pr, rawBodies, repo }) =>
     withRepo(
       repo,
       Effect.gen(function* () {
         const feedback = yield* fetchCurrentFeedback(Option.getOrNull(pr));
-        yield* logFormatted(feedback, format);
+        yield* logFormatted(
+          filterFeedback(feedback, {
+            only,
+            excludeAuthors:
+              Option.getOrNull(excludeAuthors)
+                ?.split(",")
+                .map((a) => a.trim()) ?? [],
+            rawBodies,
+          }),
+          format,
+        );
       }),
     ),
 ).pipe(
   Command.withDescription(
-    "Full review-response inventory in one call: submitted reviews + threads (with state) + inline comments + issue comments",
+    "Full review-response inventory in one call: submitted reviews + threads (with state) + inline comments + issue comments. Narrow with --only, drop bots with --exclude-authors; `omitted` reports what each filter removed",
   ),
 );
 
@@ -1110,28 +1265,60 @@ export const prSubmitReviewCommand = Command.make(
   ),
 );
 
+export const OMITTABLE_TRIAGE_SECTIONS = [
+  "reviews",
+  "inlineComments",
+  "unresolvedThreads",
+] as const;
+
+export type OmittableTriageSection = (typeof OMITTABLE_TRIAGE_SECTIONS)[number];
+
+export const omitTriageSections = <T extends Record<string, unknown>>(
+  triage: T,
+  omit: ReadonlyArray<string>,
+) => {
+  const requested = omit.map((section) => section.trim()).filter((section) => section !== "");
+  const applied = requested.filter((section): section is OmittableTriageSection =>
+    (OMITTABLE_TRIAGE_SECTIONS as ReadonlyArray<string>).includes(section),
+  );
+  if (applied.length === 0) return triage;
+  const kept = Object.fromEntries(
+    Object.entries(triage).filter(([key]) => !applied.includes(key as OmittableTriageSection)),
+  ) as Partial<T>;
+  return { ...kept, omittedSections: applied };
+};
+
 export const prReviewTriageCommand = Command.make(
   "review-triage",
   {
     format: formatOption,
+    omit: Flag.string("omit").pipe(
+      Flag.withDescription(
+        `Comma-separated sections to leave out (${OMITTABLE_TRIAGE_SECTIONS.join(", ")}) — use for cheap repeated snapshots; \`pr feedback\` owns the full inventory`,
+      ),
+      Flag.optional,
+    ),
     pr: Flag.integer("pr").pipe(
       Flag.withDescription("PR number (default: current branch PR)"),
       Flag.optional,
     ),
     repo: repoOption,
   },
-  ({ format, pr, repo }) =>
+  ({ format, omit, pr, repo }) =>
     withRepo(
       repo,
       Effect.gen(function* () {
         const prNumber = Option.getOrNull(pr);
         const result = yield* fetchReviewTriage(prNumber, format);
-        yield* logFormatted(result, format);
+        yield* logFormatted(
+          omitTriageSections(result, Option.getOrNull(omit)?.split(",") ?? []),
+          format,
+        );
       }),
     ),
 ).pipe(
   Command.withDescription(
-    "Composite: PR info + unresolved threads + visible-open threads + discussion summary + checks status in one call",
+    "Composite: PR info + merge-readiness verdict + unresolved threads + visible-open threads + discussion summary + checks status in one call",
   ),
 );
 

package/src/gh-tool/pr/core.ts

@@ -22,7 +22,15 @@ import { GitHubService } from "#gh/service";
 
 import type { ButStatusJson, PRViewJsonResult } from "./helpers";
 import { runLocalCommand } from "./helpers";
-import { diagnoseLogEntries, fetchJobLogs, formatLogEntries, parseRawJobLogs } from "#gh/workflow";
+import {
+  diagnoseLogEntries,
+  discoverDispatchedRun,
+  dispatchWorkflow,
+  fetchJobLogs,
+  formatLogEntries,
+  listDispatchedRuns,
+  parseRawJobLogs,
+} from "#gh/workflow";
 
 const CHECK_JSON_FIELDS = "name,state,bucket,link";
 const LONG_LIVED_BRANCHES = new Set(["main", "master", "develop", "staging", "production"]);
@@ -187,6 +195,10 @@ const fetchWorkflowRunFailureContext = Effect.fn("pr.fetchWorkflowRunFailureCont
   return context;
 });
 
+// `gh pr checks` exits 1 on an *empty* result ("no checks reported on the 'x' branch"). Zero checks
+// is an ordinary state, so map it to [] and keep the zero-check paths downstream reachable.
+export const NO_CHECKS_REPORTED_RE = /no checks reported/i;
+
 const fetchCheckResults = Effect.fn("pr.fetchCheckResults")(function* (pr: number | null) {
   const gh = yield* GitHubService;
 
@@ -195,7 +207,15 @@ const fetchCheckResults = Effect.fn("pr.fetchCheckResults")(function* (pr: numbe
     args.push(String(pr));
   }
 
-  return yield* gh.runGhJson<CheckResult[]>([...args, "--json", CHECK_JSON_FIELDS]);
+  return yield* gh
+    .runGhJson<CheckResult[]>([...args, "--json", CHECK_JSON_FIELDS])
+    .pipe(
+      Effect.catchTag("GitHubCommandError", (error) =>
+        NO_CHECKS_REPORTED_RE.test(error.stderr) || NO_CHECKS_REPORTED_RE.test(error.message)
+          ? Effect.succeed<CheckResult[]>([])
+          : Effect.fail(error),
+      ),
+    );
 });
 
 const buildFailedChecksReport = Effect.fn("pr.buildFailedChecksReport")(function* (
@@ -1049,6 +1069,69 @@ export const fetchChecks = Effect.fn("pr.fetchChecks")(function* (
   return results;
 });
 
+// Dispatching on the wrong ref produces a green run for another branch that reads as PR evidence.
+// The ref is therefore taken from the PR head, and the created run's headSha is compared back to it.
+export const triggerChecks = Effect.fn("pr.triggerChecks")(function* (
+  pr: number | null,
+  workflow: string,
+  fields: ReadonlyArray<string>,
+) {
+  const gh = yield* GitHubService;
+  const info = yield* viewPR(pr);
+  const repoInfo = yield* gh.getRepoInfo();
+  const repo = `${repoInfo.owner}/${repoInfo.name}`;
+
+  const existing = yield* fetchCheckResults(info.number);
+  if (existing.length > 0) {
+    return {
+      triggered: false as const,
+      pr: info.number,
+      prHeadSha: info.headSha,
+      message: `${existing.length} check(s) already reported for ${info.headSha ?? "head"}; nothing to trigger.`,
+      nextCommand: `agent-tools-gh pr watch --prs ${info.number} --until terminal --format jsonl`,
+    };
+  }
+
+  const before = yield* listDispatchedRuns({ workflow, ref: info.headRefName, repo });
+  yield* dispatchWorkflow({ workflow, ref: info.headRefName, fields, repo });
+  const created = yield* discoverDispatchedRun({
+    workflow,
+    ref: info.headRefName,
+    repo,
+    knownRunIds: new Set(before.map((run) => run.databaseId)),
+  });
+
+  const matchesPrHead = created !== null && created.headSha === info.headSha;
+  if (created !== null && !matchesPrHead) {
+    yield* Console.warn(
+      `⚠️  Dispatched run ${created.databaseId} is on ${created.headSha}, not PR head ${info.headSha ?? "unknown"}. ` +
+        `Its result is NOT evidence for PR #${info.number}.`,
+    );
+  }
+
+  return {
+    triggered: true as const,
+    pr: info.number,
+    workflow,
+    ref: info.headRefName,
+    runId: created?.databaseId ?? null,
+    runHeadSha: created?.headSha ?? null,
+    prHeadSha: info.headSha,
+    matchesPrHead,
+    url: created?.url ?? null,
+    message:
+      created === null
+        ? "Dispatched, but no matching run appeared yet. List runs to find it before treating anything as evidence."
+        : matchesPrHead
+          ? `Run ${created.databaseId} is running against PR head ${info.headSha ?? "unknown"}.`
+          : `Run ${created.databaseId} is on ${created.headSha}, not PR head ${info.headSha ?? "unknown"}; not evidence for this PR.`,
+    nextCommand:
+      created === null
+        ? `agent-tools-gh workflow list --workflow ${workflow} --branch ${info.headRefName}`
+        : `agent-tools-gh workflow watch --run ${created.databaseId}`,
+  };
+});
+
 export const collectWithStableState = <S, A, E1, R1, E2, R2>(
   initial: S,
   collect: (state: S) => Effect.Effect<A, E1, R1>,
@@ -1284,10 +1367,13 @@ export const watchPRs = Effect.fn("pr.watchPRs")(function* (
                 repo: `${repo.owner}/${repo.name}`,
                 pr: number,
                 headSha: state.head,
-                runId: run?.databaseId ?? null,
-                attempt: run?.attempt ?? null,
-                jobId,
-                checkId: null,
+                ...(run?.databaseId === undefined || run.databaseId === null
+                  ? {}
+                  : { runId: run.databaseId }),
+                ...(run?.attempt === undefined || run.attempt === null
+                  ? {}
+                  : { attempt: run.attempt }),
+                ...(jobId === null ? {} : { jobId }),
                 name: check.name,
                 state: check.state,
                 bucket: check.bucket,

package/src/gh-tool/pr/index.ts

@@ -21,6 +21,7 @@ export {
   prStatusCommand,
   prSubmitReviewCommand,
   prThreadsCommand,
+  prTriggerChecksCommand,
   prWaitMergeableCommand,
   prReviewTriageCommand,
   prReviewTriageBatchCommand,