@brainervirus/workit-core 8.33.0 → 8.35.0

package/package.json

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

package/src/forge/github.ts

@@ -29,6 +29,8 @@ export const PR_STATUS_QUERY = `query($owner: String!, $name: String!, $number:
 
 export const FIND_PR_QUERY = `query($owner: String!, $name: String!, $head: String!) { repository(owner: $owner, name: $name) { pullRequests(headRefName: $head, first: 20, orderBy: { field: CREATED_AT, direction: DESC }) { nodes { number url state baseRefName headRefName headRefOid headRepositoryOwner { login } } } } }`;
 
+export const BRANCH_CHECKS_QUERY = `query($owner: String!, $name: String!, $ref: String!, $contexts: String) { repository(owner: $owner, name: $name) { object(expression: $ref) { ... on Commit { oid statusCheckRollup { contexts(first: 100, after: $contexts) { pageInfo { hasNextPage endCursor } nodes { __typename ... on CheckRun { name status conclusion detailsUrl databaseId checkSuite { workflowRun { databaseId workflow { name } } } } ... on StatusContext { context state targetUrl } } } } } } } }`;
+
 const READY_MUTATION = `mutation($id: ID!) { markPullRequestReadyForReview(input: { pullRequestId: $id }) { pullRequest { isDraft } } }`;
 const DRAFT_MUTATION = `mutation($id: ID!) { convertPullRequestToDraft(input: { pullRequestId: $id }) { pullRequest { isDraft } } }`;
 const REPLY_MUTATION = `mutation($thread: ID!, $body: String!) { addPullRequestReviewThreadReply(input: { pullRequestReviewThreadId: $thread, body: $body }) { comment { url } } }`;
@@ -113,6 +115,12 @@ type GqlPr = {
   };
 };
 
+type BranchChecksData = {
+  repository: {
+    object: { oid?: string; statusCheckRollup: { contexts: Page<GqlContext> } | null } | null;
+  } | null;
+};
+
 type GqlResponse<T> = { data?: T; errors?: Array<{ message?: string; type?: string }> };
 
 const prState = (value: string): PrState =>
@@ -451,6 +459,36 @@ export function createGitHubForge(options: {
       return success(status);
     },
 
+    branchChecks(branch) {
+      const contexts: GqlContext[] = [];
+      let sha: string | null = null;
+      let cursor: string | null = null;
+      for (let page = 1; page <= maxPages; page += 1) {
+        const data: ForgeResult<BranchChecksData> = graphql<BranchChecksData>(
+          BRANCH_CHECKS_QUERY,
+          { owner, name, ref: `refs/heads/${branch}`, contexts: cursor },
+          `checks on ${branch}`,
+        );
+        if (!data.ok) return data;
+        const commit: NonNullable<BranchChecksData["repository"]>["object"] =
+          data.data.repository?.object ?? null;
+        if (!commit) return failure("not_found", `branch ${branch} was not found`);
+        sha = commit.oid ?? sha;
+        const rollup: { contexts: Page<GqlContext> } | null = commit.statusCheckRollup;
+        if (!rollup) break;
+        contexts.push(...rollup.contexts.nodes);
+        if (!rollup.contexts.pageInfo.hasNextPage) break;
+        cursor = rollup.contexts.pageInfo.endCursor;
+      }
+      const required = requiredContexts(branch);
+      const checks = latestPerName(
+        contexts.map(checkFromContext).filter((check): check is ForgeCheck => check !== null),
+      ).map((check) =>
+        required ? { ...check, required: required.includes(check.context) } : check,
+      );
+      return success({ sha, checks, requiredKnown: required !== null });
+    },
+
     jobLogTail(job, lines) {
       const text = apiText(
         runner,

package/src/forge/gitlab.ts

@@ -465,6 +465,54 @@ export function createGitLabForge(options: {
       return success(status);
     },
 
+    branchChecks(branch) {
+      const tip = baseTip(branch);
+      if (!tip) return failure("not_found", `branch ${branch} was not found`);
+      const latest = apiJson<
+        Array<{ id: number; project_id?: number; status: string; web_url?: string }>
+      >(
+        runner,
+        "glab",
+        apiHost,
+        api(
+          `${project}/pipelines?ref=${encodeURIComponent(branch)}&sha=${tip}&order_by=id&sort=desc&per_page=1`,
+        ),
+        `pipelines on ${branch}`,
+      );
+      if (!latest.ok) return latest;
+      const pipeline = Array.isArray(latest.data) ? latest.data[0] : undefined;
+      if (!pipeline) return success({ sha: tip, checks: [], requiredKnown: true });
+      const scope = String(pipeline.project_id ?? encodeURIComponent(repo));
+      const jobs = pages(
+        `projects/${scope}/pipelines/${pipeline.id}/jobs`,
+        `pipeline ${pipeline.id} jobs`,
+      );
+      if (!jobs.ok) return jobs;
+      const bridges = pages(
+        `projects/${scope}/pipelines/${pipeline.id}/bridges`,
+        `pipeline ${pipeline.id} bridges`,
+      );
+      if (!bridges.ok) return bridges;
+      const checks = [
+        ...(jobs.data.items as GlJob[]).map((job) => checkFromJob(job, pipeline.id, scope)),
+        ...(bridges.data.items as GlBridge[]).map((bridge) =>
+          checkFromBridge(bridge, pipeline.id, scope),
+        ),
+      ];
+      if (
+        stateOf(pipeline.status, false) === "failing" &&
+        !checks.some((check) => check.state === "failing")
+      )
+        checks.push(
+          pipelineCheck("failing", pipeline.status, {
+            id: pipeline.id,
+            project_id: pipeline.project_id ?? 0,
+            web_url: pipeline.web_url,
+          }),
+        );
+      return success({ sha: tip, checks, requiredKnown: true });
+    },
+
     jobLogTail(job, lines) {
       const scope = job.scope ?? encodeURIComponent(repo);
       const text = apiText(

package/src/forge/pr-ops.ts

@@ -46,7 +46,14 @@ import type { LaneNeed, ReviewLane } from "../core/policy/lane";
 import { laneLabel, prLaneGate } from "../core/policy/pr-lane";
 import { buildStatusDoc, selectPr, type PrStatusDoc } from "./report";
 import type { ResolvedForge } from "./resolve";
-import { failure, success, type ForgeResult, type MergeMethod, type PrRef } from "./types";
+import {
+  failure,
+  success,
+  type ForgeCheck,
+  type ForgeResult,
+  type MergeMethod,
+  type PrRef,
+} from "./types";
 
 export type Sleep = (ms: number) => Promise<void>;
 
@@ -358,6 +365,8 @@ export type MergeInput = {
   expect?: { base: string; branch: string };
   /** Merge without a verdict (`merge: true` only); the reason is recorded. */
   unverified?: { reason: string };
+  /** Merge onto a base whose latest CI is red (`--base-red-ok`); the reason is recorded. */
+  baseRedOk?: { reason: string };
   /** Squash commit subject and body (`--subject`, `--body`); unset parts use the defaults. */
   subject?: string;
   body?: string;
@@ -393,6 +402,8 @@ export type MergeOutcome = {
   };
   /** Set when `--unverified` bypassed the verdict: the reason and its ledger row. */
   unverified: { reason: string; recorded: string } | null;
+  /** The base branch's CI at its head: a one-line note when it was not green, and the override used. */
+  baseCi: { note: string | null; override: { reason: string } | null };
   grant: { source: AutonomySource };
   /** `skipped`: the implicit default found a reason to keep the branch; the merge is unaffected. */
   deletedBranch: boolean | { error: string } | { skipped: string };
@@ -454,6 +465,7 @@ export type MergeRefusal = {
     | "closed"
     | "protected_branch"
     | "base_mismatch"
+    | "base_red"
     | "ledger_tampered"
     | "intent_unrecorded";
   next?: string;
@@ -632,6 +644,41 @@ function implicitDeleteSkip(
   return null;
 }
 
+type BaseCi =
+  | { ok: true; note: string | null }
+  | { ok: false; failing: ForgeCheck[]; sha: string | null; requiredKnown: boolean };
+
+/**
+ * The base branch head's CI before a merge lands on it: red (a failing check)
+ * refuses, pending or unreadable proceeds with a note, green or no checks
+ * proceeds quietly. Only a protected target is guarded: a stack's lower
+ * branch is its own PR's business.
+ */
+function baseCiState(cwd: string, resolved: ResolvedForge, base: string): BaseCi {
+  if (!isProtectedTarget(cwd, base)) return { ok: true, note: null };
+  const read = resolved.forge.branchChecks(base);
+  if (!read.ok)
+    return { ok: true, note: `base ${base} CI not read (${read.error}); merging anyway` };
+  // Only checks branch protection requires gate; with the required set
+  // unreadable, count hard failures not known to be optional.
+  const { requiredKnown } = read.data;
+  const failing = read.data.checks.filter(
+    (check) =>
+      check.state === "failing" &&
+      (requiredKnown
+        ? check.required === true
+        : check.required !== false && check.conclusion === "failure"),
+  );
+  if (failing.length) return { ok: false, failing, sha: read.data.sha, requiredKnown };
+  const pending = read.data.checks.filter((check) => check.state === "pending");
+  return {
+    ok: true,
+    note: pending.length
+      ? `base ${base} CI is still running (${pending.map((check) => check.name).join(", ")}); merging without waiting`
+      : null,
+  };
+}
+
 export async function mergePullRequest(
   cwd: string,
   resolved: ResolvedForge,
@@ -650,6 +697,13 @@ export async function mergePullRequest(
       { reason: "unverified_refused" },
     );
 
+  const baseRed = input.baseRedOk ?? null;
+  if (baseRed && !baseRed.reason.trim())
+    return failure(
+      "invalid_input",
+      "--base-red-ok needs --reason <why merging onto a red base is fine>",
+    );
+
   const number = selectPr(cwd, resolved, { pr: input.pr });
   if (!number.ok) return number;
   const status = resolved.forge.prStatus(number.data);
@@ -789,6 +843,20 @@ export async function mergePullRequest(
     );
   }
 
+  const baseCi = baseCiState(cwd, resolved, doc.base);
+  let baseRedOverride: { reason: string } | null = null;
+  if (!baseCi.ok) {
+    const names = baseCi.failing.map((failed) => failed.name).join(", ");
+    const url = baseCi.failing.find((failed) => failed.url)?.url ?? null;
+    if (!baseRed)
+      return refuse(
+        `base_red: ${doc.base} at ${baseCi.sha?.slice(0, 12) ?? "its head"} has failing CI (${names}${baseCi.requiredKnown ? "" : "; the required checks could not be read, so every failed check counts"})${url ? `: ${url}` : ""}; merging ${label} onto it would land on a red base`,
+        `fix ${doc.base} first, or, if the user accepts it: workit pr merge${input.pr ? ` --pr ${doc.number}` : ""} --base-red-ok --reason "<why>"`,
+        { reason: "base_red", blockers: baseCi.failing.map((failed) => failed.name) },
+      );
+    baseRedOverride = baseRed;
+  }
+
   const squashMessage = squashMessageFor(cwd, resolved, input, doc);
   if (squashMessage && !squashMessage.ok) return squashMessage;
   // The intent goes in before the forge write: a merge call that errors after
@@ -806,6 +874,7 @@ export async function mergePullRequest(
     review: verdict.review,
     lane: verdict.lane,
     ...(unverified ? { unverified: unverified.recorded } : {}),
+    ...(baseRedOverride ? { baseRedOk: baseRedOverride.reason } : {}),
     grant: grant.source,
   });
   if (!intent.ok)
@@ -841,6 +910,7 @@ export async function mergePullRequest(
     review: verdict.review,
     lane: verdict.lane,
     ...(unverified ? { unverified: unverified.recorded } : {}),
+    ...(baseRedOverride ? { baseRedOk: baseRedOverride.reason } : {}),
     grant: grant.source,
     intent: intentId,
     verified: false,
@@ -909,6 +979,14 @@ export async function mergePullRequest(
       mergeSha: merged.data.mergeSha,
       verdict,
       unverified,
+      baseCi: {
+        note: baseRedOverride
+          ? `base ${doc.base} CI is red; merged anyway (--base-red-ok: ${baseRedOverride.reason})`
+          : baseCi.ok
+            ? baseCi.note
+            : null,
+        override: baseRedOverride,
+      },
       grant: { source: grant.source },
       deletedBranch,
       recorded,

package/src/forge/types.ts

@@ -110,6 +110,16 @@ export type ForgePrStatus = {
   truncated: boolean;
 };
 
+/** The checks on the latest commit of a branch (the merge guard reads the base's). */
+export type RefChecks = {
+  /** The commit the checks belong to; null when the forge did not say. */
+  sha: string | null;
+  /** `required` is set from branch protection when `requiredKnown`; else it is null on GitHub. */
+  checks: ForgeCheck[];
+  /** True when the branch's required checks could be read (GitLab gates on the whole pipeline). */
+  requiredKnown: boolean;
+};
+
 export type JobRef = { jobId: number; scope: string | null };
 
 export type RerunTarget =
@@ -196,6 +206,8 @@ export interface Forge {
   repoInfo(repo: string): ForgeResult<RepoInfo>;
   findPr(head: string, match: PrMatch): ForgeResult<PrRef | null>;
   prStatus(n: number): ForgeResult<ForgePrStatus>;
+  /** The checks on the head commit of branch `branch`; empty when CI has not reported for it. */
+  branchChecks(branch: string): ForgeResult<RefChecks>;
   jobLogTail(job: JobRef, lines: number): ForgeResult<string[]>;
   rerun(target: RerunTarget): ForgeResult<void>;
   /** Open a PR/MR; `headSha` is the head the forge reports right after creation. */

package/src/hooks/hook-runs.ts

@@ -0,0 +1,96 @@
+// A tiny record of which hook events each host ran (#433): without it "zero
+// hook events" cannot tell a host that never fires its hooks from one that
+// fires them silently. One small file per host and native event in the state
+// dir (`hook-runs/<host>__<event>.json`: last seen time and a count), written
+// best effort: one read and one atomic-enough write, no spawn, and a
+// read-only state dir never changes the hook's answer. `workit doctor`
+// (`hook_runs`) reads it. Light imports only: the Codex launcher's quiet path
+// calls it before the runtime loads.
+import { mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { stateDir } from "../core/heavy-words";
+
+export const HOOK_RUNS_DIR = "hook-runs";
+
+export type HookRun = {
+  host: string;
+  event: string;
+  at: string;
+  count: number;
+};
+
+const safe = (part: string): string => part.replace(/[^A-Za-z0-9_.-]/g, "-").slice(0, 64);
+
+const runFile = (dir: string, host: string, event: string): string =>
+  path.join(dir, HOOK_RUNS_DIR, `${safe(host)}__${safe(event)}.json`);
+
+/** Counts one run of the native `event` on `host`; never throws. */
+export const recordHookRun = (
+  host: string,
+  event: string | null | undefined,
+  env: NodeJS.ProcessEnv = process.env,
+  now: () => number = Date.now,
+): void => {
+  if (!event) return;
+  try {
+    const dir = stateDir(env);
+    const file = runFile(dir, host, event);
+    let count = 0;
+    try {
+      const previous = JSON.parse(readFileSync(file, "utf8")) as {
+        count?: unknown;
+      };
+      if (typeof previous.count === "number" && Number.isFinite(previous.count))
+        count = previous.count;
+    } catch {
+      // First run, or a torn file: start again.
+    }
+    const row: HookRun = {
+      host,
+      event,
+      at: new Date(now()).toISOString(),
+      count: count + 1,
+    };
+    try {
+      writeFileSync(file, JSON.stringify(row));
+    } catch {
+      mkdirSync(path.dirname(file), { recursive: true });
+      writeFileSync(file, JSON.stringify(row));
+    }
+  } catch {
+    // The hook still answers the host; only the doctor line is lost.
+  }
+};
+
+/** Every recorded run under `stateDir`; unreadable or malformed files are skipped. */
+export const readHookRuns = (dir: string): HookRun[] => {
+  const runs: HookRun[] = [];
+  let names: string[] = [];
+  try {
+    names = readdirSync(path.join(dir, HOOK_RUNS_DIR));
+  } catch {
+    return runs;
+  }
+  for (const name of names) {
+    try {
+      const row = JSON.parse(
+        readFileSync(path.join(dir, HOOK_RUNS_DIR, name), "utf8"),
+      ) as Partial<HookRun>;
+      if (
+        typeof row.host === "string" &&
+        typeof row.event === "string" &&
+        typeof row.at === "string" &&
+        typeof row.count === "number"
+      )
+        runs.push({
+          host: row.host,
+          event: row.event,
+          at: row.at,
+          count: row.count,
+        });
+    } catch {
+      // Not a run record.
+    }
+  }
+  return runs;
+};

package/src/hooks/run.ts

@@ -11,6 +11,7 @@ import {
 import { claudeCodeAdapter } from "./hosts/claude-code";
 import { codexAdapter } from "./hosts/codex";
 import { cursorAdapter } from "./hosts/cursor";
+import { recordHookRun } from "./hook-runs";
 import type { HostAdapter, HostId } from "./protocol";
 
 type ProcessHost = Exclude<HostId, "opencode" | "pi">;
@@ -44,6 +45,12 @@ export async function runHookProcess(
   } catch {
     raw = undefined;
   }
+  const native = (raw as { hook_event_name?: unknown } | null | undefined)?.hook_event_name;
+  recordHookRun(
+    typeof host === "string" ? host : adapter.descriptor.host,
+    typeof native === "string" ? native : null,
+    env,
+  );
   const result =
     text === null
       ? skippedHook(adapter, undefined, env, budget, "input")