@izkac/forgekit 0.3.13 → 0.3.15

package/bin/forge.mjs

@@ -9,6 +9,7 @@
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
+import { findRepoRoot } from '../src/repo-root.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const SRC = path.join(__dirname, '..', 'src');
@@ -19,6 +20,7 @@ const COMMANDS = {
   status: { script: 'session-status.mjs' },
   cleanup: { script: 'cleanup-sessions.mjs' },
   phase: { script: 'set-phase.mjs', aliases: ['set-phase'] },
+  checkpoint: { script: 'checkpoint.mjs', aliases: ['ckpt'] },
   prefs: { script: 'set-prefs.mjs' },
   models: { script: 'set-models.mjs' },
   'resolve-model': { script: 'resolve-model.mjs' },
@@ -49,6 +51,7 @@ Commands:
   new <slug>              Create a Forge session under .forge/
   status                  Show active session
   phase <phase>           Update session phase
+  checkpoint              Commit the group's work (opt-in; never pushes)
   cleanup                 Prune old/finished sessions
   prefs [pace]            Get/set pace preferences
   models [lane]           Get/set subagent billing (included|metered)
@@ -93,12 +96,23 @@ if (!entry) {
   process.exit(1);
 }
 
-const args = [...(entry.prependArgs ?? []), ...rest];
+// Every subcommand is project-scoped, so run it from the project root rather
+// than wherever the shell happens to sit: `cd crates && forge status` used to
+// report "no session" and `forge new` would have written a second .forge tree
+// inside the workspace. An explicit relative `--cwd` still means what the
+// caller typed, so absolutize it against the invocation dir first.
+const invokedFrom = process.cwd();
+const repoRoot = findRepoRoot(invokedFrom);
+const args = [...(entry.prependArgs ?? []), ...rest].map((arg, i, all) =>
+  i > 0 && all[i - 1] === '--cwd' && !path.isAbsolute(arg) ? path.resolve(invokedFrom, arg) : arg,
+);
+
 const r = spawnSync(process.execPath, [path.join(SRC, entry.script), ...args], {
   stdio: 'inherit',
-  cwd: process.cwd(),
+  cwd: repoRoot,
   env: {
     ...process.env,
+    FORGE_INVOKED_FROM: invokedFrom,
     FORGEKIT_ROOT: path.resolve(__dirname, '..', '..', '..'),
     FORGEKIT_CLI_ROOT: path.resolve(__dirname, '..'),
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@izkac/forgekit",
-  "version": "0.3.13",
+  "version": "0.3.15",
   "description": "Forgekit CLIs — forgekit (install), forge (workflow), review (code review)",
   "type": "module",
   "bin": {
@@ -16,6 +16,7 @@
   ],
   "scripts": {
     "prepack": "node scripts/prepack.mjs",
+    "prepublishOnly": "npm run lint && npm test",
     "test": "node scripts/run-tests.mjs",
     "lint": "eslint src bin scripts"
   },

package/src/checkpoint.mjs

@@ -0,0 +1,357 @@
+#!/usr/bin/env node
+/**
+ * `forge checkpoint` — an authorized, boring commit at a task-group boundary.
+ *
+ * Forge forbids autonomous commits, which is right, but the missing half was
+ * an *explicit* one: a 32-task session accumulated 6k lines across 37 files
+ * and 18 untracked ones in a single working tree, so a stray `git checkout`
+ * could erase a day of work and every reviewer after task 1 saw a diff
+ * containing all previous tasks.
+ *
+ * Checkpoints are opt-in per project (`.forge/config.json` → `git.checkpoint`),
+ * never push, never run on the default branch unless explicitly allowed, and
+ * record the resulting sha on the session so reviewers get a real diff range.
+ *
+ * Usage:
+ *   forge checkpoint --group <name> [--tasks <ids>] [--message <subject>]
+ *   forge checkpoint --dry-run
+ *   forge checkpoint --range [--last]
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { loadSession, readActive, REPO_ROOT, saveSession } from './lib.mjs';
+import { loadProjectConfig } from './config.mjs';
+
+const MODES = ['off', 'per-group', 'per-task'];
+const DEFAULT_BRANCHES = new Set(['main', 'master']);
+
+function usage() {
+  process.stderr.write(
+    `Usage:
+  forge checkpoint --group <name> [--tasks <ids>] [--message <subject>]
+  forge checkpoint --dry-run                 what would be committed
+  forge checkpoint --range [--last]          diff range for a reviewer brief
+
+Enable per project in .forge/config.json:
+  { "git": { "checkpoint": "per-group" } }   # or "per-task", "off" (default)
+`,
+  );
+}
+
+/**
+ * @param {string} cwd
+ * @param {string[]} args
+ */
+function git(cwd, args) {
+  return spawnSync('git', args, { cwd, encoding: 'utf8' });
+}
+
+/**
+ * @param {string} cwd
+ * @param {string[]} args
+ */
+function gitOut(cwd, args) {
+  return gitOutRaw(cwd, args).trim();
+}
+
+/**
+ * Untrimmed stdout. `git status --porcelain` encodes the unstaged marker as a
+ * leading space, so trimming shifts every path in the first line by one.
+ *
+ * @param {string} cwd
+ * @param {string[]} args
+ */
+function gitOutRaw(cwd, args) {
+  const r = git(cwd, args);
+  if (r.status !== 0) throw new Error(`git ${args.join(' ')} failed: ${r.stderr.trim()}`);
+  return r.stdout;
+}
+
+function fail(message, payload = null) {
+  process.stderr.write(`${message}\n`);
+  if (payload) process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+  process.exit(1);
+}
+
+function emit(payload) {
+  process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+}
+
+/**
+ * Session bookkeeping is not product work: `.forge/` churns on every phase
+ * write (including this command's own), so committing it would make every
+ * checkpoint dirty the tree again and bury the real diff in scratch.
+ */
+const EXCLUDE_SCRATCH = ['--', '.', ':(exclude).forge'];
+
+/**
+ * Working-tree entries with their porcelain status, including untracked ones —
+ * agent work is mostly new files, so a tracked-only view would miss most of it.
+ *
+ * @param {string} cwd
+ * @returns {{ path: string, status: string, untracked: boolean }[]}
+ */
+export function pendingEntries(cwd) {
+  const porcelain = gitOutRaw(cwd, [
+    'status',
+    '--porcelain',
+    '--untracked-files=all',
+    ...EXCLUDE_SCRATCH,
+  ]);
+  if (!porcelain) return [];
+  return porcelain
+    .split('\n')
+    .filter((line) => line.length > 3)
+    .map((line) => {
+      const status = line.slice(0, 2);
+      let file = line.slice(3);
+      // Renames read `old -> new`; the new path is what landed.
+      if (file.includes(' -> ')) file = file.split(' -> ')[1];
+      return { path: file.replace(/^"|"$/g, '').trim(), status, untracked: status === '??' };
+    })
+    .filter((e) => e.path)
+    .sort((a, b) => a.path.localeCompare(b.path));
+}
+
+/**
+ * @param {string} cwd
+ * @returns {string[]}
+ */
+export function pendingFiles(cwd) {
+  return pendingEntries(cwd).map((e) => e.path);
+}
+
+/**
+ * What a reviewer should actually read.
+ *
+ * A group review runs *before* that group's checkpoint, so HEAD is still the
+ * previous checkpoint and `<base>..HEAD` is empty — the reviewer would be
+ * handed a range containing nothing. While the tree is dirty the target is the
+ * working tree instead, and untracked files are named because `git diff` never
+ * shows them.
+ *
+ * @param {string} base
+ * @param {{ path: string, untracked: boolean }[]} pending
+ * @returns {string}
+ */
+export function reviewTargetFor(base, pending) {
+  if (pending.length === 0) return `${base}..HEAD`;
+  const untracked = pending.filter((e) => e.untracked).map((e) => e.path);
+  const target = `git diff ${base} (working tree vs the last checkpoint)`;
+  if (untracked.length === 0) return target;
+  return `${target} — plus ${untracked.length} untracked file(s) that no diff shows, read them in full: ${untracked.join(', ')}`;
+}
+
+/**
+ * Git operations that must finish before anything else touches the index.
+ * @param {string} cwd
+ */
+function inProgressOperation(cwd) {
+  const gitDir = path.join(cwd, '.git');
+  for (const [file, label] of [
+    ['MERGE_HEAD', 'merge'],
+    ['CHERRY_PICK_HEAD', 'cherry-pick'],
+    ['REVERT_HEAD', 'revert'],
+    ['rebase-merge', 'rebase'],
+    ['rebase-apply', 'rebase'],
+    ['BISECT_LOG', 'bisect'],
+  ]) {
+    if (fs.existsSync(path.join(gitDir, file))) return label;
+  }
+  return null;
+}
+
+/**
+ * @param {{ slug?: string, openspecChange?: string }} session
+ * @param {{ group?: string, tasks?: string, message?: string }} opts
+ */
+export function checkpointSubject(session, opts) {
+  if (opts.message) return opts.message;
+  const scope = session.openspecChange || session.slug || 'session';
+  const label = [opts.group, opts.tasks && `tasks ${opts.tasks}`].filter(Boolean).join(' ');
+  return `forge(${scope}): checkpoint${label ? ` — ${label}` : ''}`;
+}
+
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) {
+  usage();
+  process.exit(0);
+}
+
+/** @type {{ group?: string, tasks?: string, message?: string }} */
+const opts = {};
+let dryRun = false;
+let rangeOnly = false;
+let sinceLast = false;
+let allowDefaultBranch = false;
+let sessionId = null;
+for (let i = 0; i < args.length; i += 1) {
+  const a = args[i];
+  if (a === '--group' && args[i + 1]) opts.group = args[(i += 1)];
+  else if (a === '--tasks' && args[i + 1]) opts.tasks = args[(i += 1)];
+  else if ((a === '--message' || a === '-m') && args[i + 1]) opts.message = args[(i += 1)];
+  else if (a === '--session' && args[i + 1]) sessionId = args[(i += 1)];
+  else if (a === '--dry-run') dryRun = true;
+  else if (a === '--range') rangeOnly = true;
+  else if (a === '--last') sinceLast = true;
+  else if (a === '--allow-default-branch') allowDefaultBranch = true;
+  else {
+    usage();
+    fail(`Unknown argument: ${a}`);
+  }
+}
+
+const cwd = REPO_ROOT;
+
+if (!sessionId) {
+  const active = readActive();
+  if (!active?.sessionId) fail('No active Forge session — run forge new <slug> first.');
+  sessionId = active.sessionId;
+}
+const { dir: sessionDir, session } = loadSession(sessionId);
+
+const checkpoints = Array.isArray(session.checkpoints) ? session.checkpoints : [];
+
+// --- `--range`: what a reviewer should read, no repo mutation ---
+if (rangeOnly) {
+  const base = sinceLast && checkpoints.length ? checkpoints[checkpoints.length - 1].sha : session.baseCommit;
+  if (!base) {
+    emit({
+      ok: false,
+      range: null,
+      base: null,
+      checkpoints: checkpoints.length,
+      note: 'No base commit recorded — this session started before checkpoints, so reviewers read the working tree (git diff).',
+    });
+    process.exit(1);
+  }
+  let pending = [];
+  try {
+    pending = pendingEntries(cwd);
+  } catch {
+    /* not a git repo / unreadable — fall back to the bare commit range */
+  }
+  emit({
+    ok: true,
+    base,
+    range: `${base}..HEAD`,
+    dirty: pending.length > 0,
+    pending: pending.map((e) => e.path),
+    untracked: pending.filter((e) => e.untracked).map((e) => e.path),
+    reviewTarget: reviewTargetFor(base, pending),
+    checkpoints: checkpoints.length,
+    note: 'Pass reviewTarget as {DIFF_RANGE}. `range` is the commit range only — it is empty while the group under review is still uncommitted.',
+  });
+  process.exit(0);
+}
+
+// --- gates ---
+const config = loadProjectConfig(cwd);
+const mode = config?.git?.checkpoint ?? 'off';
+if (!MODES.includes(mode)) {
+  fail(`Unknown git.checkpoint mode "${mode}" in .forge/config.json (expected ${MODES.join(' | ')}).`);
+}
+if (mode === 'off') {
+  fail(
+    'Checkpoints are off for this project. Enable with .forge/config.json → { "git": { "checkpoint": "per-group" } }.',
+    { ok: false, reason: 'git.checkpoint is "off" — checkpoints disabled for this project' },
+  );
+}
+
+if (!fs.existsSync(path.join(cwd, '.git'))) {
+  fail(`Not a git repository: ${cwd} — nothing to checkpoint.`, { ok: false, reason: 'not a git repo' });
+}
+
+const busy = inProgressOperation(cwd);
+if (busy) {
+  fail(`A ${busy} is in progress — finish it before checkpointing.`, { ok: false, reason: `${busy} in progress` });
+}
+
+let branch;
+try {
+  branch = gitOut(cwd, ['rev-parse', '--abbrev-ref', 'HEAD']);
+} catch (err) {
+  fail(`Could not read the current branch: ${err instanceof Error ? err.message : err}`);
+}
+if (DEFAULT_BRANCHES.has(branch) && !allowDefaultBranch && config?.git?.allowDefaultBranch !== true) {
+  fail(
+    `Refusing to checkpoint on the default branch "${branch}". Forge work belongs on a branch — create one, or pass --allow-default-branch (or set git.allowDefaultBranch: true) if this project really commits to ${branch}.`,
+    { ok: false, reason: `default branch "${branch}"` },
+  );
+}
+
+// --- what would land ---
+let files;
+try {
+  files = pendingFiles(cwd);
+} catch (err) {
+  fail(`Could not read the working tree: ${err instanceof Error ? err.message : err}`);
+}
+
+const subject = checkpointSubject(session, opts);
+
+if (files.length === 0) {
+  emit({
+    ok: true,
+    committed: false,
+    reason: 'nothing to checkpoint — working tree is clean',
+    branch,
+    range: session.baseCommit ? `${session.baseCommit}..HEAD` : null,
+  });
+  process.exit(0);
+}
+
+if (dryRun) {
+  emit({ ok: true, committed: false, dryRun: true, branch, subject, files });
+  process.exit(0);
+}
+
+// --- commit (never push) ---
+const prev = checkpoints.length ? checkpoints[checkpoints.length - 1].sha : null;
+try {
+  gitOut(cwd, ['add', '-A', ...EXCLUDE_SCRATCH]);
+} catch (err) {
+  fail(`git add failed: ${err instanceof Error ? err.message : err}`);
+}
+const commit = git(cwd, ['commit', '-m', subject, '--no-verify']);
+if (commit.status !== 0) {
+  fail(`git commit failed: ${commit.stderr.trim() || commit.stdout.trim()}`);
+}
+const sha = gitOut(cwd, ['rev-parse', 'HEAD']);
+
+// A session created before checkpoints existed has no base; this commit's
+// parent is the closest honest answer.
+if (!session.baseCommit) {
+  try {
+    session.baseCommit = gitOut(cwd, ['rev-parse', `${sha}^`]);
+  } catch {
+    session.baseCommit = sha; // root commit — nothing before it
+  }
+}
+if (!session.branch) session.branch = branch;
+
+checkpoints.push({
+  sha,
+  subject,
+  group: opts.group ?? null,
+  tasks: opts.tasks ?? null,
+  files: files.length,
+  at: new Date().toISOString(),
+});
+session.checkpoints = checkpoints;
+saveSession(sessionDir, session);
+
+emit({
+  ok: true,
+  committed: true,
+  sha,
+  subject,
+  branch,
+  files,
+  range: `${session.baseCommit}..HEAD`,
+  groupRange: prev ? `${prev}..${sha}` : `${session.baseCommit}..${sha}`,
+  pushed: false,
+  note: 'Checkpoints never push. Pass groupRange as {DIFF_RANGE} to the group reviewer.',
+});

package/src/checkpoint.test.mjs

@@ -0,0 +1,252 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { tmpdir } from 'node:os';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const SRC = path.dirname(fileURLToPath(import.meta.url));
+const CHECKPOINT = path.join(SRC, 'checkpoint.mjs');
+
+function tmp(prefix) {
+  return fs.realpathSync(fs.mkdtempSync(path.join(tmpdir(), prefix)));
+}
+
+function git(cwd, ...args) {
+  const r = spawnSync('git', args, { cwd, encoding: 'utf8' });
+  if (r.status !== 0) throw new Error(`git ${args.join(' ')}: ${r.stderr}`);
+  return r.stdout.trim();
+}
+
+/**
+ * Git project on a feature branch with one commit, a Forge session, and
+ * uncommitted work — the shape of an implement phase at a group boundary.
+ */
+function makeProject({ branch = 'feature-x', config = { git: { checkpoint: 'per-group' } } } = {}) {
+  const cwd = tmp('forge-ckpt-');
+  git(cwd, 'init', '-q', '-b', 'main');
+  git(cwd, 'config', 'user.email', 'test@example.com');
+  git(cwd, 'config', 'user.name', 'Test');
+  fs.writeFileSync(path.join(cwd, 'README.md'), '# base\n', 'utf8');
+  git(cwd, 'add', '-A');
+  git(cwd, 'commit', '-q', '-m', 'base');
+  const baseSha = git(cwd, 'rev-parse', 'HEAD');
+  if (branch !== 'main') git(cwd, 'checkout', '-q', '-b', branch);
+
+  const sessionDir = path.join(cwd, '.forge', 'sessions', 's1');
+  fs.mkdirSync(sessionDir, { recursive: true });
+  const now = new Date().toISOString();
+  fs.writeFileSync(
+    path.join(sessionDir, 'session.json'),
+    `${JSON.stringify({
+      id: 's1',
+      slug: 'phase-1',
+      createdAt: now,
+      updatedAt: now,
+      phase: 'implement',
+      planType: 'specs',
+      openspecChange: 'phase-1',
+      tasksTotal: 8,
+      tasksComplete: 4,
+      baseCommit: baseSha,
+      branch,
+    })}\n`,
+    'utf8',
+  );
+  fs.writeFileSync(
+    path.join(cwd, '.forge', 'active.json'),
+    `${JSON.stringify({ sessionId: 's1' })}\n`,
+    'utf8',
+  );
+  if (config) {
+    fs.writeFileSync(
+      path.join(cwd, '.forge', 'config.json'),
+      `${JSON.stringify(config)}\n`,
+      'utf8',
+    );
+  }
+  // Agent work: one edit, one new file.
+  fs.appendFileSync(path.join(cwd, 'README.md'), 'edited by task 1.1\n');
+  fs.writeFileSync(path.join(cwd, 'new-module.mjs'), 'export const x = 1;\n', 'utf8');
+  return { cwd, sessionDir, baseSha };
+}
+
+function run(cwd, args = []) {
+  const env = { ...process.env, FORGEKIT_FLEET_DIR: path.join(tmp('ckpt-fleet-'), 's') };
+  try {
+    const stdout = execFileSync(process.execPath, [CHECKPOINT, ...args], { cwd, env });
+    return { status: 0, out: JSON.parse(stdout.toString()), stderr: '' };
+  } catch (err) {
+    let out = null;
+    try {
+      out = JSON.parse(String(err.stdout));
+    } catch {
+      /* non-JSON failure */
+    }
+    return { status: err.status, out, stderr: String(err.stderr) };
+  }
+}
+
+function readSession(sessionDir) {
+  return JSON.parse(fs.readFileSync(path.join(sessionDir, 'session.json'), 'utf8'));
+}
+
+test('checkpoint commits the working tree and records the commit on the session', () => {
+  const { cwd, sessionDir, baseSha } = makeProject();
+
+  const { status, out } = run(cwd, ['--group', 'group-02-testkit', '--tasks', '2.1-2.4']);
+  assert.equal(status, 0);
+  assert.equal(out.ok, true);
+  assert.equal(out.committed, true);
+  assert.match(out.subject, /phase-1/);
+  assert.match(out.subject, /group-02-testkit/);
+  // Both the edit and the untracked file are in — agent work is mostly new files.
+  assert.deepEqual(out.files.sort(), ['README.md', 'new-module.mjs']);
+
+  // Product files are all in; session scratch is deliberately left out, so a
+  // checkpoint cannot bury the diff under .forge churn (or dirty the tree
+  // again with its own session write).
+  assert.equal(
+    git(cwd, 'status', '--porcelain', '--', '.', ':(exclude).forge'),
+    '',
+    'no product file is left uncommitted',
+  );
+  assert.equal(
+    git(cwd, 'show', '--name-only', '--format=', 'HEAD').split('\n').some((f) => f.startsWith('.forge')),
+    false,
+    'session scratch is never committed by a checkpoint',
+  );
+  const session = readSession(sessionDir);
+  assert.equal(session.checkpoints.length, 1);
+  assert.equal(session.checkpoints[0].sha, git(cwd, 'rev-parse', 'HEAD'));
+  assert.equal(session.checkpoints[0].group, 'group-02-testkit');
+  assert.equal(session.checkpoints[0].tasks, '2.1-2.4');
+  // The range a reviewer needs: everything this session has produced.
+  assert.equal(out.range, `${baseSha}..HEAD`);
+});
+
+test('a second checkpoint reports the range covering only the new group', () => {
+  const { cwd, sessionDir } = makeProject();
+  const first = run(cwd, ['--group', 'group-01']);
+  assert.equal(first.status, 0);
+
+  fs.writeFileSync(path.join(cwd, 'second.mjs'), 'export const y = 2;\n', 'utf8');
+  const second = run(cwd, ['--group', 'group-02']);
+
+  assert.equal(second.status, 0);
+  assert.equal(second.out.groupRange, `${first.out.sha}..${second.out.sha}`);
+  assert.deepEqual(second.out.files, ['second.mjs']);
+  assert.equal(readSession(sessionDir).checkpoints.length, 2);
+});
+
+test('a clean tree is not an error and creates no empty commit', () => {
+  const { cwd } = makeProject();
+  run(cwd, ['--group', 'group-01']);
+  const head = git(cwd, 'rev-parse', 'HEAD');
+
+  const { status, out } = run(cwd, ['--group', 'group-02']);
+  assert.equal(status, 0);
+  assert.equal(out.ok, true);
+  assert.equal(out.committed, false);
+  assert.match(out.reason, /nothing to checkpoint/i);
+  assert.equal(git(cwd, 'rev-parse', 'HEAD'), head, 'no empty commit');
+});
+
+test('--dry-run reports what would be committed and commits nothing', () => {
+  const { cwd, sessionDir } = makeProject();
+  const head = git(cwd, 'rev-parse', 'HEAD');
+
+  const { status, out } = run(cwd, ['--group', 'group-01', '--dry-run']);
+  assert.equal(status, 0);
+  assert.equal(out.committed, false);
+  assert.deepEqual(out.files.sort(), ['README.md', 'new-module.mjs']);
+  assert.equal(git(cwd, 'rev-parse', 'HEAD'), head);
+  assert.equal(readSession(sessionDir).checkpoints, undefined);
+});
+
+test('checkpoints are refused on the default branch unless explicitly allowed', () => {
+  // Forge work belongs on a branch; committing straight to main is the one
+  // mistake an automated commit must never make on its own.
+  const { cwd } = makeProject({ branch: 'main' });
+
+  const refused = run(cwd, ['--group', 'group-01']);
+  assert.equal(refused.status, 1);
+  assert.match(refused.stderr, /default branch/i);
+  assert.equal(git(cwd, 'status', '--porcelain') === '', false, 'work is left untouched');
+
+  const allowed = run(cwd, ['--group', 'group-01', '--allow-default-branch']);
+  assert.equal(allowed.status, 0);
+  assert.equal(allowed.out.committed, true);
+});
+
+test('checkpoints are off unless the project opts in', () => {
+  const { cwd } = makeProject({ config: {} });
+  const { status, out, stderr } = run(cwd, ['--group', 'group-01']);
+  assert.equal(status, 1);
+  assert.equal(out?.ok, false);
+  assert.match(`${stderr}${out?.reason ?? ''}`, /checkpoint/i);
+  assert.match(`${stderr}${out?.reason ?? ''}`, /git\.checkpoint/);
+});
+
+test('an in-progress merge blocks a checkpoint', () => {
+  const { cwd } = makeProject();
+  fs.writeFileSync(path.join(cwd, '.git', 'MERGE_HEAD'), `${'0'.repeat(40)}\n`, 'utf8');
+
+  const { status, stderr } = run(cwd, ['--group', 'group-01']);
+  assert.equal(status, 1);
+  assert.match(stderr, /merge|rebase|in progress/i);
+});
+
+test('--range --last targets the working tree while the group is still uncommitted', () => {
+  // The group review runs BEFORE its checkpoint, so at review time the group's
+  // work is uncommitted and HEAD is still the previous checkpoint: a
+  // `<sha>..HEAD` range would be empty and the reviewer would read nothing.
+  const { cwd } = makeProject();
+  const first = run(cwd, ['--group', 'group-01']);
+  fs.writeFileSync(path.join(cwd, 'second.mjs'), 'export const y = 2;\n', 'utf8');
+  fs.appendFileSync(path.join(cwd, 'README.md'), 'more\n');
+
+  const { status, out } = run(cwd, ['--range', '--last']);
+  assert.equal(status, 0);
+  assert.equal(out.base, first.out.sha);
+  assert.equal(out.dirty, true);
+  // Untracked files are most of what an agent writes and never appear in a
+  // plain `git diff`, so they must be called out by name.
+  assert.deepEqual(out.untracked, ['second.mjs']);
+  assert.match(out.reviewTarget, new RegExp(`git diff ${first.out.sha}`));
+  assert.match(out.reviewTarget, /second\.mjs/);
+});
+
+test('--range --last is a plain commit range once the group is checkpointed', () => {
+  const { cwd } = makeProject();
+  run(cwd, ['--group', 'group-01']);
+  fs.writeFileSync(path.join(cwd, 'second.mjs'), 'export const y = 2;\n', 'utf8');
+  const second = run(cwd, ['--group', 'group-02']);
+
+  const { out } = run(cwd, ['--range', '--last']);
+  assert.equal(out.dirty, false);
+  assert.deepEqual(out.untracked, []);
+  assert.equal(out.base, second.out.sha);
+  assert.equal(out.reviewTarget, `${second.out.sha}..HEAD`);
+});
+
+test('--range without --last spans the whole session from its base commit', () => {
+  const { cwd, baseSha } = makeProject();
+  run(cwd, ['--group', 'group-01']);
+
+  const { out } = run(cwd, ['--range']);
+  assert.equal(out.base, baseSha);
+  assert.equal(out.range, `${baseSha}..HEAD`);
+  assert.equal(out.dirty, false);
+});
+
+test('checkpoint never pushes', () => {
+  const { cwd } = makeProject();
+  // A remote that would fail loudly if anything tried to reach it.
+  git(cwd, 'remote', 'add', 'origin', 'file:///nonexistent-remote.git');
+  const { status, out } = run(cwd, ['--group', 'group-01']);
+  assert.equal(status, 0);
+  assert.equal(out.committed, true);
+  assert.equal(git(cwd, 'log', '--oneline', '-1', '--format=%s').includes('phase-1'), true);
+});