@blogic-cz/agent-tools 0.14.40 → 0.14.42

package/package.json

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

package/src/db-tool/index.ts

@@ -8,7 +8,7 @@ import type { SchemaMode } from "./types";
 import { formatOption, formatOutput, renderCauseToStderr, VERSION } from "#shared";
 import { AuditServiceLayer, withAudit } from "#shared/audit";
 import { ConfigService, ConfigServiceLayer, getDefaultEnvironment } from "#config";
-import { makeDbConfigLayer } from "./config-service";
+import { DbConfigService, makeDbConfigLayer } from "./config-service";
 import { DbConnectionError } from "./errors";
 import { DbService } from "./service";
 
@@ -107,9 +107,35 @@ const schemaCommand = Command.make(
     }),
 ).pipe(Command.withDescription("Introspect database schema (tables, columns, relationships)"));
 
+const envsCommand = Command.make(
+  "envs",
+  {
+    format: formatOption,
+    profile: Flag.optional(Flag.string("profile")).pipe(
+      Flag.withDescription("Database profile name from agent-tools.json5 (if multiple configured)"),
+    ),
+  },
+  ({ format }) =>
+    Effect.gen(function* () {
+      const config = yield* ConfigService;
+      const dbConfig = yield* DbConfigService;
+      const environments = dbConfig ? Object.keys(dbConfig.environments) : [];
+      const result = {
+        success: true as const,
+        environments,
+        default: getDefaultEnvironment(config) ?? null,
+        message: `${environments.length} environment(s) configured`,
+        executionTimeMs: 0,
+      };
+      yield* Console.log(formatOutput(result, format));
+    }),
+).pipe(
+  Command.withDescription("List configured database environments and the default (no network)"),
+);
+
 const mainCommand = Command.make("db-tool", {}).pipe(
   Command.withDescription("Database Query Tool for Coding Agents"),
-  Command.withSubcommands([sqlCommand, schemaCommand]),
+  Command.withSubcommands([sqlCommand, schemaCommand, envsCommand]),
 );
 
 const cli = Command.run(mainCommand, {

package/src/db-tool/service.ts

@@ -681,11 +681,17 @@ export class DbService extends Context.Service<
           );
         };
 
-        const getConfigForEnv = (env: string): DbConfig => {
+        const getConfigForEnv = Effect.fn("DbService.getConfigForEnv")(function* (env: string) {
           const envConfig = dbConfig.environments[env];
           if (!envConfig) {
             const available = Object.keys(dbConfig.environments).join(", ");
-            throw new Error(`Unknown environment "${env}". Available: ${available}`);
+            // Tagged failure (not a bare throw) so the hint + nextCommand reach the agent (M3).
+            return yield* new DbConnectionError({
+              message: `Unknown environment "${env}". Available: ${available}`,
+              environment: env,
+              hint: "List configured environments with: db-tool envs",
+              nextCommand: "db-tool envs",
+            });
           }
 
           const accessMode = resolveDbAccessMode(
@@ -707,13 +713,13 @@ export class DbService extends Context.Service<
             allowMutations: accessMode.allowMutations,
             allowedMutations: accessMode.allowedMutations,
           };
-        };
+        });
 
         const executeQuery = Effect.fn("DbService.executeQuery")(function* (
           env: string,
           sql: string,
         ) {
-          const config = getConfigForEnv(env);
+          const config = yield* getConfigForEnv(env);
           const startTimeMs = yield* Clock.currentTimeMillis;
           const resolvedConfig = yield* resolveDbConfig(config, env);
           const password = yield* resolvePassword(resolvedConfig, env);
@@ -753,7 +759,7 @@ export class DbService extends Context.Service<
           mode: SchemaMode,
           table?: string,
         ) {
-          const config = getConfigForEnv(env);
+          const config = yield* getConfigForEnv(env);
           const startTimeMs = yield* Clock.currentTimeMillis;
           const resolvedConfig = yield* resolveDbConfig(config, env);
           const password = yield* resolvePassword(resolvedConfig, env);

package/src/gh-tool/index.ts

@@ -20,6 +20,7 @@ import {
 import {
   prViewCommand,
   prStatusCommand,
+  prListCommand,
   prCreateCommand,
   prCloseCommand,
   prEditCommand,
@@ -39,6 +40,7 @@ import {
   prReplyAndResolveCommand,
   prReviewTriageBatchCommand,
   prReviewTriageCommand,
+  prWaitMergeableCommand,
 } from "./pr/index";
 import { branchRenameCommand } from "./branch";
 import {
@@ -68,10 +70,12 @@ const prCommand = Command.make("pr", {}).pipe(
   Command.withSubcommands([
     prViewCommand,
     prStatusCommand,
+    prListCommand,
     prCreateCommand,
     prCloseCommand,
     prEditCommand,
     prMergeCommand,
+    prWaitMergeableCommand,
     prThreadsCommand,
     prCommentsCommand,
     prIssueCommentsCommand,

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

@@ -73,7 +73,11 @@ export const issueViewCommand = Command.make(
         yield* logFormatted(info, format);
       }),
     ),
-).pipe(Command.withDescription("View issue details"));
+).pipe(
+  Command.withDescription(
+    "View one issue's details. For multiple issues use `gh issue snapshot-batch --issues 1,2,3` (one call, not N).",
+  ),
+);
 
 export const issueCommentsCommand = Command.make(
   "comments",

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

@@ -1,10 +1,20 @@
 import { Command, Flag } from "effect/unstable/cli";
-import { Effect, Option } from "effect";
+import { Console, Effect, Option } from "effect";
 
 import type { CheckResult, PRStatusResult } from "#gh/types";
 
 import { formatOption, logFormatted } from "#shared";
 import { GitHubService } from "#gh/service";
+import { GitHubCommandError } from "#gh/errors";
+
+const emptyBatchError = (batch: string) =>
+  new GitHubCommandError({
+    message: `--prs received no valid PR numbers: ${JSON.stringify(batch)}`,
+    command: "gh pr --prs",
+    exitCode: 1,
+    stderr: "",
+    hint: "Pass comma-separated positive integers, e.g. --prs 1,2,3.",
+  });
 import {
   resolveDefaultTextInput,
   resolveOptionalTextInput,
@@ -25,9 +35,11 @@ import {
   fetchChecks,
   fetchChecksForCommand,
   fetchFailedChecks,
+  listPRs,
   mergePR,
   rerunChecks,
   viewPR,
+  waitForMergeable,
 } from "./core";
 import {
   fetchComments,
@@ -97,7 +109,25 @@ export const fetchReviewTriage = Effect.fn("pr.fetchReviewTriage")(function* (
     fetchChecks(prNumber, false, false, 0),
   ]);
   const classification = classifyReviewTriage(summary, checks);
-  return { classification, info, unresolvedThreads, visibleOpenThreads, summary, checks };
+
+  // Single merge-readiness verdict so agents stop re-stitching mergeable + checks + threads +
+  // review state across separate calls (F2). `blocking` names exactly what's left to do.
+  const blocking: string[] = [];
+  if (info.mergeable !== "MERGEABLE") blocking.push(`mergeable=${info.mergeable || "UNKNOWN"}`);
+  if (checks.some((check) => check.bucket === "fail")) blocking.push("failing_checks");
+  if (checks.some((check) => check.bucket === "pending")) blocking.push("pending_checks");
+  if (summary.unresolvedReviewThreadsCount > 0) blocking.push("unresolved_threads");
+  if (info.reviewDecision !== "" && info.reviewDecision !== "APPROVED") {
+    blocking.push(`review=${info.reviewDecision}`);
+  }
+  const ready = {
+    ready: blocking.length === 0,
+    mergeable: info.mergeable,
+    reviewDecision: info.reviewDecision || null,
+    blocking,
+  };
+
+  return { ready, classification, info, unresolvedThreads, visibleOpenThreads, summary, checks };
 });
 
 export const prViewCommand = Command.make(
@@ -108,18 +138,34 @@ export const prViewCommand = Command.make(
       Flag.withDescription("PR number (default: current branch PR)"),
       Flag.optional,
     ),
+    prs: Flag.string("prs").pipe(
+      Flag.withDescription("Comma-separated PR numbers to view in one call (overrides --pr)"),
+      Flag.optional,
+    ),
     repo: repoOption,
   },
-  ({ format, pr, repo }) =>
+  ({ format, pr, prs, repo }) =>
     withRepo(
       repo,
       Effect.gen(function* () {
-        const prNumber = Option.getOrNull(pr);
-        const info = yield* viewPR(prNumber);
+        const batch = Option.getOrNull(prs);
+        if (batch !== null) {
+          const numbers = parsePrNumbers(batch);
+          if (numbers.length === 0) return yield* emptyBatchError(batch);
+          const results = yield* Effect.all(
+            numbers.map((n) => viewPR(n).pipe(Effect.map((info) => ({ pr: n, info })))),
+            { concurrency: 5 },
+          );
+          yield* logFormatted({ count: results.length, prs: results }, format);
+          return;
+        }
+        const info = yield* viewPR(Option.getOrNull(pr));
         yield* logFormatted(info, format);
       }),
     ),
-).pipe(Command.withDescription("View PR information"));
+).pipe(
+  Command.withDescription("View PR information (use --prs 1,2,3 to view several in one call)"),
+);
 
 export const prStatusCommand = Command.make(
   "status",
@@ -136,12 +182,87 @@ export const prStatusCommand = Command.make(
   Command.withDescription("Auto-detect PR for current branch or GitButler workspace branches"),
 );
 
+export const prListCommand = Command.make(
+  "list",
+  {
+    format: formatOption,
+    state: Flag.choice("state", ["open", "closed", "merged", "all"]).pipe(
+      Flag.withDescription("Filter by state: open, closed, merged, all"),
+      Flag.withDefault("open"),
+    ),
+    author: Flag.string("author").pipe(
+      Flag.withDescription("Filter by author login (use @me for yourself)"),
+      Flag.optional,
+    ),
+    base: Flag.string("base").pipe(Flag.withDescription("Filter by base branch"), Flag.optional),
+    head: Flag.string("head").pipe(Flag.withDescription("Filter by head branch"), Flag.optional),
+    search: Flag.string("search").pipe(
+      Flag.withDescription("GitHub search query (e.g. 'review:required')"),
+      Flag.optional,
+    ),
+    limit: Flag.integer("limit").pipe(
+      Flag.withDescription("Maximum number of PRs to return"),
+      Flag.withDefault(30),
+    ),
+    repo: repoOption,
+  },
+  ({ format, state, author, base, head, search, limit, repo }) =>
+    withRepo(
+      repo,
+      Effect.gen(function* () {
+        const prs = yield* listPRs({
+          state,
+          limit,
+          author: Option.getOrNull(author),
+          base: Option.getOrNull(base),
+          head: Option.getOrNull(head),
+          search: Option.getOrNull(search),
+        });
+        yield* logFormatted(prs, format);
+      }),
+    ),
+).pipe(
+  Command.withDescription(
+    "List PRs (default: open; filter with --state/--author/--base/--head/--search)",
+  ),
+);
+
+export const prWaitMergeableCommand = Command.make(
+  "wait-mergeable",
+  {
+    format: formatOption,
+    pr: Flag.integer("pr").pipe(
+      Flag.withDescription("PR number (default: current branch PR)"),
+      Flag.optional,
+    ),
+    timeout: Flag.integer("timeout").pipe(
+      Flag.withDescription(
+        "Max seconds to wait for a definitive mergeable verdict (capped at 180)",
+      ),
+      Flag.withDefault(60),
+    ),
+    repo: repoOption,
+  },
+  ({ format, pr, timeout, repo }) =>
+    withRepo(
+      repo,
+      Effect.gen(function* () {
+        const info = yield* waitForMergeable(Option.getOrNull(pr), timeout);
+        yield* logFormatted(info, format);
+      }),
+    ),
+).pipe(
+  Command.withDescription(
+    "Poll until GitHub reports a definitive mergeable verdict (MERGEABLE/CONFLICTING) or timeout",
+  ),
+);
+
 export const prCreateCommand = Command.make(
   "create",
   {
     base: Flag.string("base").pipe(
-      Flag.withDescription("Base branch for the PR"),
-      Flag.withDefault("test"),
+      Flag.withDescription("Base branch for the PR (default: repository default branch)"),
+      Flag.optional,
     ),
     body: Flag.string("body").pipe(Flag.withDescription("PR body/description"), Flag.optional),
     bodyFile: Flag.string("body-file").pipe(
@@ -181,7 +302,7 @@ export const prCreateCommand = Command.make(
         });
 
         const info = yield* createPR({
-          base,
+          base: Option.getOrNull(base),
           body: resolvedBody,
           draft,
           head: Option.getOrNull(head),
@@ -324,6 +445,10 @@ export const prChecksCommand = Command.make(
       Flag.withDescription("PR number (default: current branch PR)"),
       Flag.optional,
     ),
+    prs: Flag.string("prs").pipe(
+      Flag.withDescription("Comma-separated PR numbers for a one-shot batch snapshot (no --watch)"),
+      Flag.optional,
+    ),
     repo: repoOption,
     timeout: Flag.integer("timeout").pipe(
       Flag.withDefault(CI_CHECK_WATCH_TIMEOUT_MS / 1000),
@@ -334,16 +459,39 @@ export const prChecksCommand = Command.make(
       Flag.withDescription("Watch until checks complete or timeout"),
     ),
   },
-  ({ failFast, format, pr, repo, timeout, watch }) =>
+  ({ failFast, format, pr, prs, repo, timeout, watch }) =>
     withRepo(
       repo,
       Effect.gen(function* () {
-        const prNumber = Option.getOrNull(pr);
-        const checks = yield* fetchChecksForCommand(prNumber, watch, failFast, timeout);
+        const batch = Option.getOrNull(prs);
+        if (batch !== null) {
+          if (watch) {
+            yield* Console.warn(
+              "ℹ️  --watch is ignored with --prs; batch mode returns a one-shot snapshot per PR.",
+            );
+          }
+          const numbers = parsePrNumbers(batch);
+          if (numbers.length === 0) return yield* emptyBatchError(batch);
+          const results = yield* Effect.all(
+            numbers.map((n) =>
+              fetchChecks(n, false, failFast, timeout).pipe(
+                Effect.map((checks) => ({ pr: n, checks })),
+              ),
+            ),
+            { concurrency: 5 },
+          );
+          yield* logFormatted({ count: results.length, prs: results }, format);
+          return;
+        }
+        const checks = yield* fetchChecksForCommand(Option.getOrNull(pr), watch, failFast, timeout);
         yield* logFormatted(checks, format);
       }),
     ),
-).pipe(Command.withDescription("Fetch CI check status for a PR (optionally watch with timeout)"));
+).pipe(
+  Command.withDescription(
+    "Fetch CI check status for a PR (--watch to block; --prs 1,2,3 for a batch snapshot)",
+  ),
+);
 
 export const prChecksFailedCommand = Command.make(
   "checks-failed",

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

@@ -1,4 +1,4 @@
-import { Console, Effect, Option, Result } from "effect";
+import { Clock, Console, Duration, Effect, Option, Result } from "effect";
 
 import type {
   BranchPRDetail,
@@ -12,7 +12,7 @@ import type {
   WorkflowRunDetail,
 } from "#gh/types";
 
-import { GitHubCommandError, GitHubMergeError, GitHubTimeoutError } from "#gh/errors";
+import { GitHubCommandError, GitHubMergeError } from "#gh/errors";
 import { GitHubService } from "#gh/service";
 
 import type { ButStatusJson, PRViewJsonResult } from "./helpers";
@@ -20,6 +20,9 @@ import { runLocalCommand } from "./helpers";
 
 const CHECK_JSON_FIELDS = "name,state,bucket,link";
 const GITHUB_ACTIONS_RUN_ID_RE = /github\.com\/[^/]+\/[^/]+\/actions\/runs\/(\d+)/;
+// A single blocking `--watch` is capped here so an agent never loses a whole turn to a 30-min
+// foreground wait. On hitting the cap we return the partial snapshot, not a failure (H1).
+const MAX_WATCH_SECONDS = 120;
 
 const validatePRTitle = Effect.fn("pr.validatePRTitle")(function* (title: string) {
   const gh = yield* GitHubService;
@@ -254,7 +257,7 @@ const buildFailedChecksReport = Effect.fn("pr.buildFailedChecksReport")(function
   const hint =
     failedChecks.length === 0
       ? pendingChecks.length > 0
-        ? "Wait for the remaining checks to finish, or use --watch to block until CI settles."
+        ? "Some checks are still running. Re-run this command to refresh the snapshot."
         : "All current checks are green."
       : pendingChecks.length > 0
         ? "Inspect the failed workflow run first. Other checks are still running and may change overall merge readiness."
@@ -453,8 +456,69 @@ export const detectPRStatus = Effect.fn("pr.detectPRStatus")(function* () {
   };
 });
 
+export const listPRs = Effect.fn("pr.listPRs")(function* (opts: {
+  state: string;
+  limit: number;
+  author: string | null;
+  base: string | null;
+  head: string | null;
+  search: string | null;
+}) {
+  const gh = yield* GitHubService;
+  const args = [
+    "pr",
+    "list",
+    "--state",
+    opts.state,
+    "--limit",
+    String(opts.limit),
+    "--json",
+    "number,url,title,headRefName,baseRefName,state,isDraft,author,createdAt,reviewDecision",
+  ];
+  if (opts.author !== null) args.push("--author", opts.author);
+  if (opts.base !== null) args.push("--base", opts.base);
+  if (opts.head !== null) args.push("--head", opts.head);
+  if (opts.search !== null) args.push("--search", opts.search);
+  return yield* gh.runGhJson<PRInfo[]>(args);
+});
+
+// GitHub recomputes mergeability asynchronously after CI; poll until it settles out of "UNKNOWN".
+const MAX_MERGEABLE_WAIT_SECONDS = 180;
+const MERGEABLE_POLL_INTERVAL_MS = 3000;
+
+export const waitForMergeable = Effect.fn("pr.waitForMergeable")(function* (
+  pr: number | null,
+  timeoutSeconds: number,
+) {
+  const cappedSeconds = Math.min(timeoutSeconds, MAX_MERGEABLE_WAIT_SECONDS);
+  const start = yield* Clock.currentTimeMillis;
+  const deadlineMs = Number(start) + cappedSeconds * 1000;
+
+  // Effect.whileLoop (not recursion) so TestClock.adjust can advance Effect.sleep without real waits.
+  let latest = yield* viewPR(pr);
+  let timedOut = false;
+  yield* Effect.whileLoop({
+    while: () => latest.mergeable === "UNKNOWN" && !timedOut,
+    body: () =>
+      Effect.gen(function* () {
+        const now = yield* Clock.currentTimeMillis;
+        if (Number(now) >= deadlineMs) {
+          timedOut = true;
+          return;
+        }
+        // Cap the sleep to the remaining budget so the total wait doesn't overshoot the deadline.
+        const remaining = deadlineMs - Number(now);
+        yield* Effect.sleep(Duration.millis(Math.min(MERGEABLE_POLL_INTERVAL_MS, remaining)));
+        latest = yield* viewPR(pr);
+      }),
+    step: () => undefined,
+  });
+
+  return latest;
+});
+
 export const createPR = Effect.fn("pr.createPR")(function* (opts: {
-  base: string;
+  base: string | null;
   title: string;
   body: string;
   draft: boolean;
@@ -463,6 +527,10 @@ export const createPR = Effect.fn("pr.createPR")(function* (opts: {
   const gh = yield* GitHubService;
   yield* validatePRTitle(opts.title);
 
+  // Default to the repo's real default branch instead of a hardcoded "test" — an omitted --base
+  // must never silently open a PR against the wrong trunk (L1).
+  const baseBranch = opts.base ?? (yield* gh.getRepoInfo()).defaultBranch;
+
   // When --head is provided (e.g. GitButler workspace), use `gh pr list --head`
   // to find existing PR since `gh pr view` relies on the current git branch.
   const existing = yield* opts.head !== null
@@ -500,7 +568,7 @@ export const createPR = Effect.fn("pr.createPR")(function* (opts: {
     "pr",
     "create",
     "--base",
-    opts.base,
+    baseBranch,
     "--title",
     opts.title,
     "--body",
@@ -806,31 +874,31 @@ export const fetchChecks = Effect.fn("pr.fetchChecks")(function* (
       watchArgs.push("--fail-fast");
     }
 
-    const timeoutMs = timeoutSeconds * 1000;
-    yield* gh.runGh(watchArgs).pipe(
+    // Cap the blocking wait; on timeout fall through to a snapshot instead of failing with no state.
+    const cappedSeconds = Math.min(timeoutSeconds, MAX_WATCH_SECONDS);
+    const watchOutcome = yield* gh.runGh(watchArgs).pipe(
       Effect.timeoutOrElse({
-        duration: timeoutMs,
-        orElse: () =>
-          Effect.fail(
-            new GitHubTimeoutError({
-              message: `CI check monitoring timed out after ${timeoutSeconds}s`,
-              timeoutMs,
-              hint: "CI checks are still running. Retry with a longer --timeout or check status manually.",
-              nextCommand: `agent-tools-gh pr checks${pr !== null ? ` --pr ${pr}` : ""}`,
-              retryable: true,
-            }),
-          ),
+        duration: cappedSeconds * 1000,
+        orElse: () => Effect.succeed(null),
       }),
     );
 
-    return yield* fetchCheckResults(pr);
+    const results = yield* fetchCheckResults(pr);
+    if (watchOutcome === null && results.some((c) => c.bucket === "pending")) {
+      const pending = results.filter((c) => c.bucket === "pending").length;
+      yield* Console.warn(
+        `ℹ️  Watch capped at ${cappedSeconds}s; ${pending} check(s) still pending (snapshot returned). ` +
+          `Re-run to keep watching:\n   ${buildChecksCommand(pr, true)}`,
+      );
+    }
+    return results;
   }
 
   const results = yield* fetchCheckResults(pr);
   if (results.some((c) => c.bucket === "pending")) {
     yield* Console.warn(
-      `ℹ️  Some checks are still running. Prefer --watch to block until completion instead of polling:\n` +
-        `   ${buildChecksCommand(pr, true)}`,
+      `ℹ️  Some checks are still running. Re-run to refresh — each call returns the latest snapshot:\n` +
+        `   ${buildChecksCommand(pr, false)}`,
     );
   }
   return results;

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

@@ -9,6 +9,7 @@ export {
   prEditCommand,
   prIssueCommentsCommand,
   prIssueCommentsLatestCommand,
+  prListCommand,
   prMergeCommand,
   prReplyCommand,
   prRerunChecksCommand,
@@ -17,6 +18,7 @@ export {
   prStatusCommand,
   prSubmitReviewCommand,
   prThreadsCommand,
+  prWaitMergeableCommand,
   prReviewTriageCommand,
   prReviewTriageBatchCommand,
   prViewCommand,

package/src/gh-tool/service.ts

@@ -1,5 +1,5 @@
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
-import { Context, Effect, Layer, Stream } from "effect";
+import { Context, Duration, Effect, Layer, Stream } from "effect";
 
 import type { GitHubRepoConfig } from "#config";
 import type { RepoInfo } from "./types";
@@ -8,6 +8,23 @@ import { GH_BINARY } from "./config";
 import { GitHubAuthError, GitHubCommandError, GitHubNotFoundError } from "./errors";
 import { ConfigService, getGitHubConfig, resolveGitHubRepoTarget } from "#config";
 
+// Transient GitHub-side failures worth a silent retry (vs. a hard error the agent must act on).
+const NETWORK_ERROR_RE =
+  /i\/o timeout|dial tcp|operation timed out|connection reset|\bEOF\b|HTTP 50[0-9]|50[0-9] (?:Bad Gateway|Service Unavailable|Gateway Timeout)|timeout awaiting/i;
+const AUTH_401_RE = /HTTP 401|Bad credentials/i;
+const MAX_GH_RETRIES = 2;
+
+// 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 =
+  /\b(create|edit|merge|comment|close|reopen|delete|review|ready|sync|rerun|cancel|mutation)\b|(?:-X|--method)\s+(?:POST|PATCH|PUT|DELETE)/i;
+const isSafeRetryRead = (args: readonly string[]): boolean => {
+  const joined = args.join(" ");
+  if (MUTATION_TOKENS.test(joined)) return false;
+  if (args[0] === "api") return true; // GET by default; mutating methods already excluded above
+  return args.some((a) => READ_VERBS.has(a));
+};
+
 type GhResult = {
   stdout: string;
   stderr: string;
@@ -134,7 +151,7 @@ export class GitHubService extends Context.Service<
             ),
           );
 
-        const runGh = Effect.fn("GitHubService.runGh")(function* (args: string[]) {
+        const runGhAttempt = Effect.fn("GitHubService.runGhAttempt")(function* (args: string[]) {
           const result = yield* executeGh(args);
 
           if (result.exitCode !== 0) {
@@ -149,15 +166,41 @@ export class GitHubService extends Context.Service<
               });
             }
 
+            // Expired/invalid token (401) is distinct from "never logged in" — the fix is refresh.
+            if (AUTH_401_RE.test(result.stderr)) {
+              return yield* new GitHubAuthError({
+                message: "GitHub credentials rejected (HTTP 401). Token is missing or expired.",
+                hint: "Refresh the GitHub CLI token, then retry.",
+                nextCommand: "gh auth refresh -h github.com",
+              });
+            }
+
+            // Transient network/5xx — flag retryable so the wrapper below can replay safe reads.
+            if (NETWORK_ERROR_RE.test(result.stderr)) {
+              return yield* new GitHubCommandError({
+                message: `Transient GitHub network error: ${result.stderr.trim()}`,
+                command: `gh ${args.join(" ")}`,
+                exitCode: result.exitCode,
+                stderr: result.stderr,
+                retryable: true,
+                hint: "Transient GitHub/network failure. Read commands auto-retry; if it persists, check VPN/connectivity.",
+              });
+            }
+
             if (
               result.stderr.includes("not found") ||
               result.stderr.includes("Could not resolve")
             ) {
+              const ghRepo = yield* RepoTarget;
               return yield* new GitHubNotFoundError({
-                message: result.stderr,
-                resource: "unknown",
+                message: ghRepo
+                  ? `${result.stderr.trim()} (queried repo: ${ghRepo})`
+                  : result.stderr,
+                resource: ghRepo ?? "unknown",
                 identifier: "unknown",
-                hint: "Verify the resource exists and you have access. Check repository owner/name spelling.",
+                hint: ghRepo
+                  ? `Queried ${ghRepo}. If the resource lives in another repo, pass --repo (e.g. --repo fe).`
+                  : "Verify the resource exists and you have access. Check repository owner/name spelling.",
               });
             }
 
@@ -172,6 +215,25 @@ export class GitHubService extends Context.Service<
           return result;
         });
 
+        // Auto-retry transient failures, but only for idempotent reads (never replay a mutation).
+        const runGh = (args: string[]): Effect.Effect<GhResult, GhError> => {
+          const canRetry = isSafeRetryRead(args);
+          const loop = (attempt: number): Effect.Effect<GhResult, GhError> =>
+            runGhAttempt(args).pipe(
+              Effect.catch((err) => {
+                const retryable =
+                  err instanceof GitHubCommandError && err.retryable === true && canRetry;
+                if (retryable && attempt < MAX_GH_RETRIES) {
+                  return Effect.sleep(Duration.millis(500 * 2 ** attempt)).pipe(
+                    Effect.flatMap(() => loop(attempt + 1)),
+                  );
+                }
+                return Effect.fail(err);
+              }),
+            );
+          return loop(0);
+        };
+
         const runGhJson = <T>(args: string[]) =>
           Effect.gen(function* () {
             const result = yield* runGh(args);

package/src/gh-tool/workflow.ts

@@ -212,6 +212,10 @@ const cancelRun = Effect.fn("workflow.cancelRun")(function* (runId: number, repo
   };
 });
 
+// `gh run watch` has no native timeout and was observed hanging a turn for 36 min. Cap it and
+// fall back to a one-shot snapshot, mirroring the `pr checks --watch` cap (M1).
+const WATCH_RUN_TIMEOUT_SECONDS = 120;
+
 const watchRun = Effect.fn("workflow.watchRun")(function* (runId: number, repo: string | null) {
   const gh = yield* GitHubService;
 
@@ -232,6 +236,10 @@ const watchRun = Effect.fn("workflow.watchRun")(function* (runId: number, repo:
       }
       return Effect.fail(error);
     }),
+    Effect.timeoutOrElse({
+      duration: WATCH_RUN_TIMEOUT_SECONDS * 1000,
+      orElse: () => Effect.succeed(null),
+    }),
   );
 
   const finalState = yield* viewRun(runId, repo);
@@ -245,7 +253,10 @@ const watchRun = Effect.fn("workflow.watchRun")(function* (runId: number, repo:
       status: job.status,
       conclusion: job.conclusion,
     })),
-    watchOutput: result.stdout,
+    watchOutput:
+      result === null
+        ? `(watch capped at ${WATCH_RUN_TIMEOUT_SECONDS}s; status taken from snapshot — re-run to keep watching)`
+        : result.stdout,
   };
 });
 

package/src/shared/audit.ts

@@ -116,9 +116,34 @@ const formatUnknownError = (error: unknown): string => {
   return String(error);
 };
 
+// effect-cli `ShowHelp` is a control-flow error: empty `errors[]` means a plain `--help` (exit 0),
+// a non-empty `errors[]` means a real parse failure (unrecognized option, missing arg, …) that was
+// downgraded to a help render. Distinguish them so we neither mislabel help as a failure (H4) nor
+// hide the actual syntax error behind the opaque "Help requested" string (M4).
+const getShowHelpErrors = (error: unknown): readonly unknown[] | undefined => {
+  if (typeof error === "object" && error !== null && Reflect.get(error, "_tag") === "ShowHelp") {
+    const errors = Reflect.get(error, "errors");
+    return Array.isArray(errors) ? errors : [];
+  }
+  return undefined;
+};
+
+const isPureHelpCause = (cause: Cause.Cause<unknown>): boolean => {
+  const firstFailure = cause.reasons.find(Cause.isFailReason);
+  const showHelpErrors =
+    firstFailure === undefined ? undefined : getShowHelpErrors(firstFailure.error);
+  return showHelpErrors !== undefined && showHelpErrors.length === 0;
+};
+
 const formatCause = (cause: Cause.Cause<unknown>): string => {
   const firstFailure = cause.reasons.find(Cause.isFailReason);
   if (firstFailure !== undefined) {
+    const showHelpErrors = getShowHelpErrors(firstFailure.error);
+    if (showHelpErrors !== undefined) {
+      return showHelpErrors.length > 0
+        ? showHelpErrors.map((e) => formatUnknownError(e)).join("; ")
+        : "Help requested";
+    }
     return formatUnknownError(firstFailure.error);
   }
 
@@ -296,19 +321,23 @@ export const withAudit = <A, E, R>(
     const tool = safeToolName(toolName || deriveToolNameFromArgv());
 
     return Effect.matchCauseEffect(program, {
-      onFailure: (cause) =>
-        Effect.flatMap(
+      onFailure: (cause) => {
+        // A bare `--help` exits 0 and is not a tool failure — recording it as one inflated the
+        // suite-wide fail rate by ~21% (H4). A ShowHelp carrying parse errors is still a failure.
+        const pureHelp = isPureHelpCause(cause);
+        return Effect.flatMap(
           safelyRecord({
             tool,
             project,
             args,
             duration: Date.now() - startedAt,
-            success: false,
-            error: formatCause(cause),
-            exitCode: extractExitCode(cause),
+            success: pureHelp,
+            error: pureHelp ? undefined : formatCause(cause),
+            exitCode: pureHelp ? 0 : extractExitCode(cause),
           }),
           () => Effect.failCause(cause),
-        ),
+        );
+      },
       onSuccess: (value) =>
         Effect.flatMap(
           safelyRecord({

package/src/shared/error-renderer.ts

@@ -12,12 +12,16 @@ const formatError = (error: unknown): string => {
     const tag = (error as Record<string, unknown>)._tag as string;
     const message = (error as Record<string, unknown>).message;
     const hint = (error as Record<string, unknown>).hint;
+    const nextCommand = (error as Record<string, unknown>).nextCommand;
     let result = "";
     if (typeof message === "string") {
       result = `${tag}: ${message}`;
     } else {
       const details = Object.entries(error as Record<string, unknown>)
-        .filter(([key, val]) => typeof val === "string" && key !== "_tag" && key !== "hint")
+        .filter(
+          ([key, val]) =>
+            typeof val === "string" && key !== "_tag" && key !== "hint" && key !== "nextCommand",
+        )
         .map(([key, val]) => `${key}=${String(val)}`)
         .join(", ");
       result = details ? `${tag}: ${details}` : tag;
@@ -25,6 +29,11 @@ const formatError = (error: unknown): string => {
     if (typeof hint === "string") {
       result += `\n  Hint: ${hint}`;
     }
+    // Surface the exact corrective invocation that tagged errors already carry — without this
+    // the affordance is computed everywhere and shown nowhere.
+    if (typeof nextCommand === "string" && nextCommand.length > 0) {
+      result += `\n  Try: ${nextCommand}`;
+    }
     return result;
   }
   if (error instanceof Error) return error.message;