@brainervirus/workit-core 8.0.1 → 8.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-core",
-  "version": "8.0.1",
+  "version": "8.1.1",
   "private": false,
   "description": "Workit shared core — task, policy, evidence, review, decision, worker, and writer state for agentic coding workflows",
   "keywords": [

package/src/core/branch-policy.ts

@@ -9,17 +9,34 @@ const PREFIXES = {
   hotfix: "hotfix/*",
 };
 
+/**
+ * Local branch names plus origin's remote-tracking ones (`origin/develop`
+ * counts as `develop`; a fork or mirror remote's branches do not).
+ */
+const branchNames = (workspaceRoot: string): Set<string> => {
+  const r = spawnSync(
+    "git",
+    ["for-each-ref", "--format=%(refname)", "refs/heads", "refs/remotes/origin"],
+    { cwd: workspaceRoot, encoding: "utf8" },
+  );
+  if (r.status !== 0) return new Set();
+  return new Set(
+    (r.stdout ?? "")
+      .split("\n")
+      .filter(Boolean)
+      .map((ref) =>
+        ref.startsWith("refs/heads/")
+          ? ref.slice("refs/heads/".length)
+          : ref.slice("refs/remotes/origin/".length),
+      ),
+  );
+};
+
 export const detectBranchPolicy = (workspaceRoot: string) => {
-  const branchExists = (name: string): boolean => {
-    const r = spawnSync("git", ["branch", "--list", name], {
-      cwd: workspaceRoot,
-      encoding: "utf8",
-    });
-    return r.status === 0 && (r.stdout ?? "").trim() !== "";
-  };
-  const develop = branchExists("develop");
-  const main = branchExists("main");
-  const master = branchExists("master");
+  const names = branchNames(workspaceRoot);
+  const develop = names.has("develop");
+  const main = names.has("main");
+  const master = names.has("master");
   const root = main ? "main" : master ? "master" : null;
 
   if (develop) {
@@ -61,3 +78,13 @@ export const detectBranchPolicy = (workspaceRoot: string) => {
     prefixes: PREFIXES,
   };
 };
+
+/**
+ * The preset this repository's branches imply (develop -> gitflow, main ->
+ * github-flow, master -> trunk-based), or null when they imply none. Used
+ * only when no branch policy is configured anywhere (core/config.ts).
+ */
+export const repoBranchPreset = (workspaceRoot: string): BranchPreset | null => {
+  const detected = detectBranchPolicy(workspaceRoot);
+  return detected.developBranch || detected.allowed.length ? detected.preset : null;
+};

package/src/core/branch.ts

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import path from "node:path";
+import { repoBranchPreset } from "./branch-policy";
 import { matchCommitFlavor } from "./commit-flavors";
 import { gitContext } from "./git";
 import {
@@ -100,6 +101,7 @@ function effectiveWorkspacePolicy(
           resolveConfiguredBranchPolicy(
             config,
             selected.policy ? { branchPolicy: selected.policy as WorkspaceBranchPolicy } : null,
+            () => repoBranchPreset(workspaceRoot),
           ),
         ),
         provenance: { branchPolicy: selected.source },

package/src/core/config.ts

@@ -138,6 +138,12 @@ const DEFAULTS: ToolkitConfig = {
   commitPolicy: { preset: "conventional" },
 };
 
+// Configs whose branch policy nobody chose (no config.json, or one without a
+// valid branchPolicy.preset). For them the repository's own branches pick the
+// preset (resolveBranchPolicy's `repoPreset`), so a main-only repository is
+// not held to gitflow's `develop`.
+const unchosenBranchPolicy = new WeakSet<ToolkitConfig>([DEFAULTS]);
+
 const readSafe = (p: string): string | null => {
   try {
     return readFileSync(p, "utf8");
@@ -191,36 +197,35 @@ const parseConfigResult = (raw: string | null, file: string): ReaderResult<Toolk
       ? input.commitPolicy?.preset
       : "conventional"
   ) as CommitFlavorPreset;
-  return {
-    status: "valid",
-    path: file,
-    config: {
-      locale,
-      localeOptions: Array.isArray(input.localeOptions)
-        ? input.localeOptions
-        : DEFAULTS.localeOptions,
-      // RL-02/CA-23: the persisted preset is authoritative; derived allowed /
-      // protected fields always reset from PRESETS via the one shared merge.
-      branchPolicy: mergePreset(
-        preset,
-        {
-          allowed: Array.isArray(input.branchPolicy?.allowed)
-            ? input.branchPolicy.allowed
-            : undefined,
-          protectedNames: Array.isArray(input.branchPolicy?.protected)
-            ? input.branchPolicy.protected
-            : undefined,
-        },
-        DEFAULTS,
-      ),
-      commitPolicy: {
-        preset: commitPreset,
-        ...(typeof input.commitPolicy?.pattern === "string"
-          ? { pattern: input.commitPolicy.pattern }
-          : {}),
+  const config: ToolkitConfig = {
+    locale,
+    localeOptions: Array.isArray(input.localeOptions)
+      ? input.localeOptions
+      : DEFAULTS.localeOptions,
+    // RL-02/CA-23: the persisted preset is authoritative; derived allowed /
+    // protected fields always reset from PRESETS via the one shared merge.
+    branchPolicy: mergePreset(
+      preset,
+      {
+        allowed: Array.isArray(input.branchPolicy?.allowed)
+          ? input.branchPolicy.allowed
+          : undefined,
+        protectedNames: Array.isArray(input.branchPolicy?.protected)
+          ? input.branchPolicy.protected
+          : undefined,
       },
+      DEFAULTS,
+    ),
+    commitPolicy: {
+      preset: commitPreset,
+      ...(typeof input.commitPolicy?.pattern === "string"
+        ? { pattern: input.commitPolicy.pattern }
+        : {}),
     },
   };
+  if (!Object.hasOwn(PRESETS, input.branchPolicy?.preset as string))
+    unchosenBranchPolicy.add(config);
+  return { status: "valid", path: file, config };
 };
 
 export const readConfigTyped = (dir?: string): ReaderResult<ToolkitConfig> => {
@@ -298,19 +303,28 @@ export const branchGlobPattern = (glob: string): RegExp =>
 export const resolveBranchPolicy = (
   config: ToolkitConfig,
   workspace?: { branchPolicy?: Record<string, any> } | null,
+  /** The preset the repository's branches imply (core/branch-policy.ts repoBranchPreset). */
+  repoPreset?: () => BranchPreset | null,
 ): {
   preset: BranchPreset;
   allowed: RegExp[];
   protected: Set<string>;
   integration: "pr" | "merge";
   defaultTargetBranch: string;
+  /** No policy was configured; the repository's branches chose the preset. */
+  detected: boolean;
 } => {
   const wp = workspace?.branchPolicy ?? {};
   // An invalid workspace preset (e.g. a typo) falls back to the global preset,
   // preserving resolution order workspace > global > preset, instead of
   // crashing on PRESETS[preset] (mirrors parseConfigResult's Object.hasOwn).
+  const workspacePreset = Object.hasOwn(PRESETS, wp.preset);
+  // With no policy chosen anywhere, the repository's branches pick the preset
+  // (M10); the gitflow protected names stay protected regardless.
+  const detected =
+    !workspacePreset && unchosenBranchPolicy.has(config) ? (repoPreset?.() ?? null) : null;
   const preset = (
-    Object.hasOwn(PRESETS, wp.preset) ? wp.preset : (config.branchPolicy?.preset ?? "gitflow")
+    workspacePreset ? wp.preset : (detected ?? config.branchPolicy?.preset ?? "gitflow")
   ) as BranchPreset;
   // RL-02: the preset is authoritative — allowed/protected re-derive from the
   // workspace's own values or the preset table, never the global config's, and
@@ -327,11 +341,16 @@ export const resolveBranchPolicy = (
   return {
     preset,
     allowed,
-    protected: new Set(merged.protected.map((p) => p.toLowerCase())),
+    protected: new Set(
+      [...merged.protected, ...(detected ? PRESETS.gitflow.protected : [])].map((p) =>
+        p.toLowerCase(),
+      ),
+    ),
     integration: wp.integration === "merge" ? "merge" : "pr",
     // CA-05: preset-aware default target when vcs.defaultTargetBranch is unset.
     defaultTargetBranch:
       preset === "github-flow" ? "main" : preset === "trunk-based" ? "master" : "develop",
+    detected: detected !== null,
   };
 };
 

package/src/core/workspaces.ts

@@ -1,3 +1,4 @@
+import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { readFileSync, realpathSync } from "node:fs";
 import path from "node:path";
@@ -14,6 +15,7 @@ import {
   type ToolkitConfig,
 } from "./config";
 import type { CommitFlavorPreset } from "./commit-flavors";
+import { repoBranchPreset } from "./branch-policy";
 
 export type VcsProvider = "gitlab" | "github";
 
@@ -412,6 +414,70 @@ export const validateWorkspaceGlob = (glob: string): GlobValidation => {
   return { ok: true };
 };
 
+/** A workspaces.json problem for the user to fix; CLI verbs report it as `blocked`. */
+export class WorkspaceConfigError extends Error {
+  override name = "WorkspaceConfigError";
+}
+
+const mainCheckouts = new Map<string, string | null>();
+
+/**
+ * The main checkout of the linked worktree at `cwd` (null when cwd is not a
+ * linked worktree). A worktree outside every glob (~/.codex/worktrees/…,
+ * ../x, /tmp) belongs to the workspace of the checkout it was added from (B2).
+ */
+const mainCheckoutOf = (cwd: string): string | null => {
+  const cached = mainCheckouts.get(cwd);
+  if (cached !== undefined) return cached;
+  // The repository at cwd, not one an inherited GIT_DIR/GIT_WORK_TREE names.
+  const env = { ...process.env };
+  for (const name of ["GIT_DIR", "GIT_WORK_TREE", "GIT_COMMON_DIR", "GIT_INDEX_FILE"])
+    delete env[name];
+  const git = (args: string[]): string | null => {
+    const run = spawnSync("git", args, {
+      cwd,
+      env,
+      encoding: "utf8",
+      timeout: 5000,
+      windowsHide: true,
+    });
+    return run.status === 0 ? run.stdout : null;
+  };
+  let main: string | null = null;
+  const dirs = git(["rev-parse", "--path-format=absolute", "--git-dir", "--git-common-dir"]);
+  const [gitDir, common] = (dirs ?? "").trim().split(/\r?\n/u);
+  if (gitDir && common && path.resolve(gitDir) !== path.resolve(common)) {
+    // The first `worktree` entry is the main one, also with --separate-git-dir
+    // (where the common dir is not <main>/.git); a bare repo lists its own path.
+    const listed = /^worktree (.+)$/mu.exec(git(["worktree", "list", "--porcelain"]) ?? "")?.[1];
+    main = listed?.trim() || (path.basename(common) === ".git" ? path.dirname(common) : common);
+  }
+  mainCheckouts.set(cwd, main);
+  return main;
+};
+
+/**
+ * The entries whose glob matches cwd (its logical and real path); for a linked
+ * worktree that matches none, the entries matching its main checkout.
+ */
+const matchingEntries = <T extends { glob: string }>(cwd: string, entries: readonly T[]): T[] => {
+  const match = (where: string): T[] => {
+    const targets = [where, realpathOf(where)].map((value) => value.replaceAll("\\", "/"));
+    return entries.filter((entry) => {
+      const glob = entry.glob.replaceAll("\\", "/");
+      const canonical = canonicalGlob(glob);
+      return targets.some(
+        (target) =>
+          matchWorkspace(glob, target) || (canonical !== glob && matchWorkspace(canonical, target)),
+      );
+    });
+  };
+  const direct = match(cwd);
+  if (direct.length) return direct;
+  const main = mainCheckoutOf(cwd);
+  return main ? match(main) : direct;
+};
+
 const realpathOf = (p: string): string => {
   // realpathSync.native goes through libuv, which expands Windows 8.3 short
   // names (C:\Users\RUNNER~1 -> C:\Users\runneradmin); the plain realpathSync
@@ -452,13 +518,17 @@ const selectWorkspaceMatch = <T extends { name: string; glob: string }>(
     const named = matches.filter((entry) => entry.name === workspaceName);
     if (named.length === 1) return named[0];
     if (named.length > 1)
-      throw new Error(`ambiguous workspace ${JSON.stringify(workspaceName)} for ${cwd}`);
+      throw new WorkspaceConfigError(
+        `ambiguous workspace ${JSON.stringify(workspaceName)} for ${cwd}`,
+      );
     if (matches.length > 0) {
-      throw new Error(
+      throw new WorkspaceConfigError(
         `workspace ${JSON.stringify(workspaceName)} does not match ${cwd}; matching choices: ${matches.map((entry) => entry.name).join(", ")}`,
       );
     }
-    throw new Error(`workspace ${JSON.stringify(workspaceName)} does not match ${cwd}`);
+    throw new WorkspaceConfigError(
+      `workspace ${JSON.stringify(workspaceName)} does not match ${cwd}`,
+    );
   }
 
   if (matches.length < 2) return matches[0];
@@ -467,7 +537,7 @@ const selectWorkspaceMatch = <T extends { name: string; glob: string }>(
     (entry) => globSpecificity(entry.glob) === highestSpecificity,
   );
   if (mostSpecific.length > 1) {
-    throw new Error(
+    throw new WorkspaceConfigError(
       `ambiguous workspace for ${cwd}; choose one of: ${mostSpecific.map((entry) => entry.name).join(", ")}`,
     );
   }
@@ -485,23 +555,7 @@ export const resolveWorkspaceFromEntries = <T extends { name: string; glob: stri
   // written with the logical path, so a workspace would silently stop
   // matching on macOS. Match both forms on each side; on Linux both forms
   // are identical so behavior is unchanged.
-  const targets = [cwd, realpathOf(cwd)].map((p) => p.replaceAll("\\", "/"));
-  const matches: T[] = [];
-  for (const ws of entries) {
-    const glob = ws.glob.replaceAll("\\", "/");
-    const canonical = canonicalGlob(glob);
-    let matched = false;
-    for (const target of targets) {
-      if (
-        matchWorkspace(glob, target) ||
-        (canonical !== glob && matchWorkspace(canonical, target))
-      ) {
-        matched = true;
-        break;
-      }
-    }
-    if (matched) matches.push(ws);
-  }
+  const matches = matchingEntries(cwd, entries);
   return selectWorkspaceMatch(matches, cwd, workspaceName) ?? null;
 };
 
@@ -512,7 +566,8 @@ export const resolveWorkspaceFrom = (
   workspaceName?: string,
 ): WorkspaceConfig | null => {
   const result = readWorkspacesResult(dir);
-  if (result.status === "malformed" || result.status === "invalid") throw new Error(result.error);
+  if (result.status === "malformed" || result.status === "invalid")
+    throw new WorkspaceConfigError(result.error);
   return resolveWorkspaceFromEntries(cwd, result.entries, workspaceName);
 };
 
@@ -585,7 +640,7 @@ const matchRuntimeWorkspace = (
     raw = readFileSync(file, "utf8");
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
-    throw new Error(
+    throw new WorkspaceConfigError(
       `${file} could not be read: ${error instanceof Error ? error.message : String(error)}`,
       { cause: error },
     );
@@ -594,29 +649,21 @@ const matchRuntimeWorkspace = (
   try {
     parsed = JSON.parse(raw);
   } catch {
-    throw new Error(`${file} is not valid JSON`);
+    throw new WorkspaceConfigError(`${file} is not valid JSON`);
   }
   const validated = runtimeWorkspaceIndexSchema.safeParse(parsed);
   if (!validated.success) {
     const detail = validated.error.issues
       .map((issue) => `${issue.path.map(String).join(".") || "workspaces"}: ${issue.message}`)
       .join("; ");
-    throw new Error(`${file} has invalid workspace matching data: ${detail}`);
+    throw new WorkspaceConfigError(`${file} has invalid workspace matching data: ${detail}`);
   }
   const entries = validated.data.workspaces;
   for (const entry of entries ?? []) {
     const glob = validateWorkspaceGlob(entry.glob);
-    if (!glob.ok) throw new Error(`${file} workspace ${entry.name}: ${glob.error}`);
+    if (!glob.ok) throw new WorkspaceConfigError(`${file} workspace ${entry.name}: ${glob.error}`);
   }
-  const targets = [cwd, realpathOf(cwd)].map((value) => value.replaceAll("\\", "/"));
-  const matches = (entries ?? []).filter((entry) => {
-    const glob = entry.glob.replaceAll("\\", "/");
-    const canonical = canonicalGlob(glob);
-    return targets.some(
-      (target) =>
-        matchWorkspace(glob, target) || (canonical !== glob && matchWorkspace(canonical, target)),
-    );
-  });
+  const matches = matchingEntries(cwd, entries ?? []);
   const workspaceName = process.env.WORKFLOW_WORKSPACE_NAME?.trim() || undefined;
   const selected = selectWorkspaceMatch(matches, cwd, workspaceName);
   return selected ? { file, selected } : null;
@@ -648,7 +695,7 @@ const resolveRuntimeWorkspaceCandidate = (
     const detail = policy.error.issues
       .map((issue) => `${issue.path.map(String).join(".") || "workspace"}: ${issue.message}`)
       .join("; ");
-    throw new Error(`${file} has invalid ${kind} policy configuration: ${detail}`);
+    throw new WorkspaceConfigError(`${file} has invalid ${kind} policy configuration: ${detail}`);
   }
   return policy.data as RuntimeWorkspaceCandidate;
 };
@@ -669,12 +716,12 @@ export const resolveRuntimeWorkspacePolicy = (
     candidate.defaultProfile &&
     !Object.hasOwn(candidate.profiles ?? {}, candidate.defaultProfile)
   )
-    throw new Error(
+    throw new WorkspaceConfigError(
       `workspace ${JSON.stringify(candidate.name)} has no profile ${JSON.stringify(candidate.defaultProfile)}`,
     );
   const profile = profileName ? candidate.profiles?.[profileName] : undefined;
   if (profileName && !profile)
-    throw new Error(
+    throw new WorkspaceConfigError(
       `workspace ${JSON.stringify(candidate.name)} has no profile ${JSON.stringify(profileName)}`,
     );
   const profilePolicy = profile?.[key] as WorkspaceBranchPolicy | WorkspaceCommitPolicy | undefined;
@@ -731,6 +778,8 @@ export const resolveWorkspacePolicy = (
   config: ToolkitConfig,
   workspace: WorkspaceConfig | null,
   profileName?: string,
+  /** The preset the checkout's branches imply, used when no policy is configured. */
+  repoPreset?: () => BranchPreset | null,
 ): WorkspacePolicyResolution | { status: "invalid"; error: string } => {
   const selected = workspace
     ? resolveWorkspaceProfile(workspace, profileName)
@@ -745,7 +794,7 @@ export const resolveWorkspacePolicy = (
     status: "resolved",
     workspace: selected.workspace,
     profileName: selected.profileName,
-    branchPolicy: resolveConfiguredBranchPolicy(config, selected.workspace),
+    branchPolicy: resolveConfiguredBranchPolicy(config, selected.workspace, repoPreset),
     commitPolicy: resolveConfiguredCommitPolicy(config, selected.workspace),
     provenance: selected.provenance,
   };
@@ -792,6 +841,7 @@ export function workspaceDefaultTarget(cwd: string, globalDefault: unknown): str
   const policyDefault = resolveConfiguredBranchPolicy(
     readConfig(),
     selected.policy ? { branchPolicy: selected.policy as WorkspaceBranchPolicy } : null,
+    () => repoBranchPreset(cwd),
   ).defaultTargetBranch;
   return String(
     (ws?.vcs as { defaultTargetBranch?: unknown } | undefined)?.defaultTargetBranch ??

package/src/forge/exec.ts

@@ -19,6 +19,8 @@ export type CliRun = {
   timedOut: boolean;
   /** The binary is not on PATH. */
   missing: boolean;
+  /** The timeout actually applied (a deadline may have shortened it). */
+  timeoutMs?: number;
 };
 
 /** Runs one gh/glab command. Injected in tests to replay recorded API fixtures. */
@@ -109,6 +111,47 @@ export const installHint = (bin: CliBin): string =>
 export const loginHint = (bin: CliBin, apiHost: string): string =>
   `${bin} auth login --hostname ${apiHost}`;
 
+/** Transport trouble (DNS, TCP, TLS, a 5xx from the forge): retryable, exit 5. */
+const NETWORK =
+  /error connecting|could not resolve|no such host|connection (refused|reset|timed out)|network is unreachable|i\/o timeout|tls handshake|unexpected eof|\bHTTP 5\d\d\b|bad gateway|service unavailable|gateway time-?out/iu;
+
+export const isNetworkError = (text: string): boolean => NETWORK.test(text);
+
+/**
+ * The forge's own reason for a refusal: `gh api`/`glab api` print the error
+ * body on stdout (`message`, `errors[].message`), stderr only says "HTTP 422".
+ */
+export function forgeReason(run: Pick<CliRun, "stdout" | "stderr">): string {
+  const parts: string[] = [];
+  try {
+    const body = JSON.parse(run.stdout) as {
+      message?: unknown;
+      error?: unknown;
+      errors?: unknown;
+    };
+    const add = (value: unknown): void => {
+      if (typeof value === "string" && value.trim()) parts.push(value.trim());
+      else if (Array.isArray(value)) value.forEach(add);
+      else if (value && typeof value === "object") {
+        const record = value as Record<string, unknown>;
+        if (typeof record.message === "string") add(record.message);
+        else if (!("code" in record)) Object.values(record).forEach(add);
+      }
+    };
+    add(body.message);
+    add(body.error);
+    add(body.errors);
+  } catch {
+    // not a JSON body
+  }
+  const stderr = (run.stderr.split(/\r?\n/u).find((value) => value.trim()) ?? "").trim();
+  const unique = [...new Set(parts)];
+  const text = unique.length
+    ? `${unique.join("; ")}${stderr ? ` (${stderr.replace(/^gh: |^glab: /u, "")})` : ""}`
+    : stderr || (run.stdout.split(/\r?\n/u).find((value) => value.trim()) ?? "");
+  return redactText(text).slice(0, 300);
+}
+
 /** Map a failed CLI run to an envelope error. */
 export function cliFailure<T>(
   bin: CliBin,
@@ -119,7 +162,13 @@ export function cliFailure<T>(
 ): ForgeResult<T> {
   if (run.missing) return failure("unavailable", `${bin} is not installed`, installHint(bin));
   if (run.timedOut)
-    return failure("unavailable", `${bin} api ${what} timed out after ${timeoutMs} ms`);
+    return failure(
+      "unavailable",
+      run.timeoutMs === 0
+        ? `${bin} api ${what} not attempted: the command's time budget ran out`
+        : `${bin} api ${what} timed out after ${run.timeoutMs ?? timeoutMs} ms`,
+      `check the network to ${apiHost}, then retry`,
+    );
   const stderr = redactText(run.stderr).trim();
   if (
     /auth login|not logged in|no token|authentication required|bad credentials|\b401\b|unauthorized/iu.test(
@@ -133,6 +182,12 @@ export function cliFailure<T>(
     );
   if (/\b404\b|not found/iu.test(stderr)) return failure("not_found", `${what} was not found`);
   const first = stderr.split(/\r?\n/u).find((value) => value.trim()) ?? `exit ${run.status}`;
+  if (isNetworkError(stderr))
+    return failure(
+      "unavailable",
+      `${bin} api ${what} failed (network): ${first.slice(0, 200)}`,
+      `check the network to ${apiHost}, then retry`,
+    );
   return failure("failed", `${bin} api ${what} failed: ${first.slice(0, 200)}`);
 }
 
@@ -197,7 +252,7 @@ export function apiWrite<T>(
   const run = runner(bin, args, { timeoutMs });
   if (run.status !== 0) {
     const text = redactText(`${run.stderr}\n${run.stdout}`).trim();
-    const reason = (text.split(/\r?\n/u).find((value) => value.trim()) ?? "").slice(0, 200);
+    const reason = forgeReason(run);
     if (
       !run.missing &&
       !run.timedOut &&
@@ -210,7 +265,21 @@ export function apiWrite<T>(
       );
     if (!run.missing && !run.timedOut && /\b(405|406|422)\b/u.test(text))
       return failure("blocked", `${what} refused by the forge: ${reason}`);
-    return cliFailure(bin, apiHost, run, what, timeoutMs);
+    const failed = cliFailure<T>(bin, apiHost, run, what, timeoutMs);
+    // A timeout, a dropped connection or a 5xx may come after the forge
+    // applied the write: look before writing again.
+    if (
+      !failed.ok &&
+      failed.code === "unavailable" &&
+      !run.missing &&
+      !/ is not authenticated for /u.test(failed.error)
+    )
+      return failure(
+        "unavailable",
+        failed.error,
+        "workit pr status  # the write may have gone through; check it first, then retry",
+      );
+    return failed;
   }
   if (!run.stdout.trim()) return { ok: true, data: {} as T };
   try {

package/src/forge/report.ts

@@ -473,14 +473,15 @@ export function waitVerdict(
     return { state: "waiting", reason: "head_mismatch" };
   const checks = doc.checks.state;
   if (checks === "failing") return { state: "failed", reason: "checks_failing" };
-  if (checks === "pending") return { state: "waiting", reason: "checks_pending" };
-  if (checks === "passing") return { state: "ready", reason: "checks_passing" };
-  if (doc.conflicts)
+  // Before "pending": CI never runs on a conflicting PR, so waiting cannot help (M8).
+  if (doc.conflicts && checks !== "passing")
     return {
       state: "blocked",
       reason: "conflicts",
       unblock: `rebase onto ${doc.base} and push; CI does not run on a conflicting PR`,
     };
+  if (checks === "pending") return { state: "waiting", reason: "checks_pending" };
+  if (checks === "passing") return { state: "ready", reason: "checks_passing" };
   const ciRequired =
     doc.checks.missingRequired === null ||
     doc.mergeState === "ci_must_pass" ||