@brainervirus/workit-core 8.31.0 → 8.32.0

package/package.json

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

package/src/core/policy/carry.ts

@@ -17,7 +17,8 @@
 import { mergeBase, fileAt } from "../../git/rev";
 import { computeLane, driftFiles, kindOf, parseRiskPaths, RISK_PATHS_FILE } from "./lane";
 
-export type CarryRule = "lane-none" | "tests-only";
+/** `rebase`: the same patch on a moved base (ledger.ts exact carry), never a drift rule. */
+export type CarryRule = "lane-none" | "tests-only" | "rebase";
 
 export type Drift =
   | { carries: true; rule: CarryRule; since: string; files: string[] }

package/src/core/workspaces.ts

@@ -156,6 +156,13 @@ const workspaceConfigSchema = z
      * authorship lives in the ledger only (`commit.recorded`).
      */
     trailers: z.boolean().optional(),
+    /**
+     * Whether `workit pr merge` deletes the head branch after a merge (default
+     * true); `--keep-branch` opts out for one merge. Skipped, never refused,
+     * for a protected or base branch, a fork, a stack parent and a foreign
+     * author (forge/pr-ops.ts).
+     */
+    deleteBranch: z.boolean().optional(),
     /**
      * Whether the live-session guard denies edits in a checkout another live
      * agent session owns (default true; core/live-session.ts).
@@ -842,6 +849,11 @@ const inheritedSetting = (
   return { workspace: selected.name, source: [selected, ...enclosing].find(has) ?? null };
 };
 
+/** Whether `pr merge` deletes the head branch by default: true unless a covering entry sets `deleteBranch: false`. */
+export const workspaceDeleteBranch = (cwd: string, dir?: string): boolean =>
+  inheritedSetting(cwd, dir, (entry) => typeof entry.deleteBranch === "boolean")?.source
+    ?.deleteBranch !== false;
+
 /**
  * Whether commits in cwd's workspace carry the `Workit-Session:` trailer.
  * The selected workspace's own `trailers` wins; unset, it inherits from the

package/src/forge/github.ts

@@ -44,8 +44,9 @@ type RestPr = {
   merged?: boolean;
   draft?: boolean;
   title?: string;
-  base?: { ref?: string };
-  head?: { ref?: string };
+  base?: { ref?: string; repo?: { full_name?: string } | null };
+  head?: { ref?: string; repo?: { full_name?: string } | null };
+  user?: { login?: string } | null;
 };
 
 type Page<T> = { pageInfo: { hasNextPage: boolean; endCursor: string | null }; nodes: T[] };
@@ -587,10 +588,27 @@ export function createGitHubForge(options: {
         title: value.title ?? "",
         base: value.base?.ref ?? "",
         headBranch: value.head?.ref ?? "",
+        author: value.user?.login ?? null,
+        // A deleted fork has no head repo: not ours, so a fork.
+        fork:
+          value.base?.repo?.full_name === undefined
+            ? null
+            : value.head?.repo?.full_name?.toLowerCase() !==
+              value.base.repo.full_name.toLowerCase(),
       };
       return success(meta);
     },
 
+    openPrsInto(branch) {
+      const list = rest<Array<{ number?: number }>>(
+        `repos/${repo}/pulls?state=open&base=${encodeURIComponent(branch)}&per_page=100`,
+        `open pull requests into ${branch}`,
+      );
+      if (!list.ok) return list;
+      if (!Array.isArray(list.data)) return failure("failed", "pull request list is not a list");
+      return success(list.data.flatMap((pr) => (typeof pr.number === "number" ? [pr.number] : [])));
+    },
+
     setDraft(number, draft) {
       const pr = restPr(number);
       if (!pr.ok) return pr;

package/src/forge/gitlab.ts

@@ -36,6 +36,8 @@ type GlMr = {
   sha: string;
   diff_refs?: { base_sha?: string | null } | null;
   source_project_id?: number;
+  target_project_id?: number;
+  author?: { username?: string } | null;
   head_pipeline?: {
     id: number;
     sha: string;
@@ -626,10 +628,30 @@ export function createGitLabForge(options: {
         title: value.title ?? "",
         base: value.target_branch,
         headBranch: value.source_branch,
+        author: value.author?.username ?? null,
+        fork:
+          value.source_project_id === undefined || value.target_project_id === undefined
+            ? null
+            : value.source_project_id !== value.target_project_id,
       };
       return success(meta);
     },
 
+    openPrsInto(branch) {
+      const list = apiJson<GlMr[]>(
+        runner,
+        "glab",
+        apiHost,
+        api(
+          `${project}/merge_requests?state=opened&target_branch=${encodeURIComponent(branch)}&per_page=100`,
+        ),
+        `open merge requests into ${branch}`,
+      );
+      if (!list.ok) return list;
+      if (!Array.isArray(list.data)) return failure("failed", "merge request list is not a list");
+      return success(list.data.map((mr) => mr.iid));
+    },
+
     setDraft(iid, draft) {
       const mr = getMr(iid);
       if (!mr.ok) return mr;

package/src/forge/merge-cleanup.ts

@@ -0,0 +1,100 @@
+// After `workit pr merge` deleted the remote head branch (#384): the local
+// branch and the slice's clean fanout worktree go too. Never forced.
+import fs from "node:fs";
+import path from "node:path";
+import { gitRun, nulList } from "../fanout";
+import { SCRATCH_DIR, listWorktrees } from "../fanout-worktree";
+import { GIT_TIMEOUTS } from "../git/rev";
+import { FANOUT_TOKEN_FILE } from "../hooks/worktree-confine";
+
+const SLOW = GIT_TIMEOUTS.worktree;
+
+/** `workit fanout worktree create` marked this worktree's admin dir with its token. */
+const isFanoutWorktree = (worktree: string): boolean => {
+  const dir = gitRun(worktree, ["rev-parse", "--absolute-git-dir"]);
+  if (!dir.ok) return false;
+  try {
+    return fs.readFileSync(path.join(dir.stdout.trim(), FANOUT_TOKEN_FILE), "utf8").trim() !== "";
+  } catch {
+    return false;
+  }
+};
+
+const inside = (child: string, parent: string): boolean => {
+  const relative = path.relative(fs.realpathSync.native(parent), fs.realpathSync.native(child));
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+};
+
+export type LocalCleanup = {
+  /** The local branch was deleted. */
+  branchDeleted: boolean;
+  /** The Workit fanout worktree that was on the branch and clean, removed. */
+  worktreeRemoved: string | null;
+  /** Why anything was kept: one line each. */
+  notes: string[];
+};
+
+/**
+ * After `pr merge` deleted the remote head branch: delete the local branch
+ * when it is not checked out anywhere, and first remove a clean worktree that
+ * `workit fanout worktree create` made on it. Never forced: a dirty worktree,
+ * one someone else made, the main checkout, the one this command runs in, or
+ * a local branch with commits beyond the merged head are kept and named.
+ */
+export function cleanupMergedBranch(cwd: string, branch: string, mergedHead: string): LocalCleanup {
+  const out: LocalCleanup = { branchDeleted: false, worktreeRemoved: null, notes: [] };
+  if (!branch || branch.startsWith("-")) return out;
+  const ref = `refs/heads/${branch}`;
+  const tip = gitRun(cwd, ["rev-parse", "--verify", "--quiet", ref]);
+  if (!tip.ok) return out;
+  if (
+    tip.stdout.trim() !== mergedHead &&
+    !gitRun(cwd, ["merge-base", "--is-ancestor", tip.stdout.trim(), mergedHead]).ok
+  ) {
+    out.notes.push(`local ${branch} has commits that were not merged; kept it`);
+    return out;
+  }
+  const trees = listWorktrees(cwd);
+  for (const [index, entry] of trees.entries()) {
+    if (entry.branch !== ref) continue;
+    if (index === 0 || inside(cwd, entry.path)) {
+      out.notes.push(`local ${branch} is checked out in ${entry.path}; kept it`);
+      return out;
+    }
+    if (!isFanoutWorktree(entry.path)) {
+      out.notes.push(
+        `local ${branch} is checked out in ${entry.path}, not a Workit fanout worktree; kept both`,
+      );
+      return out;
+    }
+    const status = gitRun(entry.path, [
+      "status",
+      "--porcelain=v1",
+      "-z",
+      "--untracked-files=all",
+      "--ignore-submodules=none",
+    ]);
+    const dirty = status.ok
+      ? nulList(status.stdout).filter((line) => !line.slice(3).startsWith(`${SCRATCH_DIR}/`))
+      : ["unreadable"];
+    if (dirty.length > 0) {
+      out.notes.push(
+        `worktree ${entry.path} has ${dirty.length === 1 && dirty[0] === "unreadable" ? "an unreadable state" : `${dirty.length} uncommitted change${dirty.length === 1 ? "" : "s"}`}; kept it and local ${branch}`,
+      );
+      return out;
+    }
+    const removed = gitRun(cwd, ["worktree", "remove", entry.path], SLOW);
+    if (!removed.ok) {
+      out.notes.push(
+        `could not remove worktree ${entry.path} (${removed.stderr.trim().split("\n")[0]}); kept local ${branch}`,
+      );
+      return out;
+    }
+    out.worktreeRemoved = entry.path;
+  }
+  if (listWorktrees(cwd).some((entry) => entry.branch === ref)) return out;
+  const deleted = gitRun(cwd, ["branch", "-D", "--", branch]);
+  if (deleted.ok) out.branchDeleted = true;
+  else out.notes.push(`could not delete local ${branch}: ${deleted.stderr.trim().split("\n")[0]}`);
+  return out;
+}

package/src/forge/pr-ops.ts

@@ -343,7 +343,13 @@ export async function createPullRequest(
 export type MergeInput = {
   pr: number | null;
   method: MergeMethod;
+  /** `--delete-branch`: delete, refusing a protected branch before the merge. */
   deleteBranch: boolean;
+  /**
+   * The workspace default (`deleteBranch`, no `--keep-branch`): delete when it
+   * is safe, otherwise skip with a note; never refuses the merge.
+   */
+  implicitDelete?: boolean;
   actor: LedgerActor;
   /**
    * Stack landing (S12): refuse unless the PR still targets this base and
@@ -388,7 +394,8 @@ export type MergeOutcome = {
   /** Set when `--unverified` bypassed the verdict: the reason and its ledger row. */
   unverified: { reason: string; recorded: string } | null;
   grant: { source: AutonomySource };
-  deletedBranch: boolean | { error: string };
+  /** `skipped`: the implicit default found a reason to keep the branch; the merge is unaffected. */
+  deletedBranch: boolean | { error: string } | { skipped: string };
   recorded: { id: string } | { error: string };
   /** The `pr.merge.verified` row confirming `recorded`, or why it was not written. */
   confirmed: { id: string } | { error: string };
@@ -590,6 +597,41 @@ function squashCommitList(
   );
 }
 
+/**
+ * Why the implicit delete keeps `branch`, or null when it is safe to delete:
+ * a protected, base or default-target branch, a fork's branch, a branch another
+ * open PR targets (a stack child), and a PR by someone other than the
+ * workspace's `vcs.account`. What cannot be read keeps the branch too.
+ */
+function implicitDeleteSkip(
+  cwd: string,
+  resolved: ResolvedForge,
+  doc: PrStatusDoc,
+  branch: string,
+): string | null {
+  const resolvedVcs = vcsConfig("resolve", cwd);
+  const defaultTarget =
+    resolvedVcs.ok === false ? null : String(resolvedVcs.defaultTargetBranch ?? "") || null;
+  const account = resolved.expectedAccount?.trim() ?? "";
+  const lower = branch.toLowerCase();
+  if (isProtectedTarget(cwd, branch))
+    return `${branch} is protected by the workspace branch policy`;
+  if (lower === doc.base.toLowerCase()) return `${branch} is the PR base`;
+  if (defaultTarget !== null && lower === defaultTarget.toLowerCase())
+    return `${branch} is the default target branch`;
+  if (doc.headRepo !== null) return `${branch} is a fork's branch (${doc.headRepo})`;
+  const meta = resolved.forge.prMeta(doc.number);
+  if (!meta.ok) return `could not read the PR author and head repository (${meta.error})`;
+  if (meta.data.fork !== false) return `${branch} is not known to be in ${resolved.forge.repo}`;
+  if (account && (meta.data.author ?? "").toLowerCase() !== account.toLowerCase())
+    return `the PR is by ${meta.data.author ?? "an unknown author"}, not ${account} (vcs.account)`;
+  const children = resolved.forge.openPrsInto(branch);
+  if (!children.ok) return `could not list the open PRs into ${branch} (${children.error})`;
+  if (children.data.length)
+    return `open PR ${children.data.map((n) => `#${n}`).join(", ")} targets ${branch} (a stack)`;
+  return null;
+}
+
 export async function mergePullRequest(
   cwd: string,
   resolved: ResolvedForge,
@@ -841,7 +883,13 @@ export async function mergePullRequest(
         : { error: confirmation.error };
 
   let deletedBranch: MergeOutcome["deletedBranch"] = false;
-  if (input.deleteBranch) {
+  const skipReason =
+    !input.deleteBranch && input.implicitDelete
+      ? implicitDeleteSkip(cwd, resolved, doc, branch)
+      : null;
+  if (!input.deleteBranch && input.implicitDelete && skipReason !== null)
+    deletedBranch = { skipped: skipReason };
+  else if (input.deleteBranch || input.implicitDelete) {
     const deleted = deleteRemoteBranch(cwd, resolved.remote, branch, head);
     // The forge may delete merged branches itself; gone is deleted.
     const gone = !deleted.ok && remoteRefTip(cwd, resolved.remote, `refs/heads/${branch}`);

package/src/forge/types.ts

@@ -161,6 +161,10 @@ export type PrMeta = {
   title: string;
   base: string;
   headBranch: string;
+  /** The author's login; null when the forge does not say. */
+  author: string | null;
+  /** The head comes from another repository than the PR's; null when unknown. */
+  fork: boolean | null;
 };
 
 /** What `workit pr edit` changes; unset fields are left alone. */
@@ -205,6 +209,8 @@ export interface Forge {
   updateBase(n: number, base: string): ForgeResult<void>;
   /** Title, draft flag, base and state of one PR/MR. */
   prMeta(n: number): ForgeResult<PrMeta>;
+  /** Numbers of the open PRs/MRs that target `branch` as their base (stack children). */
+  openPrsInto(branch: string): ForgeResult<number[]>;
   /** Mark a draft ready (`draft: false`) or convert it back to a draft. */
   setDraft(n: number, draft: boolean): ForgeResult<void>;
   editPr(n: number, edit: PrEdit): ForgeResult<void>;

package/src/ledger.ts

@@ -33,7 +33,8 @@
 //   `base`, the stable patch-id of `base...head` and an exact diff hash. It is
 //   `fresh` (same head; verdicts on a dirty worktree are refused, so the head
 //   is the judged tree), `carried` (new head, same patch-id AND same exact
-//   diff AND, for a pass, byte-identical own files the base left alone: a
+//   diff AND, for a pass, byte-identical own files the base left alone, or
+//   a head that is exactly the judged head cleanly rebased (cleanRebase): a
 //   rebase that only moved the base; or a trusted verdict whose
 //   follow-up change is lane none, or test-only for a unit verdict, see
 //   core/policy/carry.ts) or `stale`.
@@ -338,6 +339,32 @@ export function diffHash(cwd: string, base: string, head: string): string | null
   return `sha256:${hash.digest("hex")}`;
 }
 
+/**
+ * Whether `to` (on `toBase`) is exactly the judged `from` (on `fromBase`)
+ * rebased cleanly onto the moved base: a 3-way merge of `from` onto
+ * `merge-base(toBase, to)` with `merge-base(fromBase, from)` as the ancestor
+ * has no conflict and yields `to`'s tree. Hunks are anchored to the
+ * ancestor, so an edit moved elsewhere in a file, a conflict resolved by
+ * hand, or any other change in the branch's files makes the trees differ.
+ * False when git cannot tell (no `merge-tree --merge-base`, before 2.40).
+ */
+function cleanRebase(
+  cwd: string,
+  range: { from: string; to: string; fromBase: string; toBase: string },
+): boolean {
+  if (!Object.values(range).every(safeRef)) return false;
+  const fromFork = git(cwd, ["merge-base", range.fromBase, range.from]);
+  const toFork = git(cwd, ["merge-base", range.toBase, range.to]);
+  if (!fromFork || !toFork || fromFork === toFork) return false;
+  const merged = gitRun(
+    cwd,
+    ["merge-tree", "--write-tree", "--no-messages", `--merge-base=${fromFork}`, toFork, range.from],
+    GIT_TIMEOUTS.worktree,
+  );
+  const tree = merged.ok ? merged.stdout.split("\n")[0]?.trim() : null;
+  return Boolean(tree) && tree === git(cwd, ["rev-parse", "--verify", "-q", `${range.to}^{tree}`]);
+}
+
 // ---------------------------------------------------------------------------
 // store root (D13)
 
@@ -1124,7 +1151,9 @@ export type Reverify = { scope: "focused"; since: string; files: string[] };
 
 /** `carried (lane none since <head>)`: how a carried verdict reads in `ledger check` and `pr status`. */
 export const carryLabel = (carry: CarryNote): string =>
-  `carried (${carry.rule === "lane-none" ? "lane none" : "tests only"} since ${carry.since.slice(0, 12)})`;
+  carry.rule === "rebase"
+    ? "carried (rebase: patch unchanged)"
+    : `carried (${carry.rule === "lane-none" ? "lane none" : "tests only"} since ${carry.since.slice(0, 12)})`;
 
 export type VerdictCheck = {
   branch: string;
@@ -1516,31 +1545,49 @@ export function checkVerdicts(
   };
   // The same patch-id and diff hash are not enough to carry a pass (#334):
   // both drop hunk line numbers, so an edit moved within a file keeps them.
-  // The branch's own files must be identical blobs too (sameOwnChange). A
-  // failure keeps the looser carry: it fails closed by applying more.
-  const exactCache = new Map<ReadRow, boolean>();
-  const exactCarry = (row: ReadRow): boolean => {
-    if (FAILING.has(String(row.result))) return true;
+  // The branch's own files must be identical blobs too (sameOwnChange), or
+  // the head must be exactly the judged head cleanly rebased onto the moved
+  // base (cleanRebase): a base edit elsewhere in a file the branch touches.
+  // A failure keeps the looser carry: it fails closed by applying more.
+  // How a pass's own files match: identical blobs, a clean rebase, or neither.
+  const exactCache = new Map<ReadRow, "same" | "rebase" | null>();
+  const exactMatch = (row: ReadRow): "same" | "rebase" | null => {
     let exact = exactCache.get(row);
     if (exact === undefined) {
       const toBase = row.base ?? fallbackBase;
       const toBaseSha = toBase ? resolveCommit(cwd, toBase) : null;
       const fromBase = row.baseSha ?? toBaseSha;
-      exact = Boolean(
-        row.head &&
-        head &&
-        toBaseSha &&
-        fromBase &&
-        sameOwnChange(cwd, { from: row.head, to: head, fromBase, toBase: toBaseSha }),
-      );
+      const range =
+        row.head && head && toBaseSha && fromBase
+          ? { from: row.head, to: head, fromBase, toBase: toBaseSha }
+          : null;
+      exact = !range
+        ? null
+        : sameOwnChange(cwd, range)
+          ? "same"
+          : cleanRebase(cwd, range)
+            ? "rebase"
+            : null;
       exactCache.set(row, exact);
     }
     return exact;
   };
+  const exactCarry = (row: ReadRow): boolean =>
+    FAILING.has(String(row.result)) || exactMatch(row) !== null;
   const keyBasis = (row: ReadRow): Exclude<VerdictBasis, "none"> => {
     const basis = verdictBasis(row, { head, ...keyFor(row.base ?? fallbackBase) });
     return basis === "carried" && !exactCarry(row) ? "stale" : basis;
   };
+  /** A pass the exact keys carry only through a clean rebase (the base also edited a branch file). */
+  const rebaseNote = (row: ReadRow): CarryNote | null =>
+    row.head &&
+    head &&
+    row.head !== head &&
+    !FAILING.has(String(row.result)) &&
+    keyBasis(row) === "carried" &&
+    exactMatch(row) === "rebase"
+      ? { rule: "rebase", since: row.head, files: [] }
+      : null;
   const restacked = (row: ReadRow): boolean =>
     restackCarries(FAILING.has(String(row.result)) ? null : cwd, rows, branch, row.head, head);
   /** The follow-up carry of a verdict the exact keys and restacks do not carry. */
@@ -1646,7 +1693,7 @@ export function checkVerdicts(
       independent: independence.length === 0,
       accepted: reasons.length === 0,
       reasons,
-      carry: basis === "carried" ? carryOf(row) : null,
+      carry: basis === "carried" ? (rebaseNote(row) ?? carryOf(row)) : null,
       verdict: row,
     });
     // The author's own failure never displaces an independent pass, but it