@brainervirus/workit-core 8.1.0 → 8.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-core",
-  "version": "8.1.0",
+  "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/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";
@@ -413,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
@@ -453,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];
@@ -468,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(", ")}`,
     );
   }
@@ -486,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;
 };
 
@@ -513,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);
 };
 
@@ -586,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 },
     );
@@ -595,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;
@@ -649,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;
 };
@@ -670,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;

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" ||

package/src/forge/resolve.ts

@@ -2,7 +2,8 @@
 // §2.0 Identity).
 //
 // - The push remote host decides GitHub vs GitLab. A workspace provider that
-//   disagrees is `blocked`, never silently overridden.
+//   disagrees is `blocked` for the forge verbs, never silently overridden;
+//   `git push` (checkPushIdentity) only needs git, so it pushes with a note.
 // - PRs/MRs live in the base repository: an `upstream` remote on the same
 //   forge, else the push repo's fork parent, else the push repo itself.
 // - Every API call carries the workspace's credential explicitly, so the
@@ -23,9 +24,10 @@ import {
   type ForgeHosts,
   type SshConfig,
 } from "../git/rev";
-import { FORGE_TIMEOUTS, systemRunner, type ForgeRunner } from "./exec";
+import { FORGE_TIMEOUTS, isNetworkError, systemRunner, type ForgeRunner } from "./exec";
 import { createGitHubForge } from "./github";
 import { createGitLabForge } from "./gitlab";
+import { redactText } from "./redact";
 import { failure, success, type Forge, type ForgeResult, type Identity } from "./types";
 
 export type CredentialSource = "workspace_token_file" | "gh_account_token" | "cli_login";
@@ -62,51 +64,103 @@ export type ResolveOptions = {
   now?: () => number;
   /** ssh_config for Host aliases (default: the user's ~/.ssh/config). */
   sshConfig?: string | SshConfig;
+  /** Absolute deadline (`now()` clock) for every call, resolution included; null = none. */
+  deadline?: number | null;
 };
 
-const configuredHosts = (): ForgeHosts => {
-  const vcs = readVcsConfig();
-  if (vcs.status !== "valid") return {};
-  const host = (kind: "github" | "gitlab"): string[] => {
-    const value = (vcs.config[kind] as { host?: unknown } | undefined)?.host;
-    return typeof value === "string" && value.trim() ? [value.trim()] : [];
+// Per-process memo of credential lookups and /user answers (a long-lived MCP
+// server re-asks after the TTL). Scoped by runner, so an injected test runner
+// never sees another's answers, and keyed by the gh/glab config location, so
+// another GH_CONFIG_DIR never reuses them; only successes are kept.
+const MEMO_TTL_MS = 5 * 60_000;
+const SYSTEM_SCOPE = {};
+const memoScopes = new WeakMap<object, Map<string, { at: number; value: unknown }>>();
+
+type MemoScope = { owner: object; key: string };
+
+const memoScope = (runner: ForgeRunner | undefined, env: NodeJS.ProcessEnv): MemoScope => ({
+  owner: runner ?? SYSTEM_SCOPE,
+  key: [env.GH_CONFIG_DIR, env.GLAB_CONFIG_DIR, env.XDG_CONFIG_HOME, env.HOME]
+    .map((value) => value ?? "")
+    .join("|"),
+});
+
+function memo<T>(
+  scope: MemoScope,
+  key: string,
+  compute: () => { keep: boolean; value: T },
+  now = Date.now,
+): T {
+  let entries = memoScopes.get(scope.owner);
+  if (!entries) memoScopes.set(scope.owner, (entries = new Map()));
+  const full = `${scope.key} ${key}`;
+  const hit = entries.get(full);
+  if (hit && now() - hit.at < MEMO_TTL_MS) return hit.value as T;
+  const { keep, value } = compute();
+  if (keep) entries.set(full, { at: now(), value });
+  return value;
+}
+
+/** A runner whose calls are clamped to `limits.deadline`, carrying `token`. */
+function clampedRunner(
+  base: ForgeRunner,
+  limits: { deadline: number | null },
+  now: () => number,
+  token?: string,
+): ForgeRunner {
+  return (bin, args, callOptions) => {
+    let timeoutMs = callOptions.timeoutMs;
+    if (limits.deadline !== null) {
+      const remaining = limits.deadline - now();
+      if (remaining <= 0)
+        return {
+          status: null,
+          stdout: "",
+          stderr: "",
+          timedOut: true,
+          missing: false,
+          timeoutMs: 0,
+        };
+      timeoutMs = Math.min(timeoutMs, remaining);
+    }
+    const run = base(bin, args, { ...callOptions, timeoutMs, ...(token ? { token } : {}) });
+    return run.timedOut && run.timeoutMs === undefined ? { ...run, timeoutMs } : run;
+  };
+}
+
+/**
+ * `forge.identity` answered once per explicit credential per TTL (push, then
+ * pr create, …). The CLI's own login (`cli_login`) is never memoized: a
+ * `glab auth login` / `gh auth switch` must show on the next call.
+ */
+const memoizedIdentity = (forge: Forge, scope: MemoScope, credential: Credential): Forge => {
+  if (credential.credential === "cli_login") return forge;
+  const identity = (expected: string | null) => forge.identity(expected);
+  return {
+    ...forge,
+    identity: (expected: string | null) =>
+      memo(
+        scope,
+        `identity ${forge.kind} ${forge.apiHost} ${credential.credential} ${credential.token ?? ""} ${expected ?? ""}`,
+        () => {
+          const value = identity(expected);
+          return { keep: value.ok, value };
+        },
+      ),
   };
-  return { github: host("github"), gitlab: host("gitlab") };
 };
 
-const createForge = (derived: DerivedForge, repo: string, runner: ForgeRunner): Forge =>
-  derived.kind === "github"
-    ? createGitHubForge({ apiHost: derived.apiHost, repo, runner })
-    : createGitLabForge({ apiHost: derived.apiHost, repo, runner });
+type Credential = { token: string | undefined; credential: CredentialSource };
 
-export function resolveForge(
-  cwd: string,
-  options: ResolveOptions = {},
-): ForgeResult<ResolvedForge> {
-  let workspace: ReturnType<typeof resolveRuntimeWorkspaceVcs>;
-  try {
-    workspace = resolveRuntimeWorkspaceVcs(cwd);
-  } catch (error) {
-    return failure(
-      "blocked",
-      error instanceof Error ? error.message : String(error),
-      "fix ~/.config/workit/workspaces.json (workit init → Workspaces)",
-    );
-  }
-  const hosts = configuredHosts();
-  const pushed = pushForge(cwd, { branch: options.branch, hosts, sshConfig: options.sshConfig });
-  if (!pushed.ok) return failure(pushed.code, pushed.error, pushed.unblock);
-  const conflict = forgeConflict(pushed.forge, workspace?.vcs?.provider);
-  if (conflict) return failure("blocked", conflict.error, conflict.unblock);
-  const derived = pushed.forge;
+/** The credential every API call carries (see the header). */
+function resolveCredential(
+  workspace: ReturnType<typeof resolveRuntimeWorkspaceVcs>,
+  derived: DerivedForge,
+  run: ForgeRunner,
+  scope: MemoScope,
+): ForgeResult<Credential> {
   const { kind, apiHost } = derived;
-  const base = options.runner ?? systemRunner(kind, apiHost, options.env ?? process.env);
-  const now = options.now ?? Date.now;
   const expectedAccount = workspace?.vcs?.account ?? null;
-
-  // The credential for every call.
-  let token: string | undefined;
-  let credential: CredentialSource = "cli_login";
   const tokenFile = (workspace?.vcs as { tokenFile?: unknown } | undefined)?.tokenFile;
   if (typeof tokenFile === "string" && tokenFile.trim()) {
     // A stored token goes only to the host it is for: the public forge (also
@@ -127,6 +181,7 @@ export function resolveForge(
         `token_host_unverified: push host ${derived.host} only looks like ${kind}; workspace ${workspace?.name ?? "?"} vcs.tokenFile is not sent to it`,
         `if ${apiHost} is your ${kind} server, set ${kind}.host in ~/.config/workit/vcs.json (or vcs.host for the workspace); otherwise fix the push remote`,
       );
+    let token = "";
     try {
       token = fs.readFileSync(tokenFile.trim(), "utf8").trim();
     } catch {
@@ -142,42 +197,108 @@ export function resolveForge(
         `workspace ${workspace?.name ?? "?"} vcs.tokenFile is empty`,
         "fix vcs.tokenFile in ~/.config/workit/workspaces.json",
       );
-    credential = "workspace_token_file";
-  } else if (expectedAccount && kind === "github") {
-    const issued = base("gh", ["auth", "token", "--hostname", apiHost, "--user", expectedAccount], {
+    return success({ token, credential: "workspace_token_file" });
+  }
+  // glab keeps one login per host, so a GitLab account is checked, not selected.
+  if (!expectedAccount || kind !== "github")
+    return success({ token: undefined, credential: "cli_login" });
+  return memo(scope, `token ${apiHost} ${expectedAccount}`, () => {
+    const issued = run("gh", ["auth", "token", "--hostname", apiHost, "--user", expectedAccount], {
       timeoutMs: FORGE_TIMEOUTS.api,
     });
-    if (issued.missing)
-      return failure(
-        "unavailable",
-        "gh is not installed",
-        "install the GitHub CLI (https://cli.github.com) and run: gh auth login",
-      );
-    token = issued.status === 0 ? issued.stdout.trim() : "";
-    if (!token)
-      return failure(
-        "blocked",
-        `identity_unavailable: gh has no login for ${expectedAccount} on ${apiHost} (workspace ${workspace?.name ?? "?"})`,
-        `gh auth login --hostname ${apiHost}  # sign in as ${expectedAccount}; workit passes that account's token per call and never switches the active account`,
-      );
-    credential = "gh_account_token";
-  }
+    const value = authTokenResult(issued, apiHost, expectedAccount, workspace?.name ?? "?");
+    return { keep: value.ok, value };
+  });
+}
 
-  const limits: { deadline: number | null } = { deadline: null };
-  const runner: ForgeRunner = (bin, args, callOptions) => {
-    let timeoutMs = callOptions.timeoutMs;
-    if (limits.deadline !== null) {
-      const remaining = limits.deadline - now();
-      if (remaining <= 0)
-        return { status: null, stdout: "", stderr: "", timedOut: true, missing: false };
-      timeoutMs = Math.min(timeoutMs, remaining);
-    }
-    return base(bin, args, { ...callOptions, timeoutMs, ...(token ? { token } : {}) });
+/**
+ * `gh auth token --user`: a timeout or a transport error is `unavailable`
+ * (exit 5, retry); only gh saying it has no such login is identity_unavailable.
+ */
+function authTokenResult(
+  issued: ReturnType<ForgeRunner>,
+  apiHost: string,
+  account: string,
+  workspace: string,
+): ForgeResult<Credential> {
+  if (issued.missing)
+    return failure(
+      "unavailable",
+      "gh is not installed",
+      "install the GitHub CLI (https://cli.github.com) and run: gh auth login",
+    );
+  if (issued.timedOut)
+    return failure(
+      "unavailable",
+      `gh auth token ${issued.timeoutMs === 0 ? "not attempted: the time budget ran out" : `timed out after ${issued.timeoutMs ?? FORGE_TIMEOUTS.api} ms`} (looking up the ${account} login on ${apiHost})`,
+      "gh auth status  # check gh and the network, then retry",
+    );
+  const token = issued.status === 0 ? issued.stdout.trim() : "";
+  if (token) return success({ token, credential: "gh_account_token" });
+  const stderr = redactText(issued.stderr).trim();
+  const first = stderr.split(/\r?\n/u).find((line) => line.trim()) ?? "";
+  if (issued.status !== 0 && first && !/no oauth token|not logged in|no account/iu.test(stderr))
+    return failure(
+      "unavailable",
+      `gh auth token failed${isNetworkError(stderr) ? " (network)" : ""}: ${first.slice(0, 200)}`,
+      "gh auth status  # check gh and the network, then retry",
+    );
+  return failure(
+    "blocked",
+    `identity_unavailable: gh has no login for ${account} on ${apiHost} (workspace ${workspace})`,
+    `gh auth login --hostname ${apiHost}  # sign in as ${account}; workit passes that account's token per call and never switches the active account`,
+  );
+}
+
+const configuredHosts = (): ForgeHosts => {
+  const vcs = readVcsConfig();
+  if (vcs.status !== "valid") return {};
+  const host = (kind: "github" | "gitlab"): string[] => {
+    const value = (vcs.config[kind] as { host?: unknown } | undefined)?.host;
+    return typeof value === "string" && value.trim() ? [value.trim()] : [];
   };
+  return { github: host("github"), gitlab: host("gitlab") };
+};
+
+const createForge = (derived: DerivedForge, repo: string, runner: ForgeRunner): Forge =>
+  derived.kind === "github"
+    ? createGitHubForge({ apiHost: derived.apiHost, repo, runner })
+    : createGitLabForge({ apiHost: derived.apiHost, repo, runner });
+
+export function resolveForge(
+  cwd: string,
+  options: ResolveOptions = {},
+): ForgeResult<ResolvedForge> {
+  let workspace: ReturnType<typeof resolveRuntimeWorkspaceVcs>;
+  try {
+    workspace = resolveRuntimeWorkspaceVcs(cwd);
+  } catch (error) {
+    return failure(
+      "blocked",
+      error instanceof Error ? error.message : String(error),
+      "fix ~/.config/workit/workspaces.json (workit init → Workspaces)",
+    );
+  }
+  const hosts = configuredHosts();
+  const pushed = pushForge(cwd, { branch: options.branch, hosts, sshConfig: options.sshConfig });
+  if (!pushed.ok) return failure(pushed.code, pushed.error, pushed.unblock);
+  const conflict = forgeConflict(pushed.forge, workspace?.vcs?.provider);
+  if (conflict) return failure("blocked", conflict.error, conflict.unblock);
+  const derived = pushed.forge;
+  const { kind, apiHost } = derived;
+  const base = options.runner ?? systemRunner(kind, apiHost, options.env ?? process.env);
+  const scope = memoScope(options.runner, options.env ?? process.env);
+  const now = options.now ?? Date.now;
+  const expectedAccount = workspace?.vcs?.account ?? null;
+  // The deadline covers resolution too, so a verb's --timeout bounds it all.
+  const limits: { deadline: number | null } = { deadline: options.deadline ?? null };
+  const credential = resolveCredential(workspace, derived, clampedRunner(base, limits, now), scope);
+  if (!credential.ok) return credential;
+  const runner = clampedRunner(base, limits, now, credential.data.token);
 
   // Base repository: an `upstream` remote on the same forge, else the fork parent.
   const headRepo = derived.repo;
-  const probe = createForge(derived, headRepo, runner);
+  const probe = memoizedIdentity(createForge(derived, headRepo, runner), scope, credential.data);
   const info = probe.repoInfo(headRepo);
   if (!info.ok && info.code !== "not_found") return info;
   const headProjectId = info.ok ? info.data.id : null;
@@ -201,13 +322,16 @@ export function resolveForge(
       : (remotes.find((name) => repoOfRemote(name) === baseRepo) ?? pushed.remote);
 
   return success({
-    forge: baseRepo === headRepo ? probe : createForge(derived, baseRepo, runner),
+    forge:
+      baseRepo === headRepo
+        ? probe
+        : memoizedIdentity(createForge(derived, baseRepo, runner), scope, credential.data),
     remote: pushed.remote,
     url: pushed.url,
     derived,
     workspace: workspace?.name ?? null,
     expectedAccount,
-    credential,
+    credential: credential.data.credential,
     headRepo,
     headProjectId,
     fork: baseRepo !== headRepo,
@@ -225,16 +349,142 @@ export function checkIdentity(resolved: ResolvedForge): ForgeResult<Identity> {
   const { forge, expectedAccount } = resolved;
   const identity = forge.identity(expectedAccount);
   if (!identity.ok) return identity;
-  if (identity.data.matches === false) {
-    const bin = forge.kind === "github" ? "gh" : "glab";
-    const where = `workspace ${resolved.workspace ?? "?"}`;
+  if (identity.data.matches === false)
+    return mismatch(resolved, identity.data.login ?? "?", resolved.workspace);
+  return identity;
+}
+
+const mismatch = <T>(
+  resolved: Pick<ResolvedForge, "forge" | "credential" | "expectedAccount">,
+  login: string,
+  workspace: string | null,
+): ForgeResult<T> => {
+  const { forge, expectedAccount } = resolved;
+  const bin = forge.kind === "github" ? "gh" : "glab";
+  const where = `workspace ${workspace ?? "?"}`;
+  const fileFix = `put a token for ${expectedAccount} in the ${where} vcs.tokenFile`;
+  return failure(
+    "blocked",
+    `identity_mismatch: the ${resolved.credential === "workspace_token_file" ? "vcs.tokenFile token" : `${bin} login`} is ${login} but ${where} expects ${expectedAccount}`,
+    resolved.credential === "workspace_token_file"
+      ? fileFix
+      : forge.kind === "github"
+        ? `gh auth login --hostname ${forge.apiHost}  # sign in as ${expectedAccount}`
+        : // glab keeps one login per host; switching it would change every repo.
+          `${fileFix} (glab keeps one login per host, so workit never switches it)`,
+  );
+};
+
+/** The forge could not answer at all, as opposed to answering against the account. */
+const unreachable = (result: { code: string; error: string }): boolean =>
+  result.code === "unavailable" && !/ is not authenticated for /u.test(result.error);
+
+/** Total budget for the identity check before a push (B1). */
+export const PUSH_IDENTITY_BUDGET_MS = 5_000;
+
+export type PushIdentity = {
+  /**
+   * verified: the forge says the credential is the workspace account.
+   * no_account: the workspace names no vcs.account, so there is nothing to check.
+   * skipped: the check could not run (forge down, slow, unknown, misconfigured);
+   * git pushes anyway and `reason` says why.
+   */
+  status: "verified" | "no_account" | "skipped";
+  forge: "github" | "gitlab" | null;
+  account: string | null;
+  login: string | null;
+  reason?: string;
+  unblock?: string;
+};
+
+/**
+ * The best-effort identity check before `git push`: git decides the transport,
+ * so a forge that cannot answer (missing, slow, offline, unknown, another
+ * provider) pushes with `status: "skipped"` and the reason (S10, B1). Positive
+ * evidence still blocks: another account, no gh login for the workspace
+ * account, a broken token file or a rejected credential. All calls share one
+ * `budgetMs`; explicit credentials are memoized.
+ */
+export function checkPushIdentity(
+  cwd: string,
+  options: Omit<ResolveOptions, "deadline"> & { budgetMs?: number } = {},
+): ForgeResult<PushIdentity> {
+  let workspace: ReturnType<typeof resolveRuntimeWorkspaceVcs>;
+  try {
+    workspace = resolveRuntimeWorkspaceVcs(cwd);
+  } catch (error) {
     return failure(
       "blocked",
-      `identity_mismatch: the ${resolved.credential === "workspace_token_file" ? "vcs.tokenFile token" : `${bin} login`} is ${identity.data.login} but ${where} expects ${expectedAccount}`,
-      resolved.credential === "workspace_token_file"
-        ? `put a token for ${expectedAccount} in the ${where} vcs.tokenFile`
-        : `${bin} auth login --hostname ${forge.apiHost}  # sign in as ${expectedAccount}`,
+      error instanceof Error ? error.message : String(error),
+      "fix ~/.config/workit/workspaces.json (workit init → Workspaces)",
     );
   }
-  return identity;
+  const account = workspace?.vcs?.account ?? null;
+  const skipped = (forge: PushIdentity["forge"], reason: string, unblock?: string) =>
+    success<PushIdentity>({
+      status: "skipped",
+      forge,
+      account,
+      login: null,
+      reason,
+      ...(unblock ? { unblock } : {}),
+    });
+  const pushed = pushForge(cwd, {
+    branch: options.branch,
+    hosts: configuredHosts(),
+    sshConfig: options.sshConfig,
+  });
+  if (!pushed.ok) {
+    const host = /^unsupported_forge: .*?"([^"]+)"/u.exec(pushed.error)?.[1];
+    const what = /could not resolve ssh alias/u.test(pushed.error)
+      ? `could not resolve ssh alias ${host} to GitHub or GitLab`
+      : pushed.error.startsWith("unsupported_forge: ssh host")
+        ? `ssh host ${host} is not a GitHub/GitLab host or an alias workit can resolve`
+        : `${host} is not a GitHub or GitLab host workit knows`;
+    return skipped(
+      null,
+      host
+        ? `unsupported_forge: ${what}; account checks skipped, pushed with git only (no PR or CI verbs)`
+        : pushed.error,
+      pushed.unblock,
+    );
+  }
+  const derived = pushed.forge;
+  const conflict = forgeConflict(derived, workspace?.vcs?.provider);
+  if (conflict) return skipped(derived.kind, conflict.error, conflict.unblock);
+  if (!account) return success({ status: "no_account", forge: derived.kind, account, login: null });
+
+  const base =
+    options.runner ?? systemRunner(derived.kind, derived.apiHost, options.env ?? process.env);
+  const scope = memoScope(options.runner, options.env ?? process.env);
+  const now = options.now ?? Date.now;
+  const limits = { deadline: now() + (options.budgetMs ?? PUSH_IDENTITY_BUDGET_MS) };
+  const credential = resolveCredential(workspace, derived, clampedRunner(base, limits, now), scope);
+  // A forge that cannot answer (missing CLI, timeout, transport) is skipped;
+  // local evidence against the account (no gh login for it, a broken
+  // vcs.tokenFile, a rejected credential) still blocks: over HTTPS git would
+  // push with whatever account gh's credential helper has active.
+  if (!credential.ok)
+    return unreachable(credential)
+      ? skipped(derived.kind, credential.error, credential.unblock)
+      : credential;
+  const forge = memoizedIdentity(
+    createForge(derived, derived.repo, clampedRunner(base, limits, now, credential.data.token)),
+    scope,
+    credential.data,
+  );
+  const identity = forge.identity(account);
+  if (!identity.ok)
+    return unreachable(identity)
+      ? skipped(derived.kind, identity.error, identity.unblock)
+      : identity;
+  if (identity.data.matches === false)
+    return mismatch(
+      { forge, credential: credential.data.credential, expectedAccount: account },
+      identity.data.login ?? "?",
+      workspace?.name ?? null,
+    );
+  if (identity.data.matches === null)
+    return skipped(derived.kind, identity.data.note ?? "the credential cannot read /user");
+  return success({ status: "verified", forge: derived.kind, account, login: identity.data.login });
 }

package/src/git/ops.ts

@@ -823,6 +823,8 @@ export function executePush(
     setUpstream?: boolean;
     actor: LedgerActor;
     timeoutMs?: number;
+    /** The pre-push identity check's outcome, kept on the ledger row. */
+    identity?: Record<string, unknown>;
   },
 ): ForgeResult<PushOutcome> {
   const before = remoteRefTip(cwd, plan.rawUrl, `refs/heads/${plan.branch}`);
@@ -940,6 +942,7 @@ export function executePush(
     previous: before.sha,
     pushed,
     forced,
+    ...(input.identity ? { identity: input.identity } : {}),
   });
   return success({
     remote: plan.remote,

package/src/git/rev.ts

@@ -879,15 +879,20 @@ export function pushForge(
   const forge = deriveForge(url, options);
   if (!forge) {
     // Never echo the raw URL: it may carry a token (https://user:tok@…).
-    const host = parseRemoteUrl(url)?.host || null;
+    const parsed = parseRemoteUrl(url);
+    const host = parsed?.host || null;
     return {
       ok: false,
       code: "unavailable",
       error: host
-        ? `cannot tell whether push host "${host}" is GitHub or GitLab`
+        ? parsed?.protocol === "ssh" && !host.includes(".")
+          ? `unsupported_forge: could not resolve ssh alias "${host}" to GitHub or GitLab; PR and CI verbs need one (workit git push still pushes with git)`
+          : parsed?.protocol === "ssh"
+            ? `unsupported_forge: ssh host "${host}" is not a GitHub/GitLab host or an alias workit can resolve; PR and CI verbs need one (workit git push still pushes with git)`
+            : `unsupported_forge: cannot tell whether push host "${host}" is GitHub or GitLab; PR and CI verbs need one (workit git push still pushes with git)`
         : `push URL ${redactRemote(url)} of remote "${remote}" is not a GitHub/GitLab URL`,
       unblock: host
-        ? `map the alias in ~/.ssh/config (Host ${host} / HostName github.com|gitlab.com) or set github.host / gitlab.host in ~/.config/workit/vcs.json`
+        ? `if ${host} is an ssh alias of GitHub/GitLab, add "Host ${host}" with "HostName github.com" (or gitlab.com) to ~/.ssh/config; if it is a self-hosted GitHub/GitLab, set github.host or gitlab.host in ~/.config/workit/vcs.json; other forges (Bitbucket, Gitea…) have no PR/CI verbs`
         : `git remote set-url --push ${remote} <ssh-or-https-url>`,
     };
   }
@@ -906,7 +911,7 @@ export function forgeConflict(
   if (!configured || configured === derived.kind) return null;
   return {
     code: "blocked",
-    error: `forge_mismatch: push remote ${derived.host} is ${derived.kind} but the workspace vcs.provider is ${configured}`,
-    unblock: `set vcs.provider to "${derived.kind}" for this repo in ~/.config/workit/workspaces.json (workit-github-override), or push to a ${configured} remote`,
+    error: `forge_mismatch: push remote ${derived.host} is ${derived.kind} but the workspace vcs.provider is ${configured}, so its account and grants do not apply; PR and CI verbs stop here (workit git push still pushes with git)`,
+    unblock: `add a workspace whose glob matches only this repo, with "vcs": {"provider": "${derived.kind}"} (and its account), to ~/.config/workit/workspaces.json; the most specific glob wins`,
   };
 }