@kabmo-labs/kabmo 0.0.0-stage → 0.0.1

package/src/server/lib/fs/git-revert.ts

@@ -0,0 +1,93 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Restore one path to its committed state, discarding local changes — and
+ * REFUSE to do it to a conflicted one.
+ *
+ * Three git steps, because a single command cannot cover the states a change
+ * can be in:
+ *
+ *  1. `git reset -q -- <path>` unstages it. `git restore --staged` is the
+ *     obvious form but it resolves HEAD and refuses outright in a repository
+ *     whose first commit is still staged ("could not resolve 'HEAD'"), so a
+ *     discard there left the file staged and reported success (verified).
+ *  2. `git checkout -- <path>` restores a tracked change. It works with an
+ *     unborn HEAD and it never touches an untracked path (it exits non-zero,
+ *     which is not a failure here).
+ *  3. `git clean -fd -- <path>` removes what step 2 left: an untracked file, or
+ *     a file that was only ever staged.
+ *
+ * The previous shape (`git restore`, and on ANY failure `fs.rmSync` the path)
+ * is why a discard could destroy committed work: for a folder holding a clean
+ * tracked file beside an untracked one, `git status --porcelain -- <dir>` opens
+ * with `??` — that branch took `rm -rf` and deleted the tracked file too
+ * (verified: the committed `dir/keep.txt` was gone and the tree read ` D`). It
+ * also deleted a modified TRACKED file whenever the restore failed for an
+ * unrelated reason, such as a filename holding a double quote.
+ *
+ * **The conflict refusal is the fourth rule, and it is the one that matters
+ * most.** On a conflicted path the three steps above succeed while doing
+ * something the user did not ask for: measured on a real `UU f`, the sequence
+ * threw away the conflicted content, restored the pre-merge version of that
+ * file, and LEFT `MERGE_HEAD` in place — `git status` afterwards read "All
+ * conflicts fixed but you are still merging". A trash icon that silently ends
+ * a conflict by picking one side, and leaves the operation open, is worse than
+ * no trash icon: the merge looks finished and is not. Resolving a conflict is
+ * a decision (`--ours`/`--theirs`/edit), so it has its own actions.
+ */
+
+import { runGit } from '@/server/lib/fs/git-run';
+
+/** Runs a git command and throws with its stderr when it exits non-zero. */
+async function expectOk(args: string[], cwd: string, timeout?: number): Promise<void> {
+  const result = await runGit(args, { cwd, timeout, maxBuffer: 1024 * 1024 });
+  if (result.error) throw result.error;
+  if (result.exitCode !== 0) {
+    throw new Error(result.stderr.trim() || result.stdout.trim() || `git exited with code ${result.exitCode}`);
+  }
+}
+
+export interface RevertOptions {
+  targetDir: string;
+  /** Repo-relative path. */
+  file: string;
+  /** Paths with unmerged index entries, from `readGitState`. */
+  conflicts: readonly string[];
+}
+
+/**
+ * Discard local changes to one path.
+ *
+ * Throws on a conflicted path rather than resolving it: the caller has the
+ * conflict list (it read the state to render the row), so this is a guard
+ * against the wrong action being offered, not a second read.
+ */
+export async function revertPath({ targetDir, file, conflicts }: RevertOptions): Promise<void> {
+  if (conflicts.includes(file)) {
+    throw new Error(
+      `${file} is conflicted — take one side or resolve it in the editor instead of discarding.`,
+    );
+  }
+
+  await expectOk(['reset', '-q', '--', file], targetDir);
+
+  const restored = await runGit(['checkout', '--', file], { cwd: targetDir });
+  // A path git does not know (untracked, or already gone) is not a failure —
+  // the clean below is what removes it.
+  if (!restored.error && restored.exitCode !== 0 && !/pathspec/i.test(restored.stderr)) {
+    throw new Error(restored.stderr.trim() || `git checkout exited with code ${restored.exitCode}`);
+  }
+
+  await expectOk(['clean', '-fd', '--', file], targetDir);
+}
+
+/** Discard every unstaged change in the working tree. */
+export async function revertAll(targetDir: string): Promise<void> {
+  // `checkout` covers tracked changes in a repository with no commits too, and
+  // it never deletes an untracked file — `clean` does that explicitly.
+  await expectOk(['checkout', '--', '.'], targetDir);
+  await expectOk(['clean', '-fd'], targetDir);
+}

package/src/server/lib/fs/git-run.ts

@@ -0,0 +1,219 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * `git` as ARGV, plus the path guard the mutating actions need.
+ *
+ * The Source Control panel's actions used to build shell strings —
+ * `git add "${file}"`, `git commit -m "${message}"` — and both operands are
+ * user-controlled. A repository is free to hold a file called
+ * `evil$(touch /tmp/pwn).txt`, and a commit message is free to hold backticks
+ * or a `$( )`: `sh -c` expands them. Measured against the previous runner, a
+ * commit message of ``fix `touch /tmp/PWN` thing`` created the file and
+ * committed `fix  thing`. The same shape silently broke the actions a reader
+ * would call normal: a filename holding a double quote made `git add` exit 2
+ * with `unexpected EOF while looking for matching '"'`, and the revert path
+ * read that failure as "the file is untracked" and deleted it.
+ *
+ * Passing every operand as its own argv element removes the shell from the
+ * picture entirely — the rule `lib/wiki/git.ts` already follows, for the same
+ * reason.
+ *
+ * `resolveRepoPath` is the second half: `git` runs with a cwd, so a relative
+ * path is bounded by git itself — but the untracked-file branch REMOVES what
+ * the path names, and `path.join(targetDir, '../../x')` escapes the working
+ * tree. Nothing that reaches the filesystem may be built from a client string
+ * without this check.
+ */
+
+import path from 'path';
+import { isWithinRoot } from '@/server/lib/fs/root';
+import { isUnmergedCode } from '@/shared/lib/fs/git-unmerged';
+import type { GitChange } from '@/shared/types';
+
+export interface GitRunResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number | null;
+  signalCode: NodeJS.Signals | null;
+  killed: boolean;
+  /** Set only when the spawn itself failed (git missing, bad cwd). */
+  error?: Error;
+}
+
+/**
+ * The environment every `git` invocation gets, whether it is spawned as argv
+ * (`runGit`) or through a shell (`runShell`).
+ *
+ * Three variables, each the fix for a failure measured in this repository:
+ *
+ * - `GIT_TERMINAL_PROMPT=0` — no terminal to answer a credential prompt, so a
+ *   `pull` on a private remote would otherwise block to its timeout.
+ * - `GIT_EDITOR=true` — no terminal for the editor a merge/rebase/cherry-pick
+ *   opens for its commit message. Measured: unset, `git merge --continue` fails
+ *   with "Terminal is dumb, but EDITOR unset"; a real `GIT_EDITOR=vim` inherited
+ *   from the environment BLOCKS until the timeout kills it.
+ * - `GIT_OPTIONAL_LOCKS=0` — a READ must not take `.git/index.lock`. `git status`
+ *   is not read-only: with a STALE index (a working file newer than the stat the
+ *   index recorded — i.e. right after a checkout or a merge) it refreshes the
+ *   index and writes it back. The panel runs those reads on its own schedule
+ *   (the repo modal's per-repo read, the status payload on every tool call), so
+ *   a merge issued while one was in flight lost the race and failed with
+ *   `Unable to create '.git/index.lock': File exists` — reproduced: 8 of 8
+ *   rounds with a concurrent `git status` on a stale index, 0 of 10 with this
+ *   set. That is the `git action merge_branch failed (HTTP 400)` the browser
+ *   specs caught. The lock is only an optimization (it lets the next read skip
+ *   re-stat'ing); a mutating command takes it either way, which is correct.
+ *
+ * It is exported rather than inlined at each spawn so a new git call site cannot
+ * silently miss it — the status read goes through `runShell`, not `runGit`, and
+ * that split is exactly how one of the two paths would have kept the bug.
+ */
+export const GIT_ENV = {
+  GIT_TERMINAL_PROMPT: '0',
+  GIT_EDITOR: 'true',
+  GIT_OPTIONAL_LOCKS: '0',
+} as const;
+
+export interface GitRunOptions {
+  cwd: string;
+  /** Signal the process group after this many milliseconds. */
+  timeout?: number;
+  maxBuffer?: number;
+}
+
+/**
+ * Run one `git` command with `args` as argv elements.
+ *
+ * Exit handling is explicit, exactly as `runShell`'s is: Bun does not throw for
+ * a non-zero exit, so callers check `exitCode` and `error`. A timeout signals
+ * the whole process GROUP, because a hook or a pager that outlives the git
+ * process would otherwise keep the pipes open past the deadline.
+ */
+export async function runGit(args: string[], options: GitRunOptions): Promise<GitRunResult> {
+  const timeout = options.timeout;
+  const groupKill = timeout !== undefined && process.platform !== 'win32';
+  let proc: Bun.Subprocess<'ignore', 'pipe', 'pipe'>;
+  try {
+    proc = Bun.spawn({
+      cmd: ['git', ...args],
+      cwd: options.cwd,
+      stdin: 'ignore',
+      stdout: 'pipe',
+      stderr: 'pipe',
+      detached: groupKill,
+      maxBuffer: options.maxBuffer ?? 1024 * 1024,
+      // `GIT_TERMINAL_PROMPT`, `GIT_EDITOR` and `GIT_OPTIONAL_LOCKS` — see
+      // `GIT_ENV` above for what each one prevents and how it was measured.
+      env: { ...Bun.env, ...GIT_ENV },
+    });
+  } catch (error) {
+    return {
+      stdout: '',
+      stderr: error instanceof Error ? error.message : String(error),
+      exitCode: null,
+      signalCode: null,
+      killed: false,
+      error: error instanceof Error ? error : new Error(String(error)),
+    };
+  }
+
+  const timer = timeout === undefined
+    ? undefined
+    : setTimeout(() => {
+        try {
+          if (groupKill) process.kill(-proc.pid, 'SIGTERM');
+          else proc.kill('SIGTERM');
+        } catch {
+          // Already gone: the command finished inside its own timeout.
+        }
+      }, timeout);
+
+  let error: Error | undefined;
+  let stdout = '';
+  let stderr = '';
+  try {
+    [stdout, stderr] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+    ]);
+  } catch (err) {
+    error = err instanceof Error ? err : new Error(String(err));
+  }
+  const exitCode = await proc.exited;
+  clearTimeout(timer);
+  return {
+    stdout,
+    stderr,
+    exitCode,
+    signalCode: proc.signalCode,
+    killed: proc.killed,
+    ...(error ? { error } : {}),
+  };
+}
+
+/**
+ * A client-supplied repo-relative path, resolved to an absolute one inside
+ * `targetDir` — or null when it names something outside it.
+ *
+ * An empty path is refused rather than treated as the repo root: every caller
+ * here is acting on ONE change, and `git add ''` is an error while
+ * `git restore ''` is not.
+ */
+export function resolveRepoPath(targetDir: string, rel: string): string | null {
+  const trimmed = (rel ?? '').trim();
+  if (!trimmed) return null;
+  // Git speaks POSIX separators; a client on Windows may hand back backslashes.
+  const normalized = trimmed.split('\\').join(path.sep);
+  const resolved = path.resolve(targetDir, normalized);
+  return isWithinRoot(targetDir, resolved) ? resolved : null;
+}
+
+/** The repo-relative form git itself wants, from a path a client supplied. */
+export function repoRelative(rel: string): string {
+  return (rel ?? '').trim().split('\\').join('/');
+}
+
+/**
+ * Parse `git status --porcelain=v1 -z` output into change rows.
+ *
+ * `-z` is the only LOSSLESS form, and both of the other form's losses bite the
+ * diff panel. A path holding a space or any non-ASCII byte comes back QUOTED
+ * with its non-ASCII bytes octal-escaped (`"\303\274n..."`), and no JSON decode
+ * reverses that — `JSON.parse` turns it into the literal text `\303\274`, a
+ * path that does not exist, so the diff for every accented filename read as
+ * "No differences found". `-z` never quotes and never escapes. It also replaces
+ * the `old -> new` spelling with a second NUL-terminated field, so a rename is
+ * unwrapped from its own record instead of by splitting on a separator that a
+ * filename is free to contain.
+ *
+ * A rename or copy spends TWO records — the new path, then the old one — and
+ * only the first is a path the working tree still has.
+ */
+export function parsePorcelainZ(out: string): GitChange[] {
+  const records = out.split('\0');
+  const changes: GitChange[] = [];
+  for (let i = 0; i < records.length; i++) {
+    const record = records[i];
+    // The trailing empty record, and anything shorter than `XY p`.
+    if (record.length < 4) continue;
+    const status = record.slice(0, 2);
+    const code = status[0] === 'R' || status[0] === 'C' ? status[0] : status[1];
+    if (code === 'R' || code === 'C') i += 1;
+    changes.push({
+      status,
+      file: record.slice(3),
+      // An unmerged pair is the two SIDES of a conflict, not an index/worktree
+      // pair: `UU` has no space in either column, so the test below marked every
+      // conflicted file as staged — and the list then rendered it under "Staged
+      // Changes" AND under "Changes" (the worktree half of the same test also
+      // passes for `UU`). A conflicted file is neither; it is its own section.
+      staged: !isUnmergedCode(status) && status[0] !== ' ' && status[0] !== '?',
+      additions: 1,
+      deletions: 0,
+    });
+  }
+  return changes;
+}

package/src/server/lib/fs/git-stash.ts

@@ -0,0 +1,159 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The stash: list, save, pop, apply, drop.
+ *
+ * The third-most-used verb in the agent's own session corpus (2784
+ * invocations), and the natural partner of the conflict work: a conflicting
+ * `git stash pop` is the ONE conflict shape that leaves no operation file, so
+ * it is the case `git-state.ts` names `stash-pop` and aborts with
+ * `git reset --merge HEAD` rather than an `--abort` verb.
+ *
+ * `git stash list --format='%gd|%gs|%ct'` is the read: `%gd` is the selector
+ * (`stash@{0}`), `%gs` the reflog subject git wrote (`On main: wip test`), and
+ * `%ct` the commit time. The default `stash@{0}: WIP on main: …` line would
+ * have to be split on the first colon, and a branch name may contain one.
+ */
+
+import { runGit } from '@/server/lib/fs/git-run';
+import { readGitState } from '@/server/lib/fs/git-state';
+
+export interface StashEntry {
+  /** The selector git accepts back — `stash@{0}`. */
+  ref: string;
+  /** The reflog subject, e.g. `On main: wip test`. */
+  subject: string;
+  /** The stash commit time, as a relative string for display. */
+  date: string;
+}
+
+/** Runs a git command and throws with its stderr when it exits non-zero. */
+async function expectOk(args: string[], cwd: string, timeout?: number): Promise<string> {
+  const result = await runGit(args, { cwd, timeout, maxBuffer: 1024 * 1024 });
+  if (result.error) throw result.error;
+  if (result.exitCode !== 0) {
+    throw new Error(result.stderr.trim() || result.stdout.trim() || `git exited with code ${result.exitCode}`);
+  }
+  return result.stdout;
+}
+
+/**
+ * The stash list's read.
+ *
+ * `%x09` is the TAB escape that WORKS here: `stash list` shares
+ * `for-each-ref`'s format parser, but only the `%xNN` hex form is expanded —
+ * `%09` comes through literally (measured: the ref arrived as
+ * `stash@{0}%09On main: wip%091791962964`, one field containing the separator).
+ * The default `stash@{0}: WIP on main: …` line would have to be split on the
+ * first colon, and a branch name may contain one, which is why the format is
+ * used at all.
+ */
+const STASH_FORMAT = '%gd%x09%gs%x09%ct';
+
+export async function listStashes(targetDir: string): Promise<StashEntry[]> {
+  const result = await runGit(
+    ['stash', 'list', `--format=${STASH_FORMAT}`],
+    { cwd: targetDir, timeout: 8_000 },
+  );
+  if (result.exitCode !== 0) return [];
+  const stashes: StashEntry[] = [];
+  for (const line of result.stdout.split('\n')) {
+    if (!line.trim()) continue;
+    const [ref, subject, seconds] = line.split('\t');
+    if (!ref) continue;
+    stashes.push({ ref, subject: subject ?? '', date: formatStashDate(seconds) });
+  }
+  return stashes;
+}
+
+/** A relative age from git's epoch seconds; the raw number is not for display. */
+function formatStashDate(seconds: string): string {
+  const at = Number(seconds) * 1000;
+  if (!Number.isFinite(at) || at <= 0) return '';
+  const delta = Date.now() - at;
+  const minutes = Math.floor(delta / 60_000);
+  if (minutes < 1) return 'just now';
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  return `${Math.floor(hours / 24)}d ago`;
+}
+
+export interface StashPushOptions {
+  targetDir: string;
+  message?: string;
+  /** Also stash untracked files (`-u`). */
+  includeUntracked?: boolean;
+}
+
+/**
+ * Stash the working tree.
+ *
+ * `-u` is opt-in and never implied: it sweeps untracked files into the stash,
+ * which is a different promise from "set my changes aside" and can take a build
+ * directory with it.
+ */
+export async function pushStash({ targetDir, message, includeUntracked }: StashPushOptions): Promise<void> {
+  const args = ['stash', 'push'];
+  if (message?.trim()) args.push('-m', message.trim());
+  if (includeUntracked) args.push('-u');
+  const output = await expectOk(args, targetDir, 60_000);
+  // A clean tree answers "No local changes to save" with exit 0 — a success
+  // that stashed nothing. Reported rather than swallowed, because the user
+  // asked for a stash and did not get one.
+  if (/No local changes to save/i.test(output)) throw new Error('Nothing to stash — the working tree is clean.');
+}
+
+/**
+ * A stash ref, refused unless it is shaped like one.
+ *
+ * `stash@{0}` is the only form the panel ever sends, and the ref is a client
+ * string: measured, `git stash apply --help` printed its usage instead of
+ * applying anything, and `git stash drop --help` did the same — a ref that
+ * begins with `-` is read as an OPTION. The grammar is exact (`stash@{N}`, or a
+ * bare `N`), so anything else is a bug or a probe and both are refused here.
+ */
+function stashRefFor(value: string): string {
+  const ref = value.trim() || 'stash@{0}';
+  if (!/^(?:stash@\{\d+\}|\d+)$/.test(ref)) {
+    throw new Error(`'${ref}' is not a stash reference.`);
+  }
+  return ref;
+}
+
+export interface StashApplyOptions {
+  targetDir: string;
+  ref: string;
+  /** `pop` removes the entry after applying; `apply` keeps it. */
+  pop?: boolean;
+}
+
+/**
+ * Apply one stash entry.
+ *
+ * A conflict here is the `stash-pop` state: unmerged entries and NO operation
+ * file, so the caller's abort is `git reset --merge HEAD`. `pop` deliberately
+ * leaves the entry in place on a conflict (that is git's own behaviour — the
+ * stash is only dropped on success), which is what makes the retry possible.
+ */
+export async function applyStash({ targetDir, ref, pop }: StashApplyOptions): Promise<void> {
+  const result = await runGit(['stash', pop ? 'pop' : 'apply', stashRefFor(ref)], { cwd: targetDir, timeout: 60_000, maxBuffer: 1024 * 1024 });
+  if (result.error) throw result.error;
+  if (result.exitCode === 0) return;
+  // A `stash pop` that conflicts exits 1 with the changes applied and the
+  // conflict in the working tree — the `stash-pop` state the panel draws. It is
+  // not a failure, and reporting it as one hid the conflict it had just made.
+  // The state is the proof: a real error (a bad ref, a dirty tree) leaves no
+  // `stash-pop`.
+  const state = await readGitState(targetDir);
+  if (state.operation === 'stash-pop') return;
+  throw new Error(result.stderr.trim() || result.stdout.trim() || `git exited with code ${result.exitCode}`);
+}
+
+/** Drop one stash entry. */
+export async function dropStash(targetDir: string, ref: string): Promise<void> {
+  await expectOk(['stash', 'drop', stashRefFor(ref)], targetDir, 30_000);
+}

package/src/server/lib/fs/git-state-verbs.test.ts

@@ -0,0 +1,117 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The verb tables for a stopped operation: which command CONCLUDES it and which
+ * ABORTS it.
+ *
+ * These two mappings are the fix for the bugs that made a stopped operation a
+ * dead end, and each entry is a measurement rather than a preference:
+ *
+ *  - **`git commit --no-edit` only concludes a MERGE.** On a resolved rebase
+ *    conflict it makes the commit and leaves `rebase-merge` behind — measured,
+ *    `git status` then reads "interactive rebase in progress" and the panel's
+ *    operation bar would never clear. Cherry-pick and revert have the same
+ *    shape, each with its own `--continue`.
+ *  - **`stash-pop` has no verb at all.** A conflicting `stash pop` leaves
+ *    unmerged entries and NO operation file, so every `--abort` exits 128 with
+ *    its own fatal; only `reset --merge HEAD` clears it (and it keeps the stash
+ *    entry, which is what makes the retry possible).
+ *
+ * A table test rather than one assertion per branch: the SET is the contract,
+ * and a new operation must be given both answers or the test fails.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { abortArgsFor, OPERATION_PATHS } from '@/server/lib/fs/git-state';
+import { continueArgsFor } from '@/server/lib/fs/git-merge';
+import type { GitOperation } from '@/shared/types';
+
+/** Every operation the state read can report, as the file map declares them. */
+const ALL_OPERATIONS: GitOperation[] = ['merge', 'rebase', 'rebase-apply', 'cherry-pick', 'revert', 'stash-pop'];
+
+describe('continueArgsFor', () => {
+  test('a merge is concluded by a commit, not by `merge --continue`', () => {
+    // Both finish a merge, but `--continue` needs an editor for the message it
+    // prepared and there is no terminal to draw one in; `--no-edit` needs none.
+    expect(continueArgsFor('merge')).toEqual(['commit', '--no-edit']);
+  });
+
+  test('each sequencer gets its OWN --continue', () => {
+    // The bug this pins: `commit --no-edit` on a rebase makes the commit and
+    // leaves the rebase RUNNING, so the bar never clears.
+    expect(continueArgsFor('rebase')).toEqual(['rebase', '--continue']);
+    expect(continueArgsFor('rebase-apply')).toEqual(['rebase', '--continue']);
+    expect(continueArgsFor('cherry-pick')).toEqual(['cherry-pick', '--continue']);
+    expect(continueArgsFor('revert')).toEqual(['revert', '--continue']);
+  });
+
+  test('a stash pop has NOTHING to conclude', () => {
+    // Its changes are in the working tree with no sequencer to finish; a commit
+    // here would create one the user never asked for. `null` is what makes the
+    // route refuse and the bar hide the button.
+    expect(continueArgsFor('stash-pop')).toBeNull();
+  });
+
+  test('every operation has an answer — null or a verb, never a fallthrough', () => {
+    for (const operation of ALL_OPERATIONS) {
+      const args = continueArgsFor(operation);
+      if (args !== null) {
+        expect(Array.isArray(args)).toBe(true);
+        expect(args.length).toBeGreaterThan(0);
+      }
+    }
+  });
+});
+
+describe('abortArgsFor', () => {
+  test('each operation aborts with its own verb', () => {
+    expect(abortArgsFor('merge')).toEqual(['merge', '--abort']);
+    expect(abortArgsFor('rebase')).toEqual(['rebase', '--abort']);
+    expect(abortArgsFor('rebase-apply')).toEqual(['rebase', '--abort']);
+    expect(abortArgsFor('cherry-pick')).toEqual(['cherry-pick', '--abort']);
+    expect(abortArgsFor('revert')).toEqual(['revert', '--abort']);
+  });
+
+  test('a stash pop aborts by RESET, because no --abort verb exists for it', () => {
+    // Measured: with unmerged entries and no operation file, `merge --abort`,
+    // `rebase --abort` and `cherry-pick --abort` each exit 128 with its own
+    // fatal. `reset --merge HEAD` clears the conflict and keeps the stash entry.
+    expect(abortArgsFor('stash-pop')).toEqual(['reset', '--merge', 'HEAD']);
+  });
+
+  test('every operation has an abort — a stopped operation is never a dead end', () => {
+    for (const operation of ALL_OPERATIONS) {
+      const args = abortArgsFor(operation);
+      expect(args.length).toBeGreaterThan(0);
+      // Never the same verb as continue: an abort that concluded would be
+      // indistinguishable from pressing the other button.
+      expect(args).not.toEqual(continueArgsFor(operation));
+    }
+  });
+});
+
+describe('OPERATION_PATHS', () => {
+  test('maps each state FILE to the operation it means', () => {
+    const byName = Object.fromEntries(OPERATION_PATHS.map((p) => [p.name, p.operation]));
+    expect(byName).toEqual({
+      MERGE_HEAD: 'merge',
+      'rebase-merge': 'rebase',
+      'rebase-apply': 'rebase-apply',
+      CHERRY_PICK_HEAD: 'cherry-pick',
+      REVERT_HEAD: 'revert',
+    });
+  });
+
+  test('every operation except stash-pop is a file-backed state', () => {
+    // `stash-pop` is the one with NO file — that absence is what makes it a
+    // distinct operation rather than a null, so it must not appear here.
+    const backed = new Set(OPERATION_PATHS.map((p) => p.operation));
+    for (const operation of ALL_OPERATIONS) {
+      if (operation === 'stash-pop') expect(backed.has(operation)).toBe(false);
+      else expect(backed.has(operation)).toBe(true);
+    }
+  });
+});