@jakobm/peacekeeper 0.0.0-stage → 0.12.1

package/scripts/checkpoint-codex-changes.js

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+
+/**
+ * Commit the current Codex worktree and push to configured remotes.
+ *
+ * Explicit checkpoint remotes also receive new branches. Without that setting,
+ * only an existing branch on the configured remote is pushed. Failures are recorded inside
+ * the worktree's Git metadata so the Stop hook can keep them visible.
+ */
+
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+const { isPrimaryWorktree } = require('./log-script-invocation.js');
+const { projectConfig } = require('./project-config');
+
+function runGit(args, options = {}) {
+  const result = spawnSync('git', args, {
+    cwd: options.cwd,
+    encoding: 'utf8',
+    stdio: options.stdio || ['ignore', 'pipe', 'pipe'],
+  });
+
+  if (result.status !== 0) {
+    const detail = result.stderr?.trim() || result.stdout?.trim();
+    throw new Error(detail || `git ${args.join(' ')} failed`);
+  }
+
+  return result.stdout?.trim() || '';
+}
+
+function tryGit(args, cwd) {
+  return spawnSync('git', args, {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+}
+
+function markerPath(repositoryRoot) {
+  const gitDirectory = runGit([
+    'rev-parse',
+    '--path-format=absolute',
+    '--git-dir',
+  ], { cwd: repositoryRoot });
+
+  return path.join(gitDirectory, 'codex-checkpoint-error.json');
+}
+
+function writeFailureMarker(repositoryRoot, error, branch) {
+  const marker = markerPath(repositoryRoot);
+  fs.writeFileSync(marker, `${JSON.stringify({
+    branch: branch || null,
+    error: error.message,
+    timestamp: new Date().toISOString(),
+  }, null, 2)}\n`);
+}
+
+function clearFailureMarker(repositoryRoot) {
+  fs.rmSync(markerPath(repositoryRoot), { force: true });
+}
+
+function remoteBranchExists(repositoryRoot, branch) {
+  const { remote } = projectConfig(repositoryRoot).git;
+  const result = tryGit([
+    'ls-remote',
+    '--exit-code',
+    '--heads',
+    remote,
+    `refs/heads/${branch}`,
+  ], repositoryRoot);
+
+  if (result.status === 0) {
+    return true;
+  }
+  if (result.status === 2) {
+    return false;
+  }
+
+  const detail = result.stderr?.trim() || result.stdout?.trim();
+  throw new Error(detail || `could not inspect branches on ${remote}`);
+}
+
+function validateMessage(subject, bodyParagraphs) {
+  if (typeof subject !== 'string' || subject.trim() === '') {
+    throw new Error('a non-empty commit subject is required');
+  }
+  if (subject.includes('\n')) {
+    throw new Error('the commit subject must be a single line');
+  }
+  if (
+    !Array.isArray(bodyParagraphs)
+    || bodyParagraphs.length === 0
+    || bodyParagraphs.some((paragraph) => paragraph.trim() === '')
+  ) {
+    throw new Error('at least one non-empty commit body paragraph is required');
+  }
+
+  return {
+    bodyParagraphs: bodyParagraphs.map((paragraph) => paragraph.trim()),
+    subject: subject.trim(),
+  };
+}
+
+function parseArguments(args) {
+  let subject = null;
+  const bodyParagraphs = [];
+
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    const value = args[index + 1];
+
+    if (argument === '--subject' && value !== undefined) {
+      if (subject !== null) {
+        throw new Error('--subject may only be provided once');
+      }
+      subject = value;
+      index += 1;
+    } else if (argument === '--body' && value !== undefined) {
+      bodyParagraphs.push(value);
+      index += 1;
+    } else {
+      throw new Error(`unknown or incomplete argument: ${argument}`);
+    }
+  }
+
+  return validateMessage(subject, bodyParagraphs);
+}
+
+function checkpoint(repositoryRoot, message, log = console.log) {
+  if (isPrimaryWorktree(repositoryRoot)) {
+    throw new Error('refusing to checkpoint the primary Git worktree');
+  }
+
+  let branch = null;
+
+  try {
+    const { subject, bodyParagraphs } = validateMessage(
+      message?.subject,
+      message?.bodyParagraphs,
+    );
+
+    branch = runGit(['symbolic-ref', '--quiet', '--short', 'HEAD'], {
+      cwd: repositoryRoot,
+    });
+    const { defaultBranch, remote, checkpointPushRemotes } = projectConfig(repositoryRoot).git;
+    if (branch === defaultBranch) {
+      throw new Error(`refusing to checkpoint changes directly on ${defaultBranch}`);
+    }
+
+    const conflicts = runGit(['diff', '--name-only', '--diff-filter=U'], {
+      cwd: repositoryRoot,
+    });
+    if (conflicts !== '') {
+      throw new Error(`resolve merge conflicts before checkpointing:\n${conflicts}`);
+    }
+
+    const status = runGit(['status', '--porcelain', '--untracked-files=all'], {
+      cwd: repositoryRoot,
+    });
+    const previousFailureExists = fs.existsSync(markerPath(repositoryRoot));
+
+    if (status !== '') {
+      runGit(['add', '--all'], { cwd: repositoryRoot });
+      const commitArguments = ['commit', '--message', subject];
+      for (const paragraph of bodyParagraphs) {
+        commitArguments.push('--message', paragraph);
+      }
+      runGit(commitArguments, {
+        cwd: repositoryRoot,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+      log(`Committed ${branch}: ${subject}`);
+    } else if (!previousFailureExists) {
+      log('No changes to checkpoint.');
+      return { committed: false, pushed: false };
+    }
+
+    const pushRemotes = checkpointPushRemotes ?? (
+      remoteBranchExists(repositoryRoot, branch) ? [remote] : []
+    );
+    if (pushRemotes.length === 0) {
+      clearFailureMarker(repositoryRoot);
+      log(checkpointPushRemotes === undefined
+        ? `Kept ${branch} local because ${remote}/${branch} does not exist.`
+        : `Kept ${branch} local because checkpoint push is disabled.`);
+      return { committed: status !== '', pushed: false };
+    }
+
+    for (const pushRemote of pushRemotes) {
+      const configuredRemotes = runGit(['remote'], { cwd: repositoryRoot }).split('\n');
+      if (!configuredRemotes.includes(pushRemote)) {
+        throw new Error(`checkpoint remote ${pushRemote} is not configured in Git`);
+      }
+      runGit([
+        'push',
+        ...(remote === pushRemote ? ['--set-upstream'] : []),
+        pushRemote,
+        `HEAD:refs/heads/${branch}`,
+      ], { cwd: repositoryRoot });
+      log(`Pushed ${branch} to ${pushRemote}/${branch}.`);
+    }
+    clearFailureMarker(repositoryRoot);
+    return { committed: status !== '', pushed: true };
+  } catch (error) {
+    try {
+      writeFailureMarker(repositoryRoot, error, branch);
+    } catch {
+      // Preserve the original Git error when recording it also fails.
+    }
+    throw error;
+  }
+}
+
+function main() {
+  const repositoryRoot = runGit(['rev-parse', '--show-toplevel']);
+  const message = parseArguments(process.argv.slice(2));
+  checkpoint(repositoryRoot, message);
+}
+
+if (require.main === module) {
+  try {
+    main();
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exitCode = 1;
+  }
+}
+
+module.exports = {
+  checkpoint,
+  markerPath,
+  parseArguments,
+  remoteBranchExists,
+  validateMessage,
+};

package/scripts/checkpoint-codex-session-start.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+
+const fs = require('node:fs');
+const { checkpointInstructions } = require('./checkpoint-instructions');
+const { projectConfig } = require('./project-config');
+const { isPrimaryWorktree, logScriptInvocation } = require('./log-script-invocation');
+
+function buildResponse(event) {
+  if (event?.hook_event_name !== 'SessionStart' || typeof event.cwd !== 'string') {
+    return {};
+  }
+  if (isPrimaryWorktree(event.cwd)) return {};
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'SessionStart',
+      additionalContext: checkpointInstructions(projectConfig(event.cwd)),
+    },
+  };
+}
+
+function main() {
+  logScriptInvocation();
+  const input = fs.readFileSync(0, 'utf8').trim();
+  process.stdout.write(`${JSON.stringify(buildResponse(input === '' ? null : JSON.parse(input)))}\n`);
+}
+
+if (require.main === module) {
+  try {
+    main();
+  } catch (error) {
+    process.stdout.write(`${JSON.stringify({
+      systemMessage: `Codex checkpoint instructions failed: ${error.message}`,
+    })}\n`);
+  }
+}
+
+module.exports = { buildResponse };

package/scripts/checkpoint-codex-stop.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+
+/**
+ * Continue a stopping Codex turn once when its worktree needs a checkpoint.
+ *
+ * The continuation lets the agent use its task context to choose a meaningful
+ * English commit message instead of forcing the hook to invent one.
+ */
+
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const { markerPath } = require('./checkpoint-codex-changes.js');
+const { projectConfig } = require('./project-config');
+const { checkpointInstructions } = require('./checkpoint-instructions');
+const {
+  isPrimaryWorktree,
+  logScriptInvocation,
+} = require('./log-script-invocation.js');
+
+function runGit(args, cwd) {
+  const result = spawnSync('git', args, {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+  if (result.status !== 0) {
+    const detail = result.stderr?.trim() || result.stdout?.trim();
+    throw new Error(detail || `git ${args.join(' ')} failed`);
+  }
+
+  return result.stdout.trim();
+}
+
+function readFailure(repositoryRoot) {
+  const file = markerPath(repositoryRoot);
+  if (!fs.existsSync(file)) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return { error: 'the previous checkpoint failed' };
+  }
+}
+
+function buildResponse(event) {
+  if (event?.hook_event_name !== 'Stop' || typeof event.cwd !== 'string') {
+    return {};
+  }
+  if (isPrimaryWorktree(event.cwd)) {
+    return {};
+  }
+  const config = projectConfig(event.cwd);
+
+  const status = runGit(['status', '--porcelain', '--untracked-files=all'], event.cwd);
+  const failure = readFailure(event.cwd);
+
+  if (status === '' && !failure) {
+    return {};
+  }
+
+  if (event.stop_hook_active) {
+    const problem = failure?.error || 'uncommitted changes remain';
+    return {
+      systemMessage: `Codex checkpoint incomplete: ${problem}`,
+    };
+  }
+
+  const failureInstruction = failure
+    ? ` The previous checkpoint failed with: ${failure.error}. Resolve that failure first.`
+    : '';
+
+  return {
+    decision: 'block',
+    reason: checkpointInstructions(config)
+      + failureInstruction,
+  };
+}
+
+function main() {
+  logScriptInvocation();
+  const input = fs.readFileSync(0, 'utf8').trim();
+  const event = input === '' ? null : JSON.parse(input);
+  process.stdout.write(`${JSON.stringify(buildResponse(event))}\n`);
+}
+
+if (require.main === module) {
+  try {
+    main();
+  } catch (error) {
+    process.stdout.write(`${JSON.stringify({
+      systemMessage: `Codex checkpoint check failed: ${error.message}`,
+    })}\n`);
+  }
+}
+
+module.exports = { buildResponse };

package/scripts/checkpoint-instructions.js

@@ -0,0 +1,19 @@
+/** Shared policy delivered before work starts and when Stop requests a retry. */
+function checkpointInstructions(config) {
+  return 'This checkpoint workflow applies only in linked Git worktrees, never in the primary checkout. '
+    + 'Follow any explicit user instruction not to commit or push. If such an instruction conflicts '
+    + 'with this workflow, do not run the checkpoint command; explain that the checkpoint was skipped '
+    + 'at the user\'s request, even if a Stop hook asks for it. '
+    + 'Before the final response for a task that changed repository files, review the completed diff '
+    + 'and checkpoint the work. If HEAD is detached or the worktree is on the configured default branch '
+    + `(${config.git.defaultBranch}), first create and switch to a descriptive task branch named with the ${config.git.branchPrefix} prefix. `
+    + 'Write an English commit message with a concise, descriptive single-line subject and a body '
+    + 'separated from it by a blank line. The English body should explain the change using between '
+    + 'one and ten sentences. Run `npm exec --no -- peacekeeper checkpoint-codex-changes '
+    + '--subject "<subject>" --body "<body paragraph>"`; repeat `--body` for additional paragraphs when useful. '
+    + 'The command stages all changes, so do not include unrelated changes. '
+    + 'Push behavior follows the project configuration. Unless an explicit user instruction disables '
+    + 'this workflow, finish only after the checkpoint succeeds.';
+}
+
+module.exports = { checkpointInstructions };

package/scripts/cleanup-ended-session.js

@@ -0,0 +1,317 @@
+#!/usr/bin/env node
+
+/**
+ * Queue targeted cleanup for the branch used by a Codex session that ended.
+ *
+ * SessionEnd hooks have a maximum runtime of three seconds, so the hook process
+ * captures the worktree identity and launches a detached worker. The worker
+ * removes only that worktree and branch, and only when the captured branch tip
+ * is still fully merged into the configured remote default branch.
+ */
+
+const { spawn, spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+const { projectConfig } = require('./project-config');
+const {
+  applyPlan,
+  buildPlan,
+  listWorktrees,
+} = require('./cleanup-merged-branches.js');
+const {
+  isPrimaryWorktree,
+  logScriptInvocation,
+  sourceRepositoryRoot,
+} = require('./log-script-invocation.js');
+
+const LOCK_MAX_AGE_MS = 10 * 60 * 1000;
+const LOCK_WAIT_MS = 30 * 1000;
+
+function runGit(args, options = {}) {
+  const result = spawnSync('git', args, {
+    cwd: options.cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+  if (result.status !== 0) {
+    const detail = result.stderr?.trim() || result.stdout?.trim();
+    throw new Error(detail || `git ${args.join(' ')} failed`);
+  }
+
+  return result.stdout.trim();
+}
+
+function tryGit(args, cwd) {
+  const result = spawnSync('git', args, {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+  return result.status === 0 ? result.stdout.trim() : null;
+}
+
+function samePath(first, second) {
+  try {
+    return fs.realpathSync(first) === fs.realpathSync(second);
+  } catch {
+    return path.resolve(first) === path.resolve(second);
+  }
+}
+
+function captureWorktreeTarget(cwd, sessionId = null) {
+  if (typeof cwd !== 'string' || isPrimaryWorktree(cwd)) {
+    return null;
+  }
+  const { defaultBranch } = projectConfig(cwd).git;
+
+  const branch = tryGit(['symbolic-ref', '--quiet', '--short', 'HEAD'], cwd);
+  if (!branch || branch === defaultBranch) {
+    return null;
+  }
+
+  const objectId = runGit(['rev-parse', `refs/heads/${branch}`], { cwd });
+  const worktrees = listWorktrees(cwd);
+  const sessionWorktree = worktrees.find((item) => samePath(item.path, cwd));
+
+  if (!sessionWorktree || sessionWorktree.branch !== `refs/heads/${branch}`) {
+    return null;
+  }
+
+  const commonGitDirectory = runGit([
+    'rev-parse',
+    '--path-format=absolute',
+    '--git-common-dir',
+  ], { cwd });
+
+  return {
+    branch,
+    commonGitDirectory,
+    objectId,
+    repositoryRoot: sourceRepositoryRoot(cwd),
+    sessionId,
+    worktreePath: sessionWorktree.path,
+  };
+}
+
+function captureTarget(event) {
+  if (event?.hook_event_name !== 'SessionEnd' || typeof event.cwd !== 'string') {
+    return null;
+  }
+  return captureWorktreeTarget(event.cwd, event.session_id || null);
+}
+
+function fastForwardLocalDefaultBranch(repositoryRoot, log) {
+  const primaryRoot = sourceRepositoryRoot(repositoryRoot);
+  const { remote, defaultBranch } = projectConfig(primaryRoot).git;
+  const localRef = `refs/heads/${defaultBranch}`;
+  const remoteRef = `refs/remotes/${remote}/${defaultBranch}`;
+  const localTip = tryGit(['show-ref', '--hash', '--verify', localRef], primaryRoot);
+  if (!localTip) {
+    return false;
+  }
+
+  const remoteTip = runGit(['rev-parse', remoteRef], {
+    cwd: primaryRoot,
+  });
+  if (localTip === remoteTip) {
+    return false;
+  }
+  if (tryGit(['merge-base', '--is-ancestor', localTip, remoteTip], primaryRoot) === null) {
+    log(`Keep ${defaultBranch}: it cannot fast-forward to ${remote}/${defaultBranch}.`);
+    return false;
+  }
+
+  const defaultWorktree = listWorktrees(primaryRoot)
+    .find((worktree) => worktree.branch === localRef);
+  if (defaultWorktree) {
+    const status = runGit(['status', '--porcelain', '--untracked-files=all'], {
+      cwd: defaultWorktree.path,
+    });
+    if (status !== '') {
+      log(`Keep ${defaultBranch}: its worktree has changes.`);
+      return false;
+    }
+
+    log(`Fast-forwarding ${defaultBranch} in its worktree to ${remote}/${defaultBranch}.`);
+    runGit(['merge', '--ff-only', remoteTip], { cwd: defaultWorktree.path });
+    return true;
+  }
+
+  log(`Fast-forwarding ${defaultBranch} reference to ${remote}/${defaultBranch}.`);
+  runGit([
+    'update-ref',
+    '-m',
+    `fast-forward ${defaultBranch} to ${remote}/${defaultBranch}`,
+    localRef,
+    remoteTip,
+    localTip,
+  ], { cwd: primaryRoot });
+  return true;
+}
+
+function cleanupTarget(target, log = console.log) {
+  const { remote, defaultBranch } = projectConfig(target.repositoryRoot).git;
+  const branchRef = `refs/heads/${target.branch}`;
+  const currentObjectId = tryGit(['show-ref', '--hash', '--verify', branchRef], target.repositoryRoot);
+
+  if (currentObjectId !== target.objectId) {
+    log(`Skip ${target.branch}: the local branch changed after the session ended.`);
+    return false;
+  }
+
+  const currentWorktrees = listWorktrees(target.repositoryRoot);
+  const targetWorktree = currentWorktrees.find((item) => samePath(item.path, target.worktreePath));
+
+  if (targetWorktree) {
+    if (targetWorktree.branch !== branchRef) {
+      log(`Skip ${target.branch}: the worktree now uses a different branch.`);
+      return false;
+    }
+    if (Object.hasOwn(targetWorktree, 'locked')) {
+      log(`Skip ${target.branch}: its worktree is locked.`);
+      return false;
+    }
+
+    const worktreeObjectId = tryGit(['rev-parse', 'HEAD'], target.worktreePath);
+    if (worktreeObjectId !== target.objectId) {
+      log(`Skip ${target.branch}: the worktree HEAD changed after the session ended.`);
+      return false;
+    }
+
+    const status = runGit(['status', '--porcelain', '--untracked-files=all'], {
+      cwd: target.worktreePath,
+    });
+    if (status !== '') {
+      log(`Skip ${target.branch}: its worktree has changes.`);
+      return false;
+    }
+  }
+
+  log(`Fetching ${remote} before checking ${target.branch}.`);
+  runGit(['fetch', '--prune', remote], { cwd: target.repositoryRoot });
+  runGit(['show-ref', '--verify', '--quiet', `refs/remotes/${remote}/${defaultBranch}`], {
+    cwd: target.repositoryRoot,
+  });
+  fastForwardLocalDefaultBranch(target.repositoryRoot, log);
+
+  const item = buildPlan(target.repositoryRoot)
+    .find((candidate) => candidate.branch === target.branch);
+
+  if (!item?.local || item.localObjectId !== target.objectId) {
+    log(`Keep ${target.branch}: it is not fully merged into ${remote}/${defaultBranch}.`);
+    return false;
+  }
+  if (item.skipReason) {
+    log(`Skip ${target.branch}: ${item.skipReason}`);
+    return false;
+  }
+  if (
+    item.worktrees.length > 0
+    && !item.worktrees.every((worktree) => samePath(worktree.path, target.worktreePath))
+  ) {
+    log(`Skip ${target.branch}: it is checked out in another worktree.`);
+    return false;
+  }
+
+  applyPlan(target.repositoryRoot, [item], true, log);
+  return true;
+}
+
+function sleep(milliseconds) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+}
+
+function acquireLock(lockPath) {
+  const deadline = Date.now() + LOCK_WAIT_MS;
+
+  while (Date.now() < deadline) {
+    try {
+      fs.mkdirSync(lockPath);
+      return;
+    } catch (error) {
+      if (error.code !== 'EEXIST') {
+        throw error;
+      }
+
+      try {
+        const age = Date.now() - fs.statSync(lockPath).mtimeMs;
+        if (age > LOCK_MAX_AGE_MS) {
+          fs.rmSync(lockPath, { recursive: true, force: true });
+          continue;
+        }
+      } catch (statError) {
+        if (statError.code !== 'ENOENT') {
+          throw statError;
+        }
+      }
+
+      sleep(200);
+    }
+  }
+
+  throw new Error('timed out waiting for another session cleanup');
+}
+
+function runWorker(target) {
+  const lockPath = path.join(target.commonGitDirectory, 'cleanup-ended-session.lock');
+  acquireLock(lockPath);
+
+  try {
+    console.log(`\nSession cleanup for ${target.branch}`);
+    cleanupTarget(target);
+  } finally {
+    fs.rmSync(lockPath, { recursive: true, force: true });
+  }
+}
+
+function launchWorker(target) {
+  const logPath = path.join(target.commonGitDirectory, 'cleanup-ended-session.log');
+  const logFile = fs.openSync(logPath, 'a');
+  const payload = Buffer.from(JSON.stringify(target)).toString('base64url');
+  const child = spawn(process.execPath, [__filename, '--worker', payload], {
+    cwd: target.repositoryRoot,
+    detached: true,
+    stdio: ['ignore', logFile, logFile],
+  });
+
+  child.unref();
+  fs.closeSync(logFile);
+  return { logPath, pid: child.pid };
+}
+
+function readHookEvent() {
+  const input = fs.readFileSync(0, 'utf8').trim();
+  return input === '' ? null : JSON.parse(input);
+}
+
+function main() {
+  logScriptInvocation();
+  if (process.argv[2] === '--worker') {
+    const target = JSON.parse(Buffer.from(process.argv[3], 'base64url').toString('utf8'));
+    runWorker(target);
+    return;
+  }
+
+  const target = captureTarget(readHookEvent());
+  if (target) {
+    launchWorker(target);
+  }
+}
+
+if (require.main === module) {
+  try {
+    main();
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exitCode = 1;
+  }
+}
+
+module.exports = {
+  captureTarget,
+  captureWorktreeTarget,
+  cleanupTarget,
+  launchWorker,
+};