@blogic-cz/agent-tools 0.15.1 → 0.15.3

package/README.md

@@ -265,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.
@@ -279,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

package/package.json

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

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,

package/src/gh-tool/service.ts

@@ -14,6 +14,41 @@ const NETWORK_ERROR_RE =
 const AUTH_401_RE = /HTTP 401|Bad credentials/i;
 const MAX_GH_RETRIES = 2;
 
+// A bare `gh` stderr tells an agent what broke but never what to do next. `hint`/`nextCommand`
+// already exist on GitHubCommandError; these fill them for the failures agents actually hit.
+const KNOWN_STDERR_HINTS: ReadonlyArray<{
+  readonly re: RegExp;
+  readonly hint: string;
+  readonly nextCommand?: string;
+}> = [
+  {
+    re: /no checks reported/i,
+    hint: "The head commit carries no check runs yet. Wait for CI to register, or trigger the workflow when the push event was dropped.",
+    nextCommand: "agent-tools-gh pr trigger-checks --pr <number> --workflow <file.yml>",
+  },
+  {
+    re: /no commits between/i,
+    hint: "Head and base point at the same commit. Push a commit before opening or updating the PR.",
+  },
+  {
+    re: /already exists/i,
+    hint: "The resource already exists. Fetch the existing one and update it instead of creating another.",
+  },
+  {
+    re: /pending review/i,
+    hint: "A pending (unsubmitted) review blocks this mutation. Inspect its contents and submit or discard it before retrying.",
+    nextCommand: "agent-tools-gh pr reviews --pr <number>",
+  },
+  {
+    re: /workflow does not have 'workflow_dispatch'/i,
+    hint: "This workflow cannot be dispatched manually. Re-run an existing run instead.",
+    nextCommand: "agent-tools-gh workflow rerun --run <run-id>",
+  },
+];
+
+const resolveStderrHint = (stderr: string) =>
+  KNOWN_STDERR_HINTS.find((entry) => entry.re.test(stderr));
+
 // Only retry verbs that are unambiguously idempotent reads — never replay a mutation on a timeout.
 const READ_VERBS = new Set(["view", "list", "checks", "status", "diff"]);
 const MUTATION_TOKENS =
@@ -204,11 +239,14 @@ export class GitHubService extends Context.Service<
               });
             }
 
+            const known = resolveStderrHint(result.stderr);
             return yield* new GitHubCommandError({
               message: result.stderr,
               command: `gh ${args.join(" ")}`,
               exitCode: result.exitCode,
               stderr: result.stderr,
+              ...(known === undefined ? {} : { hint: known.hint }),
+              ...(known?.nextCommand === undefined ? {} : { nextCommand: known.nextCommand }),
             });
           }
 

package/src/gh-tool/workflow.ts

@@ -1,5 +1,5 @@
 import { Command, Flag, Param } from "effect/unstable/cli";
-import { Console, Effect, Option } from "effect";
+import { Console, Duration, Effect, Option } from "effect";
 
 import { formatOption, logFormatted } from "#shared";
 import { CI_CHECK_WATCH_TIMEOUT_MS } from "#gh/config";
@@ -241,6 +241,65 @@ export const dispatchWorkflow = Effect.fn("workflow.dispatchWorkflow")(function*
   };
 });
 
+export type DispatchedRun = {
+  databaseId: number;
+  headSha: string;
+  status: string;
+  conclusion: string | null;
+  url: string;
+};
+
+const DISPATCH_DISCOVERY_ATTEMPTS = 8;
+const DISPATCH_DISCOVERY_INTERVAL_MS = 2000;
+
+export const listDispatchedRuns = Effect.fn("workflow.listDispatchedRuns")(function* (opts: {
+  workflow: string;
+  ref: string;
+  repo: string | null;
+}) {
+  const gh = yield* GitHubService;
+  const args = [
+    "run",
+    "list",
+    "--json",
+    "databaseId,headSha,status,conclusion,url",
+    "--limit",
+    "20",
+    "--workflow",
+    opts.workflow,
+    "--branch",
+    opts.ref,
+    "--event",
+    "workflow_dispatch",
+  ];
+
+  if (opts.repo !== null) {
+    args.push("--repo", opts.repo);
+  }
+
+  return yield* gh
+    .runGhJson<DispatchedRun[]>(args)
+    .pipe(Effect.catchTag("GitHubCommandError", () => Effect.succeed<DispatchedRun[]>([])));
+});
+
+// `gh workflow run` and the REST dispatch endpoint both return an empty body — there is no
+// dispatch-to-run mapping. Polling the run list for an id absent before the dispatch is the only
+// way to name the run we just created, and an unnamed run cannot be watched or verified.
+export const discoverDispatchedRun = Effect.fn("workflow.discoverDispatchedRun")(function* (opts: {
+  workflow: string;
+  ref: string;
+  repo: string | null;
+  knownRunIds: ReadonlySet<number>;
+}) {
+  for (let attempt = 0; attempt < DISPATCH_DISCOVERY_ATTEMPTS; attempt += 1) {
+    const runs = yield* listDispatchedRuns(opts);
+    const created = runs.find((run) => !opts.knownRunIds.has(run.databaseId));
+    if (created !== undefined) return created;
+    yield* Effect.sleep(Duration.millis(DISPATCH_DISCOVERY_INTERVAL_MS));
+  }
+  return null;
+});
+
 // `gh run watch` has no native timeout (observed hanging 36 min). Block for the caller's --timeout,
 // then fall back to a one-shot snapshot so a timeout never returns nothing.
 const DEFAULT_WATCH_RUN_TIMEOUT_SECONDS = CI_CHECK_WATCH_TIMEOUT_MS / 1000;
@@ -781,13 +840,32 @@ export const workflowRunCommand = Command.make(
   ({ field, format, ref, repo, workflow }) =>
     Effect.gen(function* () {
       const resolvedRepo = yield* resolveRepoArg(repo);
+      const before = yield* listDispatchedRuns({ workflow, ref, repo: resolvedRepo });
       const result = yield* dispatchWorkflow({
         workflow,
         ref,
         fields: field,
         repo: resolvedRepo,
       });
-      yield* logFormatted(result, format);
+      const created = yield* discoverDispatchedRun({
+        workflow,
+        ref,
+        repo: resolvedRepo,
+        knownRunIds: new Set(before.map((run) => run.databaseId)),
+      });
+      yield* logFormatted(
+        {
+          ...result,
+          runId: created?.databaseId ?? null,
+          headSha: created?.headSha ?? null,
+          url: created?.url ?? null,
+          nextCommand:
+            created === null
+              ? `agent-tools-gh workflow list --workflow ${workflow} --branch ${ref}`
+              : `agent-tools-gh workflow watch --run ${created.databaseId}`,
+        },
+        format,
+      );
     }),
 ).pipe(Command.withDescription("Dispatch a workflow_dispatch workflow run"));