@ravshansbox/pi-next-issue 0.0.0-stage → 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ravshan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,55 @@
-# Temporary Holding Version
+# pi-next-issue
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A [pi](https://github.com/earendil-works/pi) extension that works through the open GitHub issues of a repository in the background, while you keep using pi.
+
+```bash
+pi install npm:@ravshansbox/pi-next-issue
+```
+
+It needs `git` and an authenticated [`gh`](https://cli.github.com/).
+
+## Use
+
+Run these in pi, inside a git repository:
+
+- `/next-issue start` starts a run.
+- `/next-issue stop` stops the run. The issue keeps its saved state, and the next run resumes it.
+- `/next-issue status` shows where the run is.
+
+The footer shows the issue, the stage, the number of tool calls and the time spent on the issue, for example `next-issue #12 · review 1/3 · 37 tools · 4m12s`. A line above the editor shows the last tool call. A note appears when an issue is merged or needs a human.
+
+The run does not belong to a session: it goes on after `/new`, `/resume`, a fork or a reload, and the new session shows it. It stops when you quit pi.
+
+## What it does
+
+Each loop fetches the open issues and takes the oldest one with saved state, else the oldest one with the `status:todo` label and none of `status:in-progress`, `status:done`, `status:needs-human` or `status:blocked`. The run ends when no such issue is left, or at the first error. For each issue:
+
+1. Swap `status:todo` for `status:in-progress`.
+2. Add a git worktree at `.worktrees/<n>` on the `<n>` branch, from the remote default branch.
+3. The implementer agent does the work. The extension commits it, with the subject from a `commit:` line in the reply of the agent, and pushes.
+4. Open a pull request that closes the issue.
+5. Wait for the checks. On a red build, the fixer agent gets the failed logs, up to `maxCiFixes` times.
+6. The reviewer agent judges the diff and gives a verdict with `blocking` and `minor` findings, which goes on the pull request. Any change the reviewer makes is thrown away.
+7. While review rounds are left, the fixer gets every finding, and the checks and the review run again. In the last round only a blocking finding stops the merge.
+8. Squash-merge the pull request, wait until it is merged, set `status:done`, and remove the worktree, the local branch, the remote branch and the saved state.
+
+An issue that cannot go on gets `status:needs-human` and a comment with the reason. Its worktree stays for you to look at.
+
+The implementer and the reviewer read the issue title, the body and the comments. They get only comments by the owner, members and collaborators of the repository. The body is passed as it is, and its author can edit it after you add the label, so check the body before you add the label.
+
+Each agent is a pi session in the worktree. It uses the model and thinking level from your pi settings, and loads all of your extensions except this one.
+
+The state of each issue is saved in `.worktrees/<n>.json`. The extension adds `/.worktrees/` to `.git/info/exclude`.
+
+## Config
+
+An optional `.pi/next-issue.json` in the repository sets these fields:
+
+| Field                 | Default    | Meaning                                           |
+| --------------------- | ---------- | ------------------------------------------------- |
+| `remote`              | `"origin"` | The git remote to push to.                        |
+| `maxCiFixes`          | `3`        | Fixes of red checks per issue.                    |
+| `maxReviewRounds`     | `3`        | Review rounds per issue.                          |
+| `checkTimeoutMinutes` | `30`       | The longest wait for the checks, and for a merge. |
+| `diffMaxChars`        | `60000`    | The longest diff that the reviewer gets.          |
+| `logMaxChars`         | `20000`    | The longest failed log that the fixer gets.       |

package/index.ts

@@ -0,0 +1,201 @@
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { loadConfig } from './src/config.ts';
+import { repoRoot } from './src/git.ts';
+import { createPorts } from './src/ports.ts';
+import { type Progress, Runner } from './src/runner.ts';
+
+type Launch = (cwd: string) => Promise<Runner>;
+
+type Holder = { runner?: Runner };
+
+const KEY = Symbol.for('pi-next-issue');
+const STATUS_KEY = 'next-issue';
+
+function holder(): Holder {
+  const store = globalThis as Record<symbol, Holder | undefined>;
+  store[KEY] ??= {};
+  return store[KEY];
+}
+
+function duration(ms: number): string {
+  const seconds = Math.max(0, Math.floor(ms / 1000));
+  const minutes = Math.floor(seconds / 60);
+  return minutes > 0 ? `${minutes}m${String(seconds % 60).padStart(2, '0')}s` : `${seconds}s`;
+}
+
+function outcomes(progress: Progress): string {
+  const merged = progress.handled.filter((item) => item.outcome === 'merged').length;
+  const human = progress.handled.length - merged;
+  const parts = [`${merged} merged`];
+  if (human > 0) {
+    parts.push(`${human} needs a human`);
+  }
+  return parts.join(', ');
+}
+
+export function formatStatus(progress: Progress, now: number): string {
+  switch (progress.status) {
+    case 'idle':
+      return 'next-issue · starting';
+    case 'running': {
+      if (progress.issue === undefined) {
+        return 'next-issue · looking for issues';
+      }
+      const parts = [`next-issue #${progress.issue}`, progress.stage ?? 'prepare'];
+      parts.push(`${progress.tools} tools`);
+      if (progress.issueStartedAt !== undefined) {
+        parts.push(duration(now - progress.issueStartedAt));
+      }
+      return parts.join(' · ');
+    }
+    case 'stopping':
+      return `next-issue #${progress.issue ?? '?'} · stopping`;
+    case 'stopped':
+      return `next-issue · stopped: ${outcomes(progress)}`;
+    case 'finished':
+      return `next-issue · finished: ${outcomes(progress)}`;
+    case 'failed':
+      return `next-issue · failed: ${progress.error ?? 'unknown error'}`;
+  }
+}
+
+const launchFromRepo: Launch = async (cwd) => {
+  const root = await repoRoot(cwd);
+  const config = await loadConfig(root);
+  return new Runner(await createPorts(root, config), config);
+};
+
+export function createExtension(launch: Launch) {
+  return (pi: ExtensionAPI) => {
+    let ui: ExtensionContext['ui'] | undefined;
+    let timer: ReturnType<typeof setInterval> | undefined;
+    let unsubscribe: (() => void) | undefined;
+    let handled = 0;
+    let status: Progress['status'] | undefined;
+
+    const render = () => {
+      const runner = holder().runner;
+      if (ui === undefined || runner === undefined) {
+        return;
+      }
+      const progress = runner.progress;
+      ui.setStatus(STATUS_KEY, formatStatus(progress, Date.now()));
+      const active = progress.status === 'running' && progress.lastTool !== undefined;
+      ui.setWidget(STATUS_KEY, active ? [`↳ ${progress.lastTool}`] : undefined);
+    };
+
+    const onChange = (progress: Progress) => {
+      for (const item of progress.handled.slice(handled)) {
+        ui?.notify(
+          `next-issue: #${item.issue} ${item.outcome === 'merged' ? 'merged' : 'needs a human'}`,
+          item.outcome === 'merged' ? 'info' : 'warning',
+        );
+      }
+      handled = progress.handled.length;
+      if (progress.status !== status) {
+        status = progress.status;
+        if (status === 'finished') {
+          ui?.notify('next-issue finished', 'info');
+        } else if (status === 'stopped') {
+          ui?.notify('next-issue stopped', 'info');
+        } else if (status === 'failed') {
+          ui?.notify(`next-issue failed: ${progress.error ?? 'unknown error'}`, 'error');
+        }
+      }
+      render();
+    };
+
+    const follow = (runner: Runner) => {
+      unsubscribe?.();
+      handled = runner.progress.handled.length;
+      status = runner.progress.status;
+      unsubscribe = runner.subscribe(onChange);
+      render();
+    };
+
+    const detach = () => {
+      unsubscribe?.();
+      unsubscribe = undefined;
+      if (timer !== undefined) {
+        clearInterval(timer);
+        timer = undefined;
+      }
+      ui = undefined;
+    };
+
+    pi.on('session_start', async (_event, ctx) => {
+      if (!ctx.hasUI) {
+        return;
+      }
+      ui = ctx.ui;
+      timer ??= setInterval(render, 1000);
+      timer.unref?.();
+      const runner = holder().runner;
+      if (runner !== undefined) {
+        follow(runner);
+      }
+    });
+
+    pi.on('session_shutdown', async (event) => {
+      detach();
+      if (event.reason === 'quit') {
+        holder().runner?.stop();
+      }
+    });
+
+    pi.registerCommand('next-issue', {
+      description: 'Work through the GitHub issues of this repository in the background',
+      getArgumentCompletions: (prefix) => {
+        const items = ['start', 'stop', 'status']
+          .filter((name) => name.startsWith(prefix))
+          .map((name) => ({ value: name, label: name }));
+        return items.length > 0 ? items : null;
+      },
+      handler: async (args, ctx) => {
+        const action = args.trim() || 'status';
+        const current = holder().runner;
+        const busy =
+          current?.progress.status === 'running' || current?.progress.status === 'stopping';
+        if (action === 'start') {
+          if (busy) {
+            ctx.ui.notify('next-issue is running already', 'warning');
+            return;
+          }
+          let runner: Runner;
+          try {
+            runner = await launch(ctx.cwd);
+          } catch (error) {
+            ctx.ui.notify(
+              `next-issue cannot start: ${error instanceof Error ? error.message : String(error)}`,
+              'error',
+            );
+            return;
+          }
+          holder().runner = runner;
+          if (ctx.hasUI) {
+            ui = ctx.ui;
+            follow(runner);
+          }
+          void runner.run();
+        } else if (action === 'stop') {
+          if (!busy) {
+            ctx.ui.notify('next-issue is not running', 'info');
+            return;
+          }
+          current?.stop();
+        } else if (action === 'status') {
+          ctx.ui.notify(
+            current === undefined
+              ? 'next-issue has not run yet'
+              : formatStatus(current.progress, Date.now()),
+            'info',
+          );
+        } else {
+          ctx.ui.notify('usage: /next-issue start | stop | status', 'warning');
+        }
+      },
+    });
+  };
+}
+
+export default createExtension(launchFromRepo);

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@ravshansbox/pi-next-issue",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.2",
+  "description": "Pi extension that works through GitHub issues in the background",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ravshansbox/pi-next-issue.git"
+  },
+  "homepage": "https://github.com/ravshansbox/pi-next-issue#readme",
+  "bugs": {
+    "url": "https://github.com/ravshansbox/pi-next-issue/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "github",
+    "issues"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint --deny-warnings",
+    "lint:fix": "oxlint --fix",
+    "format": "oxfmt",
+    "format:check": "oxfmt --check",
+    "test": "node --test \"test/*.test.ts\"",
+    "check": "npm run typecheck && npm run lint && npm run format:check && npm test"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.5",
+    "oxfmt": "^0.74.0",
+    "oxlint": "^1.89.0",
+    "typescript": "^7.0.2"
+  },
+  "files": [
+    "index.ts",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/agent.ts

@@ -0,0 +1,105 @@
+import { dirname, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  createAgentSession,
+  DefaultResourceLoader,
+  defineTool,
+  getAgentDir,
+  SessionManager,
+  type ToolDefinition,
+} from '@earendil-works/pi-coding-agent';
+import { Type } from 'typebox';
+import type { AgentTask, Verdict } from './runner.ts';
+
+const PACKAGE_DIR = dirname(dirname(fileURLToPath(import.meta.url)));
+
+export function isOwnExtension(path: string): boolean {
+  return path === PACKAGE_DIR || path.startsWith(PACKAGE_DIR + sep);
+}
+
+export function toolLabel(name: string, args: unknown): string {
+  const fields = (typeof args === 'object' && args !== null ? args : {}) as Record<string, unknown>;
+  const detail = [fields['command'], fields['path'], fields['file_path'], fields['pattern']].find(
+    (value) => typeof value === 'string',
+  ) as string | undefined;
+  const line = detail === undefined ? name : `${name} ${detail.split('\n')[0]}`;
+  return line.length > 80 ? `${line.slice(0, 79)}…` : line;
+}
+
+async function runSession(task: AgentTask, customTools: ToolDefinition[]): Promise<string> {
+  const agentDir = getAgentDir();
+  const resourceLoader = new DefaultResourceLoader({
+    cwd: task.cwd,
+    agentDir,
+    extensionsOverride: (base) => ({
+      ...base,
+      extensions: base.extensions.filter((extension) => !isOwnExtension(extension.resolvedPath)),
+    }),
+  });
+  await resourceLoader.reload();
+  const { session } = await createAgentSession({
+    cwd: task.cwd,
+    agentDir,
+    resourceLoader,
+    sessionManager: SessionManager.inMemory(task.cwd),
+    customTools,
+  });
+  const abort = () => void session.abort();
+  task.signal.addEventListener('abort', abort);
+  const unsubscribe = session.subscribe((event) => {
+    if (event.type === 'tool_execution_start') {
+      task.onTool(toolLabel(event.toolName, event.args));
+    }
+  });
+  try {
+    await session.bindExtensions({});
+    task.signal.throwIfAborted();
+    await session.prompt(task.prompt, { expandPromptTemplates: false });
+    task.signal.throwIfAborted();
+    const last = session.messages.findLast((message) => message.role === 'assistant');
+    if (last !== undefined && 'stopReason' in last && last.stopReason === 'error') {
+      throw new Error(`the agent failed: ${last.errorMessage ?? 'no reason given'}`);
+    }
+    return session.getLastAssistantText() ?? '';
+  } finally {
+    unsubscribe();
+    task.signal.removeEventListener('abort', abort);
+    session.dispose();
+  }
+}
+
+export function work(task: AgentTask): Promise<string> {
+  return runSession(task, []);
+}
+
+export async function review(task: AgentTask): Promise<Verdict | undefined> {
+  let verdict: Verdict | undefined;
+  const submit = defineTool({
+    name: 'submit_verdict',
+    label: 'Submit verdict',
+    description: 'Give the result of the review. Call it once, as your last action.',
+    parameters: Type.Object({
+      summary: Type.String({ description: 'Short summary of the review' }),
+      findings: Type.Array(
+        Type.Object({
+          severity: Type.Union([Type.Literal('blocking'), Type.Literal('minor')], {
+            description:
+              'blocking for a wrong result, a missing part of the issue, a regression or a broken convention; minor for taste and style',
+          }),
+          detail: Type.String({ description: 'What is wrong and where' }),
+        }),
+        { description: 'One entry per problem. Empty when nothing is wrong.' },
+      ),
+    }),
+    async execute(_toolCallId, params) {
+      verdict = { summary: params.summary, findings: params.findings };
+      return {
+        content: [{ type: 'text', text: 'Verdict saved.' }],
+        details: verdict,
+        terminate: true,
+      };
+    },
+  });
+  await runSession(task, [submit as unknown as ToolDefinition]);
+  return verdict;
+}

package/src/config.ts

@@ -0,0 +1,69 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+export type Config = {
+  remote: string;
+  maxCiFixes: number;
+  maxReviewRounds: number;
+  checkTimeoutMinutes: number;
+  diffMaxChars: number;
+  logMaxChars: number;
+};
+
+export const CONFIG_FILE = join('.pi', 'next-issue.json');
+
+const DEFAULTS: Config = {
+  remote: 'origin',
+  maxCiFixes: 3,
+  maxReviewRounds: 3,
+  checkTimeoutMinutes: 30,
+  diffMaxChars: 60000,
+  logMaxChars: 20000,
+};
+
+const LEAST: Record<Exclude<keyof Config, 'remote'>, number> = {
+  maxCiFixes: 0,
+  maxReviewRounds: 1,
+  checkTimeoutMinutes: 1,
+  diffMaxChars: 1,
+  logMaxChars: 1,
+};
+
+export async function loadConfig(root: string): Promise<Config> {
+  let raw: string;
+  try {
+    raw = await readFile(join(root, CONFIG_FILE), 'utf8');
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return { ...DEFAULTS };
+    }
+    throw error;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`${CONFIG_FILE} is not valid JSON`);
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`${CONFIG_FILE} must hold an object`);
+  }
+  const config: Config = { ...DEFAULTS };
+  for (const [key, value] of Object.entries(parsed)) {
+    if (key === 'remote') {
+      if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`${CONFIG_FILE}: remote must be text that is not empty`);
+      }
+      config.remote = value;
+    } else if (key in LEAST) {
+      const least = LEAST[key as keyof typeof LEAST];
+      if (typeof value !== 'number' || !Number.isInteger(value) || value < least) {
+        throw new Error(`${CONFIG_FILE}: ${key} must be a whole number of ${least} or more`);
+      }
+      config[key as keyof typeof LEAST] = value;
+    } else {
+      throw new Error(`${CONFIG_FILE} holds an unknown field: ${key}`);
+    }
+  }
+  return config;
+}

package/src/exec.ts

@@ -0,0 +1,34 @@
+import { spawn } from 'node:child_process';
+
+export type Result = { code: number; stdout: string; stderr: string };
+
+export type RunOptions = { cwd: string; input?: string; signal?: AbortSignal };
+
+export function run(command: string, args: string[], options: RunOptions): Promise<Result> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      stdio: [options.input === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'],
+      ...(options.signal === undefined ? {} : { signal: options.signal }),
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout?.setEncoding('utf8').on('data', (chunk: string) => (stdout += chunk));
+    child.stderr?.setEncoding('utf8').on('data', (chunk: string) => (stderr += chunk));
+    child.on('error', reject);
+    child.on('close', (code) => resolve({ code: code ?? 1, stdout, stderr }));
+    if (options.input !== undefined) {
+      child.stdin?.on('error', () => {});
+      child.stdin?.end(options.input);
+    }
+  });
+}
+
+export async function must(command: string, args: string[], options: RunOptions): Promise<string> {
+  const result = await run(command, args, options);
+  if (result.code !== 0) {
+    const detail = (result.stderr.trim() || result.stdout.trim()).slice(-2000);
+    throw new Error(`${command} ${args.join(' ')} failed with code ${result.code}: ${detail}`);
+  }
+  return result.stdout.trim();
+}

package/src/git.ts

@@ -0,0 +1,107 @@
+import { appendFile, readFile } from 'node:fs/promises';
+import { isAbsolute, join } from 'node:path';
+import { must, run } from './exec.ts';
+
+export const WORKTREE_DIR = '.worktrees';
+
+export async function repoRoot(cwd: string): Promise<string> {
+  return must('git', ['rev-parse', '--show-toplevel'], { cwd });
+}
+
+export function parseRemote(url: string): string {
+  const match = /[/:]([^/:]+)\/([^/]+?)(?:\.git)?\/?$/.exec(url.trim());
+  if (match === null) {
+    throw new Error(`cannot read the owner and name from the git remote ${url}`);
+  }
+  return `${match[1]}/${match[2]}`;
+}
+
+export async function remoteSlug(root: string, remote: string): Promise<string> {
+  return parseRemote(await must('git', ['remote', 'get-url', remote], { cwd: root }));
+}
+
+async function ignoreWorktrees(root: string): Promise<void> {
+  const common = await must('git', ['rev-parse', '--git-common-dir'], { cwd: root });
+  const file = join(isAbsolute(common) ? common : join(root, common), 'info', 'exclude');
+  const current = await readFile(file, 'utf8').catch(() => '');
+  if (!current.split('\n').some((line) => line.trim() === `/${WORKTREE_DIR}/`)) {
+    const gap = current.length === 0 || current.endsWith('\n') ? '' : '\n';
+    await appendFile(file, `${gap}/${WORKTREE_DIR}/\n`);
+  }
+}
+
+async function findWorktree(root: string, branch: string): Promise<string | undefined> {
+  const list = await must('git', ['worktree', 'list', '--porcelain'], { cwd: root });
+  const entry = list
+    .split('\n\n')
+    .map((block) => block.split('\n'))
+    .find((lines) => lines.includes(`branch refs/heads/${branch}`));
+  return entry?.find((line) => line.startsWith('worktree '))?.slice('worktree '.length);
+}
+
+async function hasRef(root: string, ref: string): Promise<boolean> {
+  return (await run('git', ['rev-parse', '--verify', '--quiet', ref], { cwd: root })).code === 0;
+}
+
+export async function worktree(
+  root: string,
+  remote: string,
+  base: string,
+  issue: number,
+  branch: string,
+): Promise<string> {
+  await ignoreWorktrees(root);
+  await must('git', ['fetch', remote], { cwd: root });
+  await must('git', ['worktree', 'prune'], { cwd: root });
+  const existing = await findWorktree(root, branch);
+  if (existing !== undefined) {
+    return existing;
+  }
+  const path = join(root, WORKTREE_DIR, String(issue));
+  if (await hasRef(root, `refs/heads/${branch}`)) {
+    await must('git', ['worktree', 'add', path, branch], { cwd: root });
+  } else {
+    const upstream = `${remote}/${branch}`;
+    const start = (await hasRef(root, `refs/remotes/${upstream}`)) ? upstream : `${remote}/${base}`;
+    await must('git', ['worktree', 'add', '--no-track', '-b', branch, path, start], { cwd: root });
+  }
+  return path;
+}
+
+export async function commit(cwd: string, message: string): Promise<boolean> {
+  if ((await must('git', ['status', '--porcelain'], { cwd })).length === 0) {
+    return false;
+  }
+  await must('git', ['add', '-A'], { cwd });
+  await must('git', ['commit', '-m', message], { cwd });
+  return true;
+}
+
+export async function push(cwd: string, remote: string, branch: string): Promise<void> {
+  await must('git', ['push', '-u', remote, `HEAD:refs/heads/${branch}`], { cwd });
+}
+
+export async function discard(cwd: string): Promise<void> {
+  await must('git', ['reset', '--hard', '@{upstream}'], { cwd });
+  await must('git', ['clean', '-fd'], { cwd });
+}
+
+export async function diff(cwd: string, remote: string, base: string): Promise<string> {
+  await must('git', ['fetch', remote, base], { cwd });
+  return must('git', ['diff', `${remote}/${base}...HEAD`], { cwd });
+}
+
+export async function head(cwd: string): Promise<string> {
+  return must('git', ['rev-parse', 'HEAD'], { cwd });
+}
+
+export async function cleanup(
+  root: string,
+  remote: string,
+  branch: string,
+  path: string,
+): Promise<void> {
+  await run('git', ['worktree', 'remove', '--force', path], { cwd: root });
+  await run('git', ['branch', '-D', branch], { cwd: root });
+  await run('git', ['push', remote, '--delete', branch], { cwd: root });
+}