opencode-swarm 7.184.11 → 7.184.13

package/dist/cli/index-hg1hqfy3.js

@@ -0,0 +1,963 @@
+// @bun
+import {
+  MAX_TRANSIENT_RETRIES,
+  buildTaskCompletionDescriptor,
+  ensureTaskCheckpointReceipt,
+  isTransientSpawnError,
+  loadPlan,
+  transientBackoff,
+  updateTaskCheckpointReceipt
+} from "./index-v4ra6hz8.js";
+import {
+  tool
+} from "./index-9nyqt3kb.js";
+import {
+  GitBinaryMissingError,
+  GitSpawnCwdError,
+  isGitBinaryMissing,
+  isSpawnCwdMissing,
+  isSpawnCwdUnreadable
+} from "./index-g4fs6z4e.js";
+import {
+  readLedgerEvents
+} from "./index-d2xdwz22.js";
+import {
+  appendCoreEventSync
+} from "./index-7rzgdcvc.js";
+import {
+  derivePlanId,
+  derivePlanIdentityHash
+} from "./index-7pmbnjvj.js";
+import {
+  assertProjectRoot,
+  hasExplicitProjectBoundary,
+  isStrictPathDescendant
+} from "./index-t7hmqgjy.js";
+import {
+  tryAcquireLock
+} from "./index-ejhxgyvm.js";
+import {
+  loadPluginConfigWithMeta
+} from "./index-djct2zsr.js";
+import {
+  init_git_executable,
+  resolveGitExecutable
+} from "./index-zxdawwc7.js";
+import {
+  exports_external,
+  init_zod
+} from "./index-gknz3bv1.js";
+
+// src/tools/checkpoint.ts
+init_zod();
+import * as child_process from "child_process";
+import * as fs2 from "fs";
+import * as path2 from "path";
+init_git_executable();
+
+// src/tools/create-tool.ts
+init_zod();
+
+// src/tools/resolve-working-directory.ts
+import * as fs from "fs";
+import * as path from "path";
+function resolveWorkingDirectory(workingDirectory, fallbackDirectory) {
+  if (workingDirectory == null || workingDirectory === "") {
+    if (typeof fallbackDirectory !== "string" || fallbackDirectory === "") {
+      return {
+        success: false,
+        message: "Invalid working_directory: no explicit working_directory was provided and fallbackDirectory is missing or not a string"
+      };
+    }
+    try {
+      assertProjectRoot(fallbackDirectory);
+    } catch (error) {
+      return {
+        success: false,
+        message: error instanceof Error ? error.message : String(error)
+      };
+    }
+    return { success: true, directory: fallbackDirectory };
+  }
+  if (typeof workingDirectory !== "string") {
+    return {
+      success: false,
+      message: "Invalid working_directory: path must be a string"
+    };
+  }
+  if (workingDirectory.includes("\x00")) {
+    return {
+      success: false,
+      message: "Invalid working_directory: null bytes are not allowed"
+    };
+  }
+  const reservedDevicePattern = /^(NUL|CON|AUX|COM[1-9]|LPT[1-9])(\..*)?$/i;
+  if (workingDirectory.startsWith("\\\\") || process.platform === "win32" && reservedDevicePattern.test(workingDirectory)) {
+    return {
+      success: false,
+      message: "Invalid working_directory: Windows device paths are not allowed"
+    };
+  }
+  const rawPathParts = workingDirectory.split(/[\\/]/);
+  if (rawPathParts.includes("..")) {
+    return {
+      success: false,
+      message: "Invalid working_directory: path traversal sequences (..) are not allowed"
+    };
+  }
+  const normalizedDir = path.normalize(workingDirectory);
+  const resolvedDir = path.resolve(normalizedDir);
+  let statResult;
+  try {
+    statResult = fs.statSync(resolvedDir);
+  } catch {
+    return {
+      success: false,
+      message: `Invalid working_directory: path "${resolvedDir}" does not exist or is inaccessible`
+    };
+  }
+  if (!statResult.isDirectory()) {
+    return {
+      success: false,
+      message: `Invalid working_directory: path "${resolvedDir}" is not a directory`
+    };
+  }
+  try {
+    assertProjectRoot(resolvedDir);
+  } catch (error) {
+    return {
+      success: false,
+      message: error instanceof Error ? error.message : String(error)
+    };
+  }
+  if (typeof fallbackDirectory !== "string" || fallbackDirectory === "") {
+    return { success: true, directory: resolvedDir };
+  }
+  const resolvedFallback = path.resolve(fallbackDirectory);
+  let fallbackExists = false;
+  try {
+    fs.statSync(resolvedFallback);
+    fallbackExists = true;
+  } catch {
+    fallbackExists = false;
+  }
+  if (fallbackExists) {
+    const isSubdirectory = isStrictPathDescendant(resolvedDir, resolvedFallback);
+    if (isSubdirectory) {
+      if (hasExplicitProjectBoundary(resolvedDir)) {
+        return { success: true, directory: resolvedDir };
+      }
+      return {
+        success: false,
+        message: `Invalid working_directory: "${workingDirectory}" resolves to "${resolvedDir}" ` + `which is a subdirectory of fallback "${resolvedFallback}". ` + `Pass the project root path or omit working_directory entirely.`
+      };
+    }
+  }
+  return { success: true, directory: resolvedDir };
+}
+
+// src/tools/create-tool.ts
+function classifyToolError(error) {
+  const msg = (error instanceof Error ? error.message ?? "" : String(error)).toLowerCase();
+  if (msg.includes("not registered") || msg.includes("unknown tool"))
+    return "not_registered";
+  if (msg.includes("not whitelisted") || msg.includes("not allowed"))
+    return "not_whitelisted";
+  if (msg.includes("enoent") || msg.includes("command not found") || msg.includes("binary not found") || msg.includes("no such file or directory"))
+    return "binary_missing";
+  return "execution_error";
+}
+function createSwarmTool(opts) {
+  const ownsWorkingDirectory = Object.hasOwn(opts.args, "working_directory");
+  const allowsWorkingDirectoryOverride = opts.allowWorkingDirectoryOverride === true && !ownsWorkingDirectory;
+  const toolArgs = allowsWorkingDirectoryOverride ? {
+    ...opts.args,
+    working_directory: exports_external.string().optional().describe("Project or linked-worktree root for this tool invocation")
+  } : opts.args;
+  return tool({
+    description: opts.description,
+    args: toolArgs,
+    execute: async (args, ctx) => {
+      const fallbackDirectory = ctx?.directory ?? process.cwd();
+      try {
+        let effectiveArgs = args;
+        let effectiveDirectory = fallbackDirectory;
+        let effectiveContext = ctx;
+        if (!ownsWorkingDirectory && typeof args === "object" && args !== null) {
+          if (!allowsWorkingDirectoryOverride && Object.hasOwn(args, "working_directory")) {
+            throw new Error("Invalid working_directory: this tool does not allow working_directory overrides");
+          }
+          if (allowsWorkingDirectoryOverride && Object.hasOwn(args, "working_directory")) {
+            const { working_directory: workingDirectory, ...executorArgs } = args;
+            effectiveArgs = executorArgs;
+            if (workingDirectory !== undefined) {
+              const resolved = resolveWorkingDirectory(workingDirectory, fallbackDirectory);
+              if (!resolved.success)
+                throw new Error(resolved.message);
+              effectiveDirectory = resolved.directory;
+              effectiveContext = {
+                ...ctx,
+                directory: resolved.directory,
+                worktree: resolved.directory
+              };
+            }
+          }
+        }
+        const result = await opts.execute(effectiveArgs, effectiveDirectory, effectiveContext);
+        return result;
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return JSON.stringify({
+          success: false,
+          failure_class: classifyToolError(error),
+          message: "Tool execution failed",
+          errors: [message]
+        }, null, 2);
+      }
+    }
+  });
+}
+
+// src/tools/checkpoint.ts
+var CHECKPOINT_LOG_PATH = ".swarm/checkpoints.json";
+var PLAN_LOCK_PATH = "plan.json";
+var CHECKPOINT_AGENT_NAME = "checkpoint";
+var MAX_LABEL_LENGTH = 100;
+var GIT_TIMEOUT_MS = 30000;
+var GIT_MAX_BUFFER_BYTES = 5 * 1024 * 1024;
+var CHECKPOINT_LOCK_MAX_ATTEMPTS = 20;
+var CHECKPOINT_LOCK_DELAY_MS = 250;
+var CHECKPOINT_LOCK_DEADLINE_MS = 45000;
+var CHECKPOINT_RECEIPT_LOOKUP_LIMIT = 25;
+var NON_SWARM_COMMIT_PATHSPEC = [
+  ".",
+  ":(exclude,top).swarm",
+  ":(exclude,top).swarm/**"
+];
+var SHELL_METACHARACTERS = /[;|&$`(){}<>!'"]/;
+var SAFE_LABEL_PATTERN = /^[a-zA-Z0-9_ -]+$/;
+var CONTROL_CHAR_PATTERN = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/;
+var NON_ASCII_PATTERN = /[^\x20-\x7E]/;
+var _internals = {
+  tryAcquireLock,
+  loadPlan,
+  gitExec,
+  sleep: (ms) => new Promise((resolve2) => setTimeout(resolve2, ms)),
+  findCommitByExactSubject,
+  stageAllExcludingSwarm,
+  resolveGitExecutable
+};
+function serializeResult(action, payload) {
+  return JSON.stringify({
+    action,
+    ...payload
+  }, null, 2);
+}
+function containsNonAsciiChars(label) {
+  for (let i = 0;i < label.length; i++) {
+    const charCode = label.charCodeAt(i);
+    if (charCode < 32 || charCode > 126) {
+      return true;
+    }
+  }
+  return false;
+}
+function validateLabel(label) {
+  if (!label || label.length === 0) {
+    return "label is required";
+  }
+  if (label.length > MAX_LABEL_LENGTH) {
+    return `label exceeds maximum length of ${MAX_LABEL_LENGTH}`;
+  }
+  if (label.startsWith("--")) {
+    return 'label cannot start with "--" (git flag pattern)';
+  }
+  if (CONTROL_CHAR_PATTERN.test(label)) {
+    return "label contains control characters";
+  }
+  if (NON_ASCII_PATTERN.test(label)) {
+    return "label contains non-ASCII or invalid characters";
+  }
+  if (containsNonAsciiChars(label)) {
+    return "label contains non-ASCII characters (must be printable ASCII only)";
+  }
+  if (SHELL_METACHARACTERS.test(label)) {
+    return "label contains shell metacharacters";
+  }
+  if (!SAFE_LABEL_PATTERN.test(label)) {
+    return "label contains invalid characters (use alphanumeric, hyphen, underscore, space)";
+  }
+  if (!/[a-zA-Z0-9_]/.test(label)) {
+    return "label cannot be whitespace-only";
+  }
+  if (label.includes("..") || label.includes("/") || label.includes("\\")) {
+    return "label contains path traversal sequence";
+  }
+  return null;
+}
+function getCheckpointLogPath(directory) {
+  return path2.join(directory, CHECKPOINT_LOG_PATH);
+}
+function readCheckpointLog(directory) {
+  const logPath = getCheckpointLogPath(directory);
+  try {
+    if (fs2.existsSync(logPath)) {
+      const content = fs2.readFileSync(logPath, "utf-8");
+      const parsed = JSON.parse(content);
+      if (!parsed.checkpoints || !Array.isArray(parsed.checkpoints)) {
+        return { version: 1, checkpoints: [] };
+      }
+      return parsed;
+    }
+  } catch {}
+  return { version: 1, checkpoints: [] };
+}
+function writeCheckpointLog(log, directory) {
+  const logPath = getCheckpointLogPath(directory);
+  const dir = path2.dirname(logPath);
+  if (!fs2.existsSync(dir)) {
+    fs2.mkdirSync(dir, { recursive: true });
+  }
+  const tempPath = `${logPath}.tmp`;
+  fs2.writeFileSync(tempPath, JSON.stringify(log, null, 2), "utf-8");
+  fs2.renameSync(tempPath, logPath);
+}
+function appendRetentionEvent(directory, event) {
+  try {
+    appendCoreEventSync(directory, {
+      ...event,
+      timestamp: new Date().toISOString()
+    });
+  } catch {}
+}
+function loadCheckpointConfig(directory) {
+  let maxCheckpoints = 20;
+  let allowEmptyCommits = false;
+  try {
+    const { config } = loadPluginConfigWithMeta(directory);
+    maxCheckpoints = config.checkpoint?.max_retention ?? maxCheckpoints;
+    allowEmptyCommits = config.checkpoint?.allow_empty_commits === true;
+  } catch {}
+  return { maxCheckpoints, allowEmptyCommits };
+}
+function appendCheckpointEntry(directory, log, entry, maxCheckpoints) {
+  const existing = log.checkpoints.find((checkpoint) => checkpoint.label === entry.label);
+  if (existing) {
+    if (existing.sha !== entry.sha) {
+      throw new Error(`checkpoint log conflict: label "${entry.label}" already exists with a different SHA`);
+    }
+    return;
+  }
+  log.checkpoints.push(entry);
+  if (log.checkpoints.length > maxCheckpoints) {
+    const evicted = log.checkpoints.splice(0, log.checkpoints.length - maxCheckpoints);
+    appendRetentionEvent(directory, {
+      event: "checkpoint_retention_applied",
+      evicted_labels: evicted.map((checkpoint) => checkpoint.label),
+      evicted_count: evicted.length,
+      remaining_count: log.checkpoints.length
+    });
+  }
+}
+function upsertTaskCompletionCheckpointEntry(directory, log, entry, maxCheckpoints) {
+  const existingIndex = log.checkpoints.findIndex((checkpoint) => checkpoint.label === entry.label);
+  if (existingIndex >= 0) {
+    const existing = log.checkpoints[existingIndex];
+    if (existing.sha === entry.sha) {
+      return;
+    }
+    log.checkpoints[existingIndex] = entry;
+    return;
+  }
+  log.checkpoints.push(entry);
+  if (log.checkpoints.length > maxCheckpoints) {
+    const evicted = log.checkpoints.splice(0, log.checkpoints.length - maxCheckpoints);
+    appendRetentionEvent(directory, {
+      event: "checkpoint_retention_applied",
+      evicted_labels: evicted.map((checkpoint) => checkpoint.label),
+      evicted_count: evicted.length,
+      remaining_count: log.checkpoints.length
+    });
+  }
+}
+function stageAllExcludingSwarm(directory) {
+  _internals.gitExec(["add", "--all", "--", ...NON_SWARM_COMMIT_PATHSPEC], directory);
+}
+function gitExec(args, cwd) {
+  for (let attempt = 0;attempt < MAX_TRANSIENT_RETRIES; attempt++) {
+    const result = child_process.spawnSync(_internals.resolveGitExecutable(), args, {
+      cwd,
+      encoding: "utf-8",
+      timeout: GIT_TIMEOUT_MS,
+      stdio: ["ignore", "pipe", "pipe"],
+      windowsHide: true,
+      maxBuffer: GIT_MAX_BUFFER_BYTES
+    });
+    if (result.error) {
+      const code = result.error.code;
+      const message = result.error.message ?? "";
+      const isTransient = isTransientSpawnError(result.error) || /ETIMEDOUT|timed out/i.test(message);
+      if (!isTransient || attempt >= MAX_TRANSIENT_RETRIES - 1) {
+        if (isSpawnCwdMissing(result.error, cwd)) {
+          throw new GitSpawnCwdError(cwd, "missing");
+        }
+        if (isSpawnCwdUnreadable(result.error, cwd)) {
+          throw new GitSpawnCwdError(cwd, "unreadable");
+        }
+        if (isGitBinaryMissing(result.error, cwd)) {
+          throw new GitBinaryMissingError(`git executable is not available on PATH (working directory ${cwd} exists)`, { cause: result.error });
+        }
+        throw new Error(`git failed to start: ${code ?? "unknown"} - ${message}`);
+      }
+      transientBackoff(attempt);
+      continue;
+    }
+    if (result.status === 0) {
+      return result.stdout ?? "";
+    }
+    throw new Error(result.stderr?.trim() || `git exited with code ${result.status}`);
+  }
+  throw new Error("git command failed after transient retries");
+}
+function getCurrentSha(directory) {
+  return gitExec(["rev-parse", "HEAD"], directory).trim();
+}
+function isGitRepo(directory) {
+  try {
+    gitExec(["rev-parse", "--git-dir"], directory);
+    return { isRepo: true };
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    const isTransient = /ETIMEDOUT|timed out/i.test(message) && !/not a git repository/i.test(message);
+    if (isTransient) {
+      return {
+        isRepo: false,
+        warning: "git probe failed after retry exhaustion - treating as not a git repository"
+      };
+    }
+    return {
+      isRepo: false,
+      warning: "git probe failed - directory may not be a git repository"
+    };
+  }
+}
+function findCommitByExactSubject(directory, subject) {
+  const output = _internals.gitExec([
+    "log",
+    "HEAD",
+    "--format=%H%x00%s",
+    "--fixed-strings",
+    `--grep=${subject}`,
+    "-n",
+    String(CHECKPOINT_RECEIPT_LOOKUP_LIMIT)
+  ], directory);
+  for (const line of output.split(/\r?\n/)) {
+    if (!line)
+      continue;
+    const nulIndex = line.indexOf("\x00");
+    if (nulIndex <= 0)
+      continue;
+    const sha = line.slice(0, nulIndex).trim();
+    const candidateSubject = line.slice(nulIndex + 1);
+    if (sha.length === 40 && /^[a-f0-9]{40}$/i.test(sha) && candidateSubject === subject) {
+      return sha;
+    }
+  }
+  return null;
+}
+async function withTaskCompletionLocksResult(input) {
+  const deadline = Date.now() + CHECKPOINT_LOCK_DEADLINE_MS;
+  let attempts = 0;
+  while (attempts < CHECKPOINT_LOCK_MAX_ATTEMPTS && Date.now() <= deadline) {
+    attempts++;
+    let planLockResult;
+    try {
+      planLockResult = await _internals.tryAcquireLock(input.directory, PLAN_LOCK_PATH, CHECKPOINT_AGENT_NAME, `save-task-completion-plan-${input.taskId}`);
+    } catch (error) {
+      if (input.onFailure) {
+        return input.onFailure(error);
+      }
+      return serializeResult("save_task_completion", {
+        success: false,
+        error: `save_task_completion failed: ${error instanceof Error ? error.message : String(error)}`
+      });
+    }
+    if (!planLockResult.acquired) {
+      if (attempts >= CHECKPOINT_LOCK_MAX_ATTEMPTS || Date.now() + CHECKPOINT_LOCK_DELAY_MS > deadline) {
+        break;
+      }
+      await _internals.sleep(CHECKPOINT_LOCK_DELAY_MS);
+      continue;
+    }
+    try {
+      let checkpointLockResult;
+      try {
+        checkpointLockResult = await _internals.tryAcquireLock(input.directory, CHECKPOINT_LOG_PATH, CHECKPOINT_AGENT_NAME, `save-task-completion-checkpoint-${input.taskId}`);
+      } catch (error) {
+        if (input.onFailure) {
+          return input.onFailure(error);
+        }
+        return serializeResult("save_task_completion", {
+          success: false,
+          error: `save_task_completion failed: ${error instanceof Error ? error.message : String(error)}`
+        });
+      }
+      if (!checkpointLockResult.acquired) {
+        if (attempts >= CHECKPOINT_LOCK_MAX_ATTEMPTS || Date.now() + CHECKPOINT_LOCK_DELAY_MS > deadline) {
+          break;
+        }
+        await _internals.sleep(CHECKPOINT_LOCK_DELAY_MS);
+        continue;
+      }
+      try {
+        return await input.run();
+      } catch (error) {
+        if (input.onFailure) {
+          return input.onFailure(error);
+        }
+        return serializeResult("save_task_completion", {
+          success: false,
+          error: `save_task_completion failed: ${error instanceof Error ? error.message : String(error)}`
+        });
+      } finally {
+        if (checkpointLockResult.lock._release) {
+          try {
+            await checkpointLockResult.lock._release();
+          } catch {}
+        }
+      }
+    } finally {
+      if (planLockResult.lock._release) {
+        try {
+          await planLockResult.lock._release();
+        } catch {}
+      }
+    }
+  }
+  if (input.onBusy) {
+    return input.onBusy(attempts);
+  }
+  return serializeResult("save_task_completion", {
+    success: false,
+    status: "checkpoint_busy",
+    error: "checkpoint_busy: checkpoint or plan state is locked by another operation; retry after the current mutation completes",
+    retryable: true,
+    attempts
+  });
+}
+async function withCheckpointMutationLock(input) {
+  const result = await withCheckpointMutationLockResult({
+    action: input.action,
+    directory: input.directory,
+    operationKey: input.operationKey,
+    run: input.run,
+    onContendedAttempt: input.onContendedAttempt
+  });
+  return result;
+}
+async function withCheckpointMutationLockResult(input) {
+  const deadline = Date.now() + CHECKPOINT_LOCK_DEADLINE_MS;
+  let attempts = 0;
+  while (attempts < CHECKPOINT_LOCK_MAX_ATTEMPTS && Date.now() <= deadline) {
+    attempts++;
+    let lockResult;
+    try {
+      lockResult = await _internals.tryAcquireLock(input.directory, CHECKPOINT_LOG_PATH, CHECKPOINT_AGENT_NAME, input.operationKey);
+    } catch (error) {
+      if (input.onFailure) {
+        return input.onFailure(error);
+      }
+      return serializeResult(input.action, {
+        success: false,
+        error: `${input.action} failed: ${error instanceof Error ? error.message : String(error)}`
+      });
+    }
+    if (lockResult.acquired) {
+      try {
+        try {
+          return await input.run();
+        } catch (error) {
+          if (input.onFailure) {
+            return input.onFailure(error);
+          }
+          return serializeResult(input.action, {
+            success: false,
+            error: `${input.action} failed: ${error instanceof Error ? error.message : String(error)}`
+          });
+        }
+      } finally {
+        if (lockResult.lock._release) {
+          try {
+            await lockResult.lock._release();
+          } catch {}
+        }
+      }
+    }
+    const contended = input.onContendedAttempt?.();
+    if (contended)
+      return contended;
+    if (attempts >= CHECKPOINT_LOCK_MAX_ATTEMPTS || Date.now() + CHECKPOINT_LOCK_DELAY_MS > deadline) {
+      break;
+    }
+    await _internals.sleep(CHECKPOINT_LOCK_DELAY_MS);
+  }
+  if (input.onBusy) {
+    return input.onBusy(attempts);
+  }
+  return serializeResult(input.action, {
+    success: false,
+    status: "checkpoint_busy",
+    error: "checkpoint_busy: checkpoint state is locked by another operation; retry after the current mutation completes",
+    retryable: true,
+    attempts
+  });
+}
+function handleSave(label, directory) {
+  try {
+    const { maxCheckpoints, allowEmptyCommits } = loadCheckpointConfig(directory);
+    const log = readCheckpointLog(directory);
+    const existingCheckpoint = log.checkpoints.find((checkpoint) => checkpoint.label === label);
+    if (existingCheckpoint) {
+      return serializeResult("save", {
+        success: false,
+        error: `duplicate label: "${label}" already exists. Use a different label or delete the existing checkpoint first.`
+      });
+    }
+    const timestamp = new Date().toISOString();
+    _internals.stageAllExcludingSwarm(directory);
+    const hasStagedChanges = (() => {
+      try {
+        gitExec(["diff", "--cached", "--quiet"], directory);
+        return false;
+      } catch {
+        return true;
+      }
+    })();
+    if (hasStagedChanges) {
+      gitExec(["commit", "-m", `checkpoint: ${label}`], directory);
+    } else if (allowEmptyCommits) {
+      gitExec(["commit", "--allow-empty", "-m", `checkpoint: ${label}`], directory);
+    }
+    const newSha = getCurrentSha(directory);
+    appendCheckpointEntry(directory, log, {
+      label,
+      sha: newSha,
+      timestamp
+    }, maxCheckpoints);
+    writeCheckpointLog(log, directory);
+    return serializeResult("save", {
+      success: true,
+      label,
+      sha: newSha,
+      message: `Checkpoint saved: "${label}"`
+    });
+  } catch (e) {
+    return serializeResult("save", {
+      success: false,
+      error: e instanceof Error ? `save failed: ${e.message}` : "save failed: unknown error"
+    });
+  }
+}
+async function saveCheckpointRecord(label, directory) {
+  const labelError = validateLabel(label);
+  if (labelError) {
+    return { success: false, error: labelError };
+  }
+  return withCheckpointMutationLockResult({
+    action: "save",
+    directory,
+    operationKey: `save-record-${label}`,
+    run: async () => {
+      const log = readCheckpointLog(directory);
+      if (log.checkpoints.find((checkpoint) => checkpoint.label === label)) {
+        return { success: false, error: `duplicate label: "${label}"` };
+      }
+      let sha = "";
+      const repoProbe = isGitRepo(directory);
+      if (repoProbe.isRepo) {
+        try {
+          sha = getCurrentSha(directory);
+        } catch {
+          sha = "";
+        }
+      }
+      appendCheckpointEntry(directory, log, {
+        label,
+        sha,
+        timestamp: new Date().toISOString()
+      }, loadCheckpointConfig(directory).maxCheckpoints);
+      writeCheckpointLog(log, directory);
+      const result = { success: true, sha };
+      if (!sha) {
+        result.warning = "no git restore target - checkpoint recorded without a SHA (directory may not be a git repository or HEAD is unavailable)";
+      }
+      return result;
+    },
+    onBusy: () => ({
+      success: false,
+      error: "checkpoint_busy: checkpoint state is locked by another operation; retry after the current mutation completes"
+    }),
+    onFailure: (error) => ({
+      success: false,
+      error: error instanceof Error ? error.message : "unknown error"
+    })
+  });
+}
+function handleRestore(label, directory) {
+  try {
+    const log = readCheckpointLog(directory);
+    const checkpoint = log.checkpoints.find((candidate) => candidate.label === label);
+    if (!checkpoint) {
+      return serializeResult("restore", {
+        success: false,
+        error: `checkpoint not found: "${label}"`
+      });
+    }
+    const logBeforeReset = log;
+    gitExec(["reset", "--hard", checkpoint.sha], directory);
+    writeCheckpointLog(logBeforeReset, directory);
+    return serializeResult("restore", {
+      success: true,
+      label,
+      sha: checkpoint.sha,
+      message: `Restored to checkpoint: "${label}" (hard reset)`
+    });
+  } catch (e) {
+    return serializeResult("restore", {
+      success: false,
+      error: e instanceof Error ? `restore failed: ${e.message}` : "restore failed: unknown error"
+    });
+  }
+}
+function handleList(directory) {
+  const log = readCheckpointLog(directory);
+  const sorted = [...log.checkpoints].sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+  return serializeResult("list", {
+    success: true,
+    count: sorted.length,
+    checkpoints: sorted
+  });
+}
+function handleDelete(label, directory) {
+  try {
+    const log = readCheckpointLog(directory);
+    const initialLength = log.checkpoints.length;
+    log.checkpoints = log.checkpoints.filter((checkpoint) => checkpoint.label !== label);
+    if (log.checkpoints.length === initialLength) {
+      return serializeResult("delete", {
+        success: false,
+        error: `checkpoint not found: "${label}"`
+      });
+    }
+    writeCheckpointLog(log, directory);
+    return serializeResult("delete", {
+      success: true,
+      label,
+      message: `Checkpoint deleted: "${label}"`
+    });
+  } catch (e) {
+    return serializeResult("delete", {
+      success: false,
+      error: e instanceof Error ? `delete failed: ${e.message}` : "delete failed: unknown error"
+    });
+  }
+}
+async function handleSaveTaskCompletion(taskId, directory) {
+  return withTaskCompletionLocksResult({
+    directory,
+    taskId,
+    run: async () => {
+      const plan = await _internals.loadPlan(directory);
+      if (!plan) {
+        return serializeResult("save_task_completion", {
+          success: false,
+          error: "save_task_completion failed: no durable plan is available under .swarm/plan.json"
+        });
+      }
+      const task = plan.phases.flatMap((phase) => phase.tasks).find((candidate) => candidate.id === taskId);
+      if (!task) {
+        return serializeResult("save_task_completion", {
+          success: false,
+          error: `save_task_completion failed: task "${taskId}" was not found in the current plan`
+        });
+      }
+      if (task.status !== "completed") {
+        return serializeResult("save_task_completion", {
+          success: false,
+          error: `save_task_completion failed: task "${taskId}" is ${task.status}, not completed`
+        });
+      }
+      await _internals.afterTaskEligibilityRead?.(directory, task.id);
+      const planIdentityHash = derivePlanIdentityHash(plan);
+      const planId = derivePlanId(plan);
+      const ledgerEvents = await readLedgerEvents(directory);
+      const planEvents = ledgerEvents.filter((event) => event.plan_id === planId);
+      const anchor = planEvents.find((event) => event.event_type === "plan_created");
+      const anchorPlan = anchor?.payload?.plan;
+      if (anchorPlan && typeof anchorPlan === "object") {
+        const rawIdentity = anchorPlan;
+        if (typeof rawIdentity.swarm !== "string" || typeof rawIdentity.title !== "string" || derivePlanIdentityHash({
+          swarm: rawIdentity.swarm,
+          title: rawIdentity.title
+        }) !== planIdentityHash) {
+          throw new Error(`save_task_completion failed: ledger identity does not match the current plan for task "${task.id}"`);
+        }
+      }
+      const latestTaskStatusEvent = [...planEvents].reverse().find((event) => event.event_type === "task_status_changed" && event.task_id === task.id);
+      if (latestTaskStatusEvent && latestTaskStatusEvent.to_status !== "completed") {
+        throw new Error(`save_task_completion failed: the authoritative ledger does not record task "${task.id}" as completed`);
+      }
+      const completionLedgerSeq = latestTaskStatusEvent?.seq ?? anchor?.seq ?? 0;
+      const receipt = ensureTaskCheckpointReceipt(directory, planIdentityHash, task.id, completionLedgerSeq);
+      const descriptor = buildTaskCompletionDescriptor(planIdentityHash, task.id, receipt.generation);
+      if (receipt.label !== descriptor.label) {
+        throw new Error(`Task checkpoint receipt label conflict for ${task.id}: expected ${descriptor.label}, found ${receipt.label}`);
+      }
+      if (receipt.state === "logged") {
+        return serializeResult("save_task_completion", {
+          success: true,
+          idempotent: true,
+          label: receipt.label,
+          sha: receipt.sha,
+          receipt_state: receipt.state,
+          message: `Checkpoint task completion already logged for "${descriptor.taskId}"`
+        });
+      }
+      const recoveredSha = _internals.findCommitByExactSubject(directory, descriptor.subject);
+      let committedSha = null;
+      committedSha = recoveredSha ?? receipt.sha;
+      if (!committedSha) {
+        _internals.stageAllExcludingSwarm(directory);
+        _internals.gitExec([
+          "commit",
+          "--allow-empty",
+          "-m",
+          descriptor.subject,
+          "--",
+          ...NON_SWARM_COMMIT_PATHSPEC
+        ], directory);
+        committedSha = getCurrentSha(directory);
+      }
+      if (!committedSha) {
+        throw new Error(`save_task_completion failed: could not resolve commit SHA for task "${descriptor.taskId}"`);
+      }
+      updateTaskCheckpointReceipt(directory, descriptor, "committed", committedSha);
+      const log = readCheckpointLog(directory);
+      upsertTaskCompletionCheckpointEntry(directory, log, {
+        label: descriptor.label,
+        sha: committedSha,
+        timestamp: new Date().toISOString()
+      }, loadCheckpointConfig(directory).maxCheckpoints);
+      writeCheckpointLog(log, directory);
+      const logged = updateTaskCheckpointReceipt(directory, descriptor, "logged", committedSha);
+      return serializeResult("save_task_completion", {
+        success: true,
+        label: logged.label,
+        sha: committedSha,
+        receipt_state: logged.state,
+        message: `Checkpoint task completion saved for "${descriptor.taskId}"`
+      });
+    }
+  });
+}
+var checkpoint = createSwarmTool({
+  allowWorkingDirectoryOverride: true,
+  description: "Save, restore, list, and delete git checkpoints. " + "Use save to create a named snapshot, restore to return tracked files to a checkpoint, " + "list to see all checkpoints, delete to remove a checkpoint from the log, and save_task_completion to record a retry-safe task completion checkpoint. " + "Git commits are preserved on delete.",
+  args: {
+    action: exports_external.string().describe("Action to perform: save, restore, list, delete, or save_task_completion"),
+    label: exports_external.string().optional().describe("Checkpoint label (required for save, restore, delete)"),
+    task_id: exports_external.string().optional().describe('Plan task ID (required for save_task_completion), e.g. "1.1"')
+  },
+  execute: async (args, directory) => {
+    const repoProbe = isGitRepo(directory);
+    if (!repoProbe.isRepo) {
+      return serializeResult("unknown", {
+        success: false,
+        error: `${repoProbe.warning ?? "not a git repository"} - checkpoint tools require a git repository`
+      });
+    }
+    let action;
+    let label;
+    let taskId;
+    try {
+      action = String(args.action);
+      label = args.label !== undefined && args.label !== null ? String(args.label) : undefined;
+      taskId = args.task_id !== undefined && args.task_id !== null ? String(args.task_id) : undefined;
+    } catch {
+      return serializeResult("unknown", {
+        success: false,
+        error: "invalid arguments"
+      });
+    }
+    const validActions = [
+      "save",
+      "restore",
+      "list",
+      "delete",
+      "save_task_completion"
+    ];
+    if (!validActions.includes(action)) {
+      return serializeResult("unknown", {
+        success: false,
+        error: `invalid action: "${action}". Valid actions: ${validActions.join(", ")}`
+      });
+    }
+    if (["save", "restore", "delete"].includes(action)) {
+      if (!label) {
+        return serializeResult(action, {
+          success: false,
+          error: `label is required for ${action} action`
+        });
+      }
+      const labelError = validateLabel(label);
+      if (labelError) {
+        return serializeResult(action, {
+          success: false,
+          error: `invalid label: ${labelError}`
+        });
+      }
+    }
+    if (action === "save_task_completion") {
+      if (!taskId || taskId.trim().length === 0) {
+        return serializeResult("save_task_completion", {
+          success: false,
+          error: "task_id is required for save_task_completion action"
+        });
+      }
+    }
+    switch (action) {
+      case "save":
+        return withCheckpointMutationLock({
+          action: "save",
+          directory,
+          operationKey: `save-${label}`,
+          run: async () => handleSave(label, directory)
+        });
+      case "restore":
+        return withCheckpointMutationLock({
+          action: "restore",
+          directory,
+          operationKey: `restore-${label}`,
+          run: async () => handleRestore(label, directory)
+        });
+      case "list":
+        return handleList(directory);
+      case "delete":
+        return withCheckpointMutationLock({
+          action: "delete",
+          directory,
+          operationKey: `delete-${label}`,
+          run: async () => handleDelete(label, directory)
+        });
+      case "save_task_completion":
+        return handleSaveTaskCompletion(taskId, directory);
+      default:
+        return serializeResult("unknown", {
+          success: false,
+          error: "unreachable"
+        });
+    }
+  }
+});
+
+export { resolveWorkingDirectory, createSwarmTool, _internals, saveCheckpointRecord, checkpoint };