@brainervirus/workit-core 8.0.1 → 8.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-core",
-  "version": "8.0.1",
+  "version": "8.1.0",
   "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

@@ -14,6 +14,7 @@ import {
   type ToolkitConfig,
 } from "./config";
 import type { CommitFlavorPreset } from "./commit-flavors";
+import { repoBranchPreset } from "./branch-policy";
 
 export type VcsProvider = "gitlab" | "github";
 
@@ -731,6 +732,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 +748,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 +795,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/git/ops.ts

@@ -18,6 +18,8 @@
 //   the tip workit last recorded, and success only when the remote tip
 //   observed afterwards equals the local SHA (`push.verified` row).
 import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
 import {
   classifyBranchDirt,
   isProtectedTarget,
@@ -51,12 +53,17 @@ import {
 const COMMIT_TIMEOUT_MS = 10 * 60_000;
 const PUSH_TIMEOUT_MS = 120_000;
 
-type Run = { ok: boolean; status: number | null; stdout: string; stderr: string };
+type Run = {
+  ok: boolean;
+  status: number | null;
+  stdout: string;
+  stderr: string;
+};
 
 const git = (
   cwd: string,
   args: string[],
-  options: { timeoutMs?: number; env?: NodeJS.ProcessEnv } = {},
+  options: { timeoutMs?: number; env?: NodeJS.ProcessEnv; input?: string } = {},
 ): Run => {
   const result = spawnSync("git", args, {
     cwd,
@@ -66,7 +73,9 @@ const git = (
     timeout: options.timeoutMs ?? GIT_TIMEOUTS.local,
     killSignal: "SIGKILL",
     windowsHide: true,
-    stdio: ["ignore", "pipe", "pipe"],
+    ...(options.input === undefined
+      ? { stdio: ["ignore", "pipe", "pipe"] as const }
+      : { input: options.input, stdio: ["pipe", "pipe", "pipe"] as const }),
   });
   return {
     ok: result.status === 0,
@@ -85,6 +94,96 @@ const gitError = (run: { stderr: string; stdout?: string }, max = 3): string =>
   return lines.slice(-max).join(" / ").slice(0, 400) || "git failed";
 };
 
+/** Past this many lines, hook output keeps its head and tail. */
+const OUTPUT_LINES = 200;
+/** A longer output line (a minified bundle, a JSON blob) is cut here. */
+const OUTPUT_LINE_CHARS = 1000;
+
+/**
+ * Everything git and its hooks printed, redacted and without `hint:` lines, so
+ * a failing lint hook's errors reach the agent. Long output keeps the first
+ * and last OUTPUT_LINES / 2 lines.
+ */
+const gitOutput = (run: { stderr: string; stdout?: string }): string => {
+  const lines = redactText(`${run.stderr}\n${run.stdout ?? ""}`)
+    .split(/\r?\n/u)
+    .map((value) => value.trimEnd())
+    .filter((value) => value.trim() && !value.trimStart().startsWith("hint:"))
+    .map((value) =>
+      value.length > OUTPUT_LINE_CHARS ? `${value.slice(0, OUTPUT_LINE_CHARS)}…` : value,
+    );
+  if (!lines.length) return "git failed";
+  if (lines.length <= OUTPUT_LINES) return lines.join("\n");
+  const half = OUTPUT_LINES / 2;
+  return [
+    ...lines.slice(0, half),
+    `… ${lines.length - OUTPUT_LINES} lines omitted …`,
+    ...lines.slice(-half),
+  ].join("\n");
+};
+
+type Operation = "rebase" | "am" | "merge" | "cherry-pick" | "revert";
+
+type InProgress = {
+  operation: Operation;
+  /**
+   * A commit is the legitimate next step: an interactive rebase stopped at an
+   * `edit`, or a revert or merge without conflicts (`--no-commit`).
+   */
+  commitAllowed: boolean;
+  /** The branch being rebased (HEAD is detached meanwhile). */
+  branch: string | null;
+};
+
+/** The multi-step git operation the checkout is in the middle of, if any. */
+function operationInProgress(cwd: string): InProgress | null {
+  const markers: [string, Operation][] = [
+    ["rebase-merge", "rebase"],
+    ["rebase-apply", "rebase"],
+    ["MERGE_HEAD", "merge"],
+    ["CHERRY_PICK_HEAD", "cherry-pick"],
+    ["REVERT_HEAD", "revert"],
+  ];
+  const run = git(cwd, ["rev-parse", ...markers.flatMap(([name]) => ["--git-path", name])]);
+  if (!run.ok) return null;
+  const found = run.stdout.split("\n").map((line) => path.resolve(cwd, line.trim()));
+  const conflicted = () => git(cwd, ["ls-files", "-u"]).stdout.trim() !== "";
+  for (const [index, [, operation]] of markers.entries()) {
+    const marker = found[index];
+    if (!marker || !existsSync(marker)) continue;
+    // `git am` also uses rebase-apply; its `applying` file tells them apart.
+    if (index === 1 && existsSync(path.join(marker, "applying")))
+      return { operation: "am", commitAllowed: false, branch: null };
+    // An `edit` stop leaves rebase-merge/amend; the rebased branch is head-name.
+    if (index === 0 && existsSync(path.join(marker, "amend")) && !conflicted()) {
+      let headName = "";
+      try {
+        headName = readFileSync(path.join(marker, "head-name"), "utf8").trim();
+      } catch {
+        // No head-name: a rebase of a detached HEAD; there is no branch to commit for.
+      }
+      const branch = headName.startsWith("refs/heads/")
+        ? headName.slice("refs/heads/".length)
+        : null;
+      return { operation, commitAllowed: branch !== null, branch };
+    }
+    if ((operation === "revert" || operation === "merge") && !conflicted())
+      return { operation, commitAllowed: true, branch: null };
+    return { operation, commitAllowed: false, branch: null };
+  }
+  return null;
+}
+
+/** A refusal that names the operation in progress and how to finish or leave it. */
+function inProgressFailure<T>(operation: Operation, verb: string): ForgeResult<T> {
+  const command = operation === "am" ? "git am" : `git ${operation}`;
+  return failure(
+    "blocked",
+    `${operation.replace("-", "_")}_in_progress: a ${operation === "am" ? "git am" : operation} is in progress; finish or abort it before workit can ${verb}`,
+    `resolve the conflicts, git add <files>, then ${command} --continue  # or ${command} --abort to return to where you started`,
+  );
+}
+
 const validRefName = (cwd: string, name: string): boolean =>
   !name.startsWith("-") && git(cwd, ["check-ref-format", "--branch", name]).ok;
 
@@ -138,6 +237,8 @@ export type BranchInput = {
 export function gitBranch(cwd: string, input: BranchInput): ForgeResult<BranchOutcome> {
   if (!headSha(cwd) && currentBranch(cwd) === null)
     return failure("invalid_input", "not inside a git repository with a commit");
+  const progress = operationInProgress(cwd);
+  if (progress) return inProgressFailure(progress.operation, "create a branch");
   // One resolution: the default target, the base for new branches and the
   // release track (core/release-tracks.ts) all come from vcsConfig. With
   // --base the track is the base's line (it decides the --kind naming);
@@ -264,6 +365,10 @@ export type CommitOutcome = {
   /** Changes left uncommitted (not selected). */
   leftDirty: number;
   session: string | null;
+  /** With --amend: the commit this one replaced. */
+  amended: string | null;
+  /** Follow-ups the agent should know (an amended commit that was already pushed). */
+  notes: string[];
   /** The ledger row id, or why it could not be written (the commit stands). */
   recorded: { id: string } | { error: string };
 };
@@ -296,21 +401,109 @@ export function lintCommitMessage(
 
 const SESSION_SAFE = /^[\w.:@/+-]{1,128}$/u;
 
+// Fixed trailer syntax, whatever the user's trailer.* config says.
+const TRAILER_CONFIG = ["-c", "trailer.separators=:", "-c", "trailer.where=end"];
+
+/** The trailers (`Key: value`) of a commit message. */
+function messageTrailers(cwd: string, message: string): string[] {
+  const run = git(cwd, [...TRAILER_CONFIG, "interpret-trailers", "--parse", "--no-divider"], {
+    input: `${message}\n`,
+  });
+  return run.ok ? run.stdout.split("\n").filter((line) => line.trim()) : [];
+}
+
+/**
+ * The message with `trailers` appended, keeping every existing trailer and
+ * never repeating an identical one (an amend of a commit this session already
+ * made). `--no-divider`: a `---` line in the body is text, not a patch start.
+ */
+function withTrailers(cwd: string, message: string, trailers: readonly string[]): string {
+  if (!trailers.length) return message;
+  const run = git(
+    cwd,
+    [
+      ...TRAILER_CONFIG,
+      "interpret-trailers",
+      "--no-divider",
+      "--if-exists",
+      "addIfDifferent",
+      ...trailers.flatMap((trailer) => ["--trailer", trailer]),
+    ],
+    { input: `${message}\n` },
+  );
+  return run.ok ? run.stdout.trim() : `${message}\n\n${trailers.join("\n")}`;
+}
+
+/** Short names (`main`, `develop`) of the refs that contain `sha`, local or remote. */
+function branchesContaining(cwd: string, sha: string): Set<string> {
+  const run = git(cwd, [
+    "for-each-ref",
+    "--format=%(refname)",
+    "--contains",
+    sha,
+    "refs/heads",
+    "refs/remotes",
+  ]);
+  const names = new Set<string>();
+  for (const ref of run.ok ? run.stdout.split("\n") : []) {
+    if (ref.startsWith("refs/heads/")) names.add(ref.slice("refs/heads/".length));
+    else if (ref.startsWith("refs/remotes/")) {
+      const name = ref.split("/").slice(3).join("/");
+      if (name && name !== "HEAD") names.add(name);
+    }
+  }
+  return names;
+}
+
+/**
+ * The shared branch (protected, or the default target or base) that already
+ * contains `sha`: amending it would rewrite a commit that is not this
+ * branch's own. Null when `sha` is the branch's own.
+ */
+function sharedBranchContaining(cwd: string, sha: string, branch: string): string | null {
+  const resolved = vcsConfig("resolve", cwd);
+  const defaults = new Set(
+    resolved.ok === false
+      ? []
+      : [resolved.defaultTargetBranch, resolved.baseBranch]
+          .map((value) => String(value ?? ""))
+          .filter(Boolean),
+  );
+  for (const name of branchesContaining(cwd, sha))
+    if (name !== branch && (defaults.has(name) || isProtectedTarget(cwd, name))) return name;
+  return null;
+}
+
+const nothingToCommit = (what: string) =>
+  failure<CommitOutcome>(
+    "failed",
+    `nothing_to_commit: ${what}`,
+    "workit git commit --allow-empty -m '<msg>'  # only to record an empty commit on purpose",
+  );
+
 export function gitCommit(
   cwd: string,
   input: {
-    message: string;
+    /** The new message; with `amend` and no message the amended commit's is kept. */
+    message?: string | null;
     all?: boolean;
     paths?: readonly string[];
+    /** Replace the branch's last commit (`git commit --amend`). */
+    amend?: boolean;
+    /** Record a commit even when it changes no file. */
+    allowEmpty?: boolean;
     actor: LedgerActor;
     env?: NodeJS.ProcessEnv;
   },
 ): ForgeResult<CommitOutcome> {
-  const message = input.message.trim();
-  if (!message) return failure("invalid_input", "a commit message is required (-m <msg>)");
+  const given = input.message?.trim() ?? "";
+  if (!given && !input.amend)
+    return failure("invalid_input", "a commit message is required (-m <msg> or -F <file>)");
   const paths = input.paths ?? [];
   if (input.all && paths.length) return failure("invalid_input", "pass --all or paths, not both");
-  const branch = currentBranch(cwd);
+  const progress = operationInProgress(cwd);
+  if (progress && !progress.commitAllowed) return inProgressFailure(progress.operation, "commit");
+  const branch = progress?.branch ?? currentBranch(cwd);
   if (!branch)
     return failure(
       "invalid_input",
@@ -322,52 +515,120 @@ export function gitCommit(
       `protected_branch: ${branch} is protected by the workspace branch policy; workit never commits to it`,
       "workit git branch <feature/name>  # then commit there",
     );
-  const lint = lintCommitMessage(cwd, message);
-  if (!lint.ok) return failure("blocked", lint.error, lint.correction);
+  const previous = input.amend ? headSha(cwd) : null;
+  if (input.amend && !previous)
+    return failure("invalid_input", `nothing to amend: ${branch} has no commit yet`);
+  if (previous) {
+    const shared = sharedBranchContaining(cwd, previous, branch);
+    if (shared)
+      return failure(
+        "blocked",
+        `amend_shared_commit: ${previous.slice(0, 12)} is already on ${shared}, so it is not ${branch}'s own commit; workit never rewrites it`,
+        "workit git commit -m '<msg>' -- <paths>  # add a new commit instead",
+      );
+  }
+  let message = given;
+  let carried: string[] = [];
+  if (given) {
+    const lint = lintCommitMessage(cwd, given);
+    if (!lint.ok) return failure("blocked", lint.error, lint.correction);
+  }
+  if (previous) {
+    const kept = git(cwd, ["log", "-1", "--format=%B", previous]);
+    if (!kept.ok)
+      return failure("failed", `could not read the message of ${branch}: ${gitError(kept)}`);
+    // --no-edit keeps the message whole; a new message carries the old trailers over.
+    if (given) carried = messageTrailers(cwd, kept.stdout.trim());
+    else message = kept.stdout.trim();
+  }
   const session = input.actor.session;
   if (session && !SESSION_SAFE.test(session))
     return failure(
       "invalid_input",
       "WORKIT_SESSION_ID must be 1-128 characters of [A-Za-z0-9_.:@/+-]",
     );
+  // A commit that only rewords (amend) or is empty on purpose needs no change.
+  const changeRequired = !input.amend && !input.allowEmpty;
 
-  const args = ["commit", "--no-edit", "-m", message];
-  if (session) args.push("--trailer", `Workit-Session: ${session}`);
+  // Amending an empty commit (a CI retrigger) keeps it empty without --allow-empty.
+  const emptyAmend =
+    previous !== null &&
+    git(cwd, ["rev-parse", "--verify", "-q", `${previous}^{tree}`]).stdout.trim() ===
+      git(cwd, ["rev-parse", "--verify", "-q", `${previous}~1^{tree}`]).stdout.trim();
+  const args = ["commit", "--no-edit"];
+  if (input.amend) args.push("--amend");
+  if (input.allowEmpty || emptyAmend) args.push("--allow-empty");
+  args.push(
+    "-m",
+    withTrailers(cwd, message, [...carried, ...(session ? [`Workit-Session: ${session}`] : [])]),
+  );
   if (paths.length) {
     if (paths.some((value) => value.startsWith("-") || !value.trim()))
       return failure("invalid_input", "paths must not be empty or start with -");
-    const added = git(cwd, ["add", "-A", "--", ...paths]);
-    if (!added.ok) return failure("failed", `git add failed: ${gitError(added)}`);
+    // A path already removed from disk and index (`git rm`) has nothing to
+    // add, and `git add` would fail on it; the commit below still records it.
+    const tracked = new Set(nulList(git(cwd, ["ls-files", "-z", "--", ...paths]).stdout));
+    const addable = paths.filter(
+      (value) =>
+        existsSync(path.resolve(cwd, value)) ||
+        [...tracked].some((file) => file === value || file.startsWith(`${value}/`)),
+    );
+    if (addable.length) {
+      const added = git(cwd, ["add", "-A", "--", ...addable]);
+      if (!added.ok) return failure("failed", `git add failed: ${gitError(added)}`);
+    }
+    if (changeRequired && git(cwd, ["diff", "--cached", "--quiet", "HEAD", "--", ...paths]).ok)
+      return nothingToCommit(`${paths.join(", ")} has no change to commit`);
     args.push("--", ...paths);
   } else if (input.all) {
     const added = git(cwd, ["add", "-A"]);
     if (!added.ok) return failure("failed", `git add failed: ${gitError(added)}`);
-  } else {
+    if (changeRequired && git(cwd, ["diff", "--cached", "--quiet"]).ok)
+      return nothingToCommit("the working tree is clean");
+  } else if (changeRequired) {
     const staged = git(cwd, ["diff", "--cached", "--name-only", "-z"]);
     if (staged.ok && !staged.stdout.replaceAll("\0", "")) {
       const dirt = dirtEntries(cwd);
+      if (!dirt.length) return nothingToCommit("the working tree is clean");
       return failure(
-        dirt.length ? "blocked" : "failed",
-        dirt.length
-          ? `nothing_staged: nothing is staged and workit never commits unrelated changes implicitly (${dirt.length} changed: ${dirt
-              .slice(0, 5)
-              .map((entry) => entry.slice(3))
-              .join(", ")}${dirt.length > 5 ? ", …" : ""})`
-          : "nothing_to_commit: the working tree is clean",
-        dirt.length
-          ? `workit git commit -m '<msg>' -- <paths>  # or --all to commit every change`
-          : undefined,
+        "blocked",
+        `nothing_staged: nothing is staged and workit never commits unrelated changes implicitly (${dirt.length} changed: ${dirt
+          .slice(0, 5)
+          .map((entry) => entry.slice(3))
+          .join(", ")}${dirt.length > 5 ? ", …" : ""})`,
+        `workit git commit -m '<msg>' -- <paths>  # or --all to commit every change`,
       );
     }
   }
-  const committed = git(cwd, args, { timeoutMs: COMMIT_TIMEOUT_MS, env: input.env });
-  if (!committed.ok) return failure("failed", `git commit failed: ${gitError(committed, 6)}`);
+  const committed = git(cwd, args, {
+    timeoutMs: COMMIT_TIMEOUT_MS,
+    env: input.env,
+  });
+  if (!committed.ok)
+    return failure(
+      "failed",
+      `git commit failed (a hook or git refused it):\n${gitOutput(committed)}`,
+    );
   const sha = headSha(cwd);
   if (!sha) return failure("failed", "the commit did not resolve");
+  // A merge commit lists what it brought in relative to its first parent.
+  const merge = git(cwd, ["rev-parse", "-q", "--verify", `${sha}^2`]).ok;
   const files = nulList(
-    git(cwd, ["diff-tree", "--root", "--no-commit-id", "--name-only", "-r", "-z", sha]).stdout,
+    git(
+      cwd,
+      merge
+        ? ["diff", "--name-only", "-z", `${sha}^1`, sha]
+        : ["diff-tree", "--root", "--no-commit-id", "--name-only", "-r", "-z", sha],
+    ).stdout,
   );
   const leftDirty = dirtEntries(cwd).length;
+  const notes: string[] = [];
+  // Only a commit on the branch's own upstream needs a forced push.
+  const upstream = `refs/remotes/${pushRemoteName(cwd, branch) ?? "origin"}/${branch}`;
+  if (previous && git(cwd, ["merge-base", "--is-ancestor", previous, upstream]).ok)
+    notes.push(
+      `the amended commit ${previous.slice(0, 12)} was already pushed (${upstream.slice("refs/remotes/".length)}); publish the rewrite with: workit git push --force-with-lease`,
+    );
 
   // Bounded row (MAX_LINE_BYTES): the subject and the first files only.
   const listed: string[] = [];
@@ -388,6 +649,7 @@ export function gitCommit(
     subject: (message.split("\n", 1)[0] ?? "").slice(0, 200),
     files: listed,
     fileCount: files.length,
+    ...(previous ? { amended: previous } : {}),
   });
   return success({
     sha,
@@ -396,6 +658,8 @@ export function gitCommit(
     files,
     leftDirty,
     session,
+    amended: previous,
+    notes,
     recorded: row.ok ? { id: String(row.value.id) } : { error: row.error },
   });
 }
@@ -420,6 +684,8 @@ export function pushPreflight(
   cwd: string,
   options: { branch?: string | null } = {},
 ): ForgeResult<PushPlan> {
+  const progress = operationInProgress(cwd);
+  if (progress) return inProgressFailure(progress.operation, "push");
   const branch = options.branch ?? currentBranch(cwd);
   if (!branch) return failure("invalid_input", "HEAD is detached; push a branch");
   if (isProtectedTarget(cwd, branch))
@@ -490,13 +756,44 @@ export function recordedRemoteTip(cwd: string, plan: PushPlan): string | undefin
 
 /**
  * `--force-if-includes` semantics: the remote tip was integrated locally, i.e.
- * it is reachable from the local branch or appears in the branch's reflog
- * (the commit was this branch's tip before a rebase/amend).
+ * it is reachable from the local branch or from a former tip in the branch's
+ * reflog (the branch held it before an amend or rebase). Reachability only:
+ * this guards what a forced push may drop.
  */
 function includesRemoteTip(cwd: string, branch: string, tip: string): boolean {
-  if (git(cwd, ["merge-base", "--is-ancestor", tip, `refs/heads/${branch}`]).ok) return true;
-  const reflog = git(cwd, ["reflog", "show", "--format=%H", `refs/heads/${branch}`, "--"]);
-  return reflog.ok && reflog.stdout.split("\n").some((line) => line.trim() === tip);
+  const ref = `refs/heads/${branch}`;
+  if (git(cwd, ["merge-base", "--is-ancestor", tip, ref]).ok) return true;
+  const reflog = git(cwd, ["reflog", "show", "--format=%H", ref, "--"]);
+  const former = [
+    ...new Set(
+      (reflog.ok ? reflog.stdout : "")
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean),
+    ),
+  ];
+  if (former.includes(tip)) return true;
+  if (!former.length) return false;
+  // Commits reachable from the tip but from no former tip: none means included.
+  const outside = git(cwd, ["rev-list", "-n", "1", "--stdin"], {
+    input: `${tip}\n${former.map((sha) => `^${sha}`).join("\n")}\n`,
+  });
+  return outside.ok && !outside.stdout.trim();
+}
+
+/**
+ * Every commit the remote tip has and the branch lacks is a non-merge commit
+ * with a patch-equivalent local commit (the same work, rebased elsewhere).
+ * Only words the push advice; it never relaxes the lease guard, because a
+ * merge commit can carry changes no patch-id shows.
+ */
+function patchEquivalent(cwd: string, branch: string, tip: string): boolean {
+  const ref = `refs/heads/${branch}`;
+  const merges = git(cwd, ["rev-list", "--count", "--merges", `${ref}..${tip}`]);
+  if (!merges.ok || merges.stdout.trim() !== "0") return false;
+  const cherry = git(cwd, ["cherry", ref, tip]);
+  const lines = cherry.ok ? cherry.stdout.split("\n").filter(Boolean) : [];
+  return lines.length > 0 && lines.every((line) => line.startsWith("-"));
 }
 
 export type PushOutcome = {
@@ -578,13 +875,38 @@ export function executePush(
           `lease_mismatch: ${plan.remote}/${plan.branch} moved while pushing`,
           `git fetch ${plan.remote} ${plan.branch} && git rebase ${plan.remote}/${plan.branch}  # or merge it; then: workit git push`,
         );
+      const rejected = /non-fast-forward|fetch first|\[rejected\]/iu.test(text);
+      const integrated =
+        rejected && before.sha !== null && includesRemoteTip(cwd, plan.branch, before.sha);
+      const equivalent =
+        rejected &&
+        !integrated &&
+        before.sha !== null &&
+        patchEquivalent(cwd, plan.branch, before.sha);
+      if (before.sha !== null && (integrated || equivalent)) {
+        // An amend or rebase rewrote commits that are already pushed: a fetch
+        // and rebase would re-apply the old ones. The lease is the tip seen now.
+        const lease =
+          recordedRemoteTip(cwd, plan) === before.sha
+            ? "workit git push --force-with-lease"
+            : `workit git push --force-with-lease --expect ${before.sha}`;
+        return failure(
+          "failed",
+          integrated
+            ? `non_fast_forward: local ${plan.branch} was rewritten (amend or rebase) after ${plan.remote}/${plan.branch} (${before.sha.slice(0, 12)}) was pushed; that tip is already part of the local history, so do not fetch and rebase`
+            : `non_fast_forward: every commit on ${plan.remote}/${plan.branch} (${before.sha.slice(0, 12)}) has a patch-equivalent commit in local ${plan.branch} (rebased elsewhere); fetching and rebasing would apply them twice`,
+          integrated
+            ? lease
+            : `${lease} --overwrite-unintegrated  # after checking ${plan.remote}/${plan.branch} holds nothing else`,
+        );
+      }
       if (/non-fast-forward|fetch first|\[rejected\]/iu.test(text))
         return failure(
           "failed",
           `non_fast_forward: ${plan.remote}/${plan.branch} has commits this branch does not`,
           `git fetch ${plan.remote} && git rebase ${plan.remote}/${plan.branch}  # or, if the rewrite is intended: workit git push --force-with-lease`,
         );
-      return failure("failed", `git push to ${plan.url} failed: ${gitError(run)}`);
+      return failure("failed", `git push to ${plan.url} failed:\n${gitOutput(run)}`);
     }
     pushed = true;
   }
@@ -669,6 +991,10 @@ export function deleteRemoteBranch(
   if (run.ok) return { ok: true };
   const text = `${run.stderr}\n${run.stdout}`;
   return /stale info|cannot lock ref|fetch first|non-fast-forward/iu.test(text)
-    ? { ok: false, lease: true, error: "the remote branch tip changed before deletion" }
+    ? {
+        ok: false,
+        lease: true,
+        error: "the remote branch tip changed before deletion",
+      }
     : { ok: false, lease: false, error: gitError(run) };
 }