@lucid-agents/taskmarket 1.17.1 → 1.18.0

package/dist/chunk-ESPAXW2P.js

@@ -0,0 +1,831 @@
+import { createRequire as __tmCreateRequire } from 'node:module'; import { fileURLToPath as __tmFileURLToPath } from 'node:url'; import { dirname as __tmDirname } from 'node:path'; const require = __tmCreateRequire(import.meta.url); const __tmFilename = __tmFileURLToPath(import.meta.url); const __tmDirnameValue = __tmDirname(__tmFilename);
+import {
+  DEFAULT_SANDBOX_ROOT,
+  DEFAULT_SYNC_LIMITS,
+  ManifestLimitError,
+  SandboxFileError,
+  SyncError,
+  applyChanges,
+  captureProblem,
+  claimLost,
+  claimProject,
+  diffWorkspace,
+  killedSession,
+  loadBlob,
+  loadSyncState,
+  planUpload,
+  pruneBlobs,
+  pushLocalChanges,
+  releaseClaim,
+  renderChanges,
+  saveBlob,
+  unresolvedCount,
+  updateSyncState,
+  uploadWorkspace
+} from "./chunk-64HQ7ZF2.js";
+import {
+  AgentLaunchError
+} from "./chunk-YM4S6IE4.js";
+
+// src/lib/agent/sync-view.ts
+var SYNC_VIEW_VERSION = 1;
+var MAX_LISTED_CHANGES = 500;
+var MARK = { added: "+", modified: "~", deleted: "-" };
+var WHY = {
+  conflict: "changed on this computer too; not applied",
+  blocked: "never applied",
+  too_large: "over the sync file bound; never applied",
+  unreadable: "the sandbox could not read it; never applied",
+  unsafe_path: "never applied",
+  not_saved: "not brought back; drop it with --keep-local <path> or --discard"
+};
+function changeLine(change) {
+  const what = [
+    change.kind,
+    change.symlink ? "symlink" : change.binary ? "binary" : void 0,
+    change.lines ? `+${change.lines.added} -${change.lines.removed}` : void 0
+  ].filter(Boolean).join(", ");
+  if (change.status === "clean") return `  ${MARK[change.kind]} ${change.path} (${what})`;
+  const reason = change.detail ? `${change.detail}; ${WHY[change.status]}` : WHY[change.status];
+  return `  ! ${change.path} (${what}; ${change.status.replace("_", " ")}: ${reason})`;
+}
+function countsLine(counts) {
+  const parts = [`${counts.clean} to apply`];
+  if (counts.conflict) parts.push(`${counts.conflict} in conflict`);
+  if (counts.blocked) parts.push(`${counts.blocked} blocked`);
+  if (counts.notSaved) parts.push(`${counts.notSaved} not saved`);
+  if (counts.tooDeep) parts.push(`${counts.tooDeep} director(ies) nested too deep, not saved`);
+  return parts.join(", ");
+}
+function leftOutNote(leftOut) {
+  const of = (reason) => leftOut.filter((dir) => dir.reason === reason).map((dir) => dir.path);
+  const parts = [];
+  const build = of("build_output");
+  if (build.length > 0) {
+    parts.push(
+      `left out as build output: ${build.slice(0, 10).join(", ")}${build.length > 10 ? `, and ${build.length - 10} more` : ""}`
+    );
+  }
+  const deep = of("too_deep");
+  if (deep.length > 0) {
+    parts.push(
+      `not saved, nested too deep: ${deep.slice(0, 10).join(", ")}${deep.length > 10 ? `, and ${deep.length - 10} more` : ""}`
+    );
+  }
+  return `Directories in the sandbox not brought back (${parts.join("; ")}).`;
+}
+
+// src/lib/agent/workspace-sync.ts
+import { randomUUID } from "crypto";
+import { promises as fs } from "fs";
+import os from "os";
+import path from "path";
+var MAX_DIFF_CHARS = 8 * 1024 * 1024;
+var MAX_LISTED_PER_REASON = 20;
+var SyncStepError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "SyncStepError";
+  }
+};
+function emptyBase() {
+  return { version: 1, entries: [] };
+}
+function parseIncludeSecrets(values = []) {
+  const out = /* @__PURE__ */ new Set();
+  for (const raw of values) {
+    const value = raw.split(path.sep).join("/").replace(/^\.\//, "");
+    const segments = value.split("/");
+    if (!value || value.startsWith("/") || /^[A-Za-z]:/.test(value) || /[*?[\]{}()!+@\\]/.test(value) || segments.some((segment) => segment === "" || segment === "." || segment === "..")) {
+      throw new AgentLaunchError(
+        "sync_invalid_path",
+        `--include-secret takes a file path inside the project, not a pattern: ${raw}`
+      );
+    }
+    out.add(value);
+  }
+  return [...out].sort();
+}
+function size(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+function listed(paths) {
+  const shown = paths.slice(0, MAX_LISTED_PER_REASON).join(", ");
+  return paths.length > MAX_LISTED_PER_REASON ? `${shown}, and ${paths.length - MAX_LISTED_PER_REASON} more` : shown;
+}
+function planLines(plan, includeSecrets = []) {
+  const tracked = plan.entries.filter((entry) => entry.tracked).length;
+  const lines = [
+    "",
+    `Workspace sync: ${plan.projectDir}`,
+    `  Upload: ${plan.entries.length} file(s) (${tracked} tracked, ${plan.entries.length - tracked} untracked), ${size(plan.totalBytes)}${plan.git ? ", respecting .gitignore" : "; not a git work tree, so every file except .git and node_modules"}`
+  ];
+  const by = (reason) => plan.excluded.filter((entry) => entry.reason === reason).map((entry) => entry.path);
+  const secrets = by("secret");
+  if (secrets.length > 0) {
+    lines.push(
+      `  Left out, secret-like (they stay on this computer; --include-secret <path> uploads one): ${listed(secrets)}`
+    );
+  }
+  const named = includeSecrets.filter((rel) => plan.entries.some((entry) => entry.path === rel));
+  if (named.length > 0)
+    lines.push(`  Secret-like, uploaded because you named them: ${listed(named)}`);
+  const tooLarge = by("too_large");
+  if (tooLarge.length > 0) {
+    lines.push(
+      `  Left out, over the ${size(DEFAULT_SYNC_LIMITS.maxFileBytes)} file bound: ${listed(tooLarge)}`
+    );
+  }
+  const outside = by("symlink_outside_project");
+  if (outside.length > 0) {
+    lines.push(`  Left out, symlinks leading outside the project: ${listed(outside)}`);
+  }
+  const other = by("not_a_file");
+  if (other.length > 0) lines.push(`  Left out, not regular files: ${listed(other)}`);
+  const unselected = by("untracked_not_selected");
+  if (unselected.length > 0) {
+    lines.push(`  Left out, untracked and not selected: ${unselected.length}`);
+  }
+  if (plan.excludedNotListed > 0) {
+    lines.push(`  Left out and not listed (past the listing bound): ${plan.excludedNotListed}`);
+  }
+  lines.push(
+    `  Bounds: ${DEFAULT_SYNC_LIMITS.maxFiles} files and ${size(DEFAULT_SYNC_LIMITS.maxTotalBytes)} per upload.`,
+    "  Changes come back only as a diff you review: /pull in the session, or taskmarket agent pull after it."
+  );
+  return lines;
+}
+function captureProblemMessage(problem) {
+  const where = problem.sandboxId ? `sandbox ${problem.sandboxId}` : "its sandbox";
+  const what = problem.kind === "interrupted" ? `The last session in this project ended (at ${problem.at}) before the changes left in ${where} were saved.` : `The changes the last session left in ${where} could not be saved when it ended (${problem.reason}).`;
+  const recover = problem.sandboxId && problem.base ? " Save them now with taskmarket agent pull --recover, which reconnects to that sandbox while it still exists (an idle sandbox is stopped, and deleted, after about 15 minutes);" : "";
+  return `${what}${recover} taskmarket agent pull --discard drops this record and anything still in that sandbox. A new session starts in this project only after one of these.`;
+}
+function pendingMessage(pending) {
+  const parts = [];
+  if (pending.clean) parts.push(`${pending.clean} to apply`);
+  if (pending.conflict) parts.push(`${pending.conflict} in conflict with your local edits`);
+  if (pending.notSaved) parts.push(`${pending.notSaved} too large to have been saved`);
+  if (pending.tooDeep) {
+    parts.push(
+      `${pending.tooDeep} director(ies) nested too deep to have been saved (acknowledge each with taskmarket agent pull --keep-local <dir>)`
+    );
+  }
+  return `The last session in this project left ${unresolvedCount(pending)} change(s) you have not pulled (${parts.join(", ")}). Review and apply them with taskmarket agent pull; for a path you want to keep as it is here, taskmarket agent pull --keep-local <path>; or drop them all with taskmarket agent pull --discard. Then start a new session.`;
+}
+function refuseUnfinished(state, owner, notes) {
+  const problem = captureProblem(state, owner);
+  if (problem) {
+    throw new AgentLaunchError(
+      problem.kind === "interrupted" ? "sync_capture_interrupted" : "sync_capture_failed",
+      captureProblemMessage(problem)
+    );
+  }
+  if (state.capture?.state === "saved" && unresolvedCount(state.capture.pending) > 0) {
+    throw new AgentLaunchError("sync_pull_pending", pendingMessage(state.capture.pending));
+  }
+  const session = state.session;
+  if (session && !session.uploaded && killedSession(state, owner)) {
+    notes.push(
+      "",
+      `The last session here (--no-sync) ended without stopping sandbox ${session.sandboxId}. What the agent made there is not brought back unless you run taskmarket agent pull --recover before the sandbox stops on its own once idle (about 15 minutes).`
+    );
+    state.orphan = {
+      sandboxId: session.sandboxId,
+      at: session.startedAt,
+      base: session.base ?? { version: 1, entries: [] }
+    };
+    session.endedAt = (/* @__PURE__ */ new Date()).toISOString();
+  }
+}
+function syncLaunchError(error) {
+  if (error instanceof SyncError) {
+    throw new AgentLaunchError(`sync_${error.code}`, error.message);
+  }
+  throw error;
+}
+async function prepareWorkspaceSync(options) {
+  const projectRoot = await fs.realpath(options.cwd ?? process.cwd());
+  const includeSecrets = parseIncludeSecrets(options.includeSecrets);
+  const owner = options.owner ?? process.pid;
+  const notes = [];
+  const state = await claimProject(
+    projectRoot,
+    "session",
+    (current) => refuseUnfinished(current, owner, notes),
+    owner,
+    options.onClaimLost
+  );
+  if (notes.length > 0) options.say(notes);
+  try {
+    const prepared = await prepareClaimed(options, projectRoot, includeSecrets, state);
+    return { ...prepared, ...state.claim?.nonce ? { claimNonce: state.claim.nonce } : {} };
+  } catch (error) {
+    await releaseClaim(projectRoot, owner).catch(() => void 0);
+    throw error;
+  }
+}
+async function prepareClaimed(options, projectRoot, includeSecrets, state) {
+  if (options.mode === "none") {
+    options.say(["", "Workspace sync: off (--no-sync); the sandbox starts empty."]);
+    return { projectRoot, includeSecrets: [] };
+  }
+  const home = await fs.realpath(os.homedir()).catch(() => os.homedir());
+  if (projectRoot === home || path.parse(projectRoot).root === projectRoot) {
+    throw new AgentLaunchError(
+      "sync_project_unsafe",
+      `taskmarket agent uploads the directory it starts in, and ${projectRoot} is your home or a filesystem root. Start it in a project directory, or pass --no-sync.`
+    );
+  }
+  let plan;
+  try {
+    plan = await planUpload(projectRoot, { includeSecrets });
+  } catch (error) {
+    syncLaunchError(error);
+  }
+  const lines = planLines(plan, includeSecrets);
+  const approval = state.approval;
+  if (approval && includeSecrets.every((rel) => approval.includeSecrets.includes(rel))) {
+    options.say([...lines, `  Approved for this project on ${approval.approvedAt}.`]);
+    return { projectRoot, plan, includeSecrets };
+  }
+  if (options.mode === "sync") {
+    options.say([...lines, "  Approved with --sync, for this session only."]);
+    return { projectRoot, plan, includeSecrets };
+  }
+  if (!options.interactive) {
+    throw new AgentLaunchError(
+      "sync_approval_required",
+      "Uploading this project to the sandbox needs your approval. Run taskmarket agent at a terminal to approve it once for this project, pass --sync to approve this session, or --no-sync to start with an empty sandbox."
+    );
+  }
+  const prompter = options.prompter();
+  try {
+    prompter.say(lines);
+    if (!await prompter.confirm(
+      "Upload these files to your sandbox, now and in later sessions in this project?"
+    )) {
+      throw new AgentLaunchError(
+        "sync_declined",
+        "Nothing was uploaded and no sandbox was opened. Run taskmarket agent --no-sync to start with an empty sandbox."
+      );
+    }
+  } finally {
+    prompter.close();
+  }
+  const now = (options.now ?? (() => /* @__PURE__ */ new Date()))();
+  await updateSyncState(projectRoot, (next) => {
+    next.approval = { approvedAt: now.toISOString(), includeSecrets };
+  });
+  return { projectRoot, plan, includeSecrets };
+}
+async function uploadPlan(backend, plan, signal) {
+  try {
+    return await uploadWorkspace(backend, plan, { signal });
+  } catch (error) {
+    if (error instanceof SyncError) syncLaunchError(error);
+    throw new AgentLaunchError(
+      "sync_upload_failed",
+      `The project could not be uploaded to the sandbox: ${error.message}`
+    );
+  }
+}
+var UNSAVED_DETAIL = {
+  budget: `too large to save when the session ended (past the ${size(DEFAULT_SYNC_LIMITS.maxTotalBytes)} save budget)`,
+  skipped: "its contents were not saved when the session ended"
+};
+function relabel(change, unsaved) {
+  const reason = unsaved.get(change.path);
+  const counted = change.status === "unreadable" || change.status === "clean" || change.status === "conflict";
+  if (!reason || !counted || change.status === "in_sync") {
+    return { status: change.status, detail: change.detail };
+  }
+  if (reason === "too_large") {
+    return { status: "too_large", detail: `over ${DEFAULT_SYNC_LIMITS.maxFileBytes} bytes` };
+  }
+  return { status: "not_saved", detail: UNSAVED_DETAIL[reason] };
+}
+function summarize(changeSet, unsaved = /* @__PURE__ */ new Map()) {
+  const changes = [];
+  const counts = { clean: 0, conflict: 0, blocked: 0 };
+  for (const change of changeSet.changes) {
+    if (change.status === "in_sync") continue;
+    const { status, detail } = relabel(change, unsaved);
+    if (status === "clean") counts.clean++;
+    else if (status === "conflict") counts.conflict++;
+    else if (status === "not_saved") counts.notSaved = (counts.notSaved ?? 0) + 1;
+    else counts.blocked++;
+    const symlink = change.remote?.type === "symlink" || change.local?.type === "symlink";
+    const summary = {
+      path: change.path,
+      kind: change.kind,
+      status,
+      binary: change.binary,
+      symlink,
+      ...detail ? { detail } : {}
+    };
+    if ((status === "clean" || status === "conflict") && !change.binary && !symlink) {
+      const patch = renderChanges({ projectDir: changeSet.projectDir, changes: [change] });
+      let added = 0;
+      let removed = 0;
+      for (const line of patch.split("\n")) {
+        if (line.startsWith("+") && !line.startsWith("+++")) added++;
+        else if (line.startsWith("-") && !line.startsWith("---")) removed++;
+      }
+      summary.lines = { added, removed };
+    }
+    changes.push(summary);
+  }
+  return { changes, counts };
+}
+function remainingAfter(changeSet, applied) {
+  const done = new Set(applied);
+  const counts = { clean: 0, conflict: 0, blocked: 0 };
+  for (const change of changeSet.changes) {
+    if (change.status === "in_sync" || done.has(change.path)) continue;
+    if (change.status === "clean") counts.clean++;
+    else if (change.status === "conflict") counts.conflict++;
+    else counts.blocked++;
+  }
+  return counts;
+}
+function fullDiff(changeSet, maxChars = MAX_DIFF_CHARS) {
+  const text = renderChanges(changeSet);
+  return text.length > maxChars ? `${text.slice(0, maxChars)}
+... the diff is cut here; run taskmarket agent pull --diff after the session for all of it
+` : text;
+}
+function recordingBackend(inner) {
+  const files = /* @__PURE__ */ new Map();
+  let manifest = [];
+  const backend = {
+    kind: inner.kind,
+    root: inner.root,
+    connect: (signal) => inner.connect(signal),
+    close: () => inner.close(),
+    readFile: async (file, options) => {
+      const data = await inner.readFile(file, options);
+      files.set(file, data);
+      return data;
+    },
+    openForUpdate: (file, options) => inner.openForUpdate(file, options),
+    writeFile: (file, data, options) => inner.writeFile(file, data, options),
+    list: (dir, options) => inner.list(dir, options),
+    glob: (dir, pattern, options) => inner.glob(dir, pattern, options),
+    grep: (file, query, options) => inner.grep(file, query, options),
+    manifest: async (dir, options) => {
+      manifest = await inner.manifest(dir, options);
+      return manifest;
+    },
+    directories: (dir, parents, options) => inner.directories(dir, parents, options),
+    symlink: (file, target, options) => inner.symlink(file, target, options),
+    remove: (file, options) => inner.remove(file, options),
+    exec: (command, cwd, options) => inner.exec(command, cwd, options)
+  };
+  return { backend, files, manifest: () => manifest };
+}
+var readOnly = () => Promise.reject(new Error("The saved session changes are read-only"));
+function savedEntry(entry) {
+  if (entry.type === "symlink") return { path: entry.path, type: "symlink", target: entry.target };
+  return {
+    path: entry.path,
+    type: "file",
+    size: entry.size,
+    sha256: entry.unsaved ? "" : entry.sha256
+  };
+}
+function savedState(entry) {
+  if (!entry) return void 0;
+  const listed2 = savedEntry(entry);
+  return listed2.type === "symlink" ? { path: listed2.path, type: "symlink", target: listed2.target } : { path: listed2.path, type: "file", sha256: listed2.sha256 };
+}
+function unsavedPaths(manifest) {
+  const out = /* @__PURE__ */ new Map();
+  for (const entry of manifest) {
+    if (entry.type === "file" && entry.unsaved) out.set(entry.path, entry.unsaved);
+  }
+  return out;
+}
+function savedWorkspace(projectRoot, stored) {
+  const root = DEFAULT_SANDBOX_ROOT;
+  const manifest = stored.map(savedEntry);
+  const byPath = new Map(manifest.map((entry) => [entry.path, entry]));
+  const directories = /* @__PURE__ */ new Set();
+  for (const entry of manifest) {
+    for (let i = entry.path.indexOf("/"); i >= 0; i = entry.path.indexOf("/", i + 1)) {
+      directories.add(entry.path.slice(0, i));
+    }
+  }
+  return {
+    kind: "saved",
+    root,
+    connect: async () => ({ label: "saved session changes" }),
+    close: async () => void 0,
+    readFile: async (file, options) => {
+      const rel = file.startsWith(`${root}/`) ? file.slice(root.length + 1) : "";
+      const entry = byPath.get(rel);
+      if (!entry || entry.type !== "file" || !entry.sha256) {
+        throw new SandboxFileError("ENOENT", "open", file);
+      }
+      const data = await loadBlob(projectRoot, entry.sha256);
+      if (!data) throw new SandboxFileError("EIO", "read", file, "the saved copy is missing");
+      if (data.length > options.maxBytes) throw new SandboxFileError("EFBIG", "read", file);
+      return data;
+    },
+    openForUpdate: readOnly,
+    writeFile: readOnly,
+    list: readOnly,
+    glob: readOnly,
+    grep: readOnly,
+    manifest: async (_dir, options) => {
+      const within = options.within ? new Set(options.within) : void 0;
+      const parent = (rel) => rel.includes("/") ? rel.slice(0, rel.lastIndexOf("/")) : "";
+      const entries = manifest.filter(
+        (entry) => within ? within.has(parent(entry.path)) : !entry.path.split("/").some((segment) => options.prune.includes(segment))
+      );
+      if (entries.length > options.limit) throw new ManifestLimitError(options.limit);
+      return entries.map((entry) => ({ ...entry }));
+    },
+    directories: async (_dir, parents) => [...directories].filter(
+      (dir) => parents.includes(dir.includes("/") ? dir.slice(0, dir.lastIndexOf("/")) : "")
+    ),
+    symlink: readOnly,
+    remove: readOnly,
+    exec: readOnly
+  };
+}
+var ClaimLostError = class extends Error {
+  constructor() {
+    super(
+      "another taskmarket process took over this project, so this one does not write over its record"
+    );
+    this.name = "ClaimLostError";
+  }
+};
+var SessionSync = class {
+  constructor(options) {
+    this.options = options;
+    this.base = options.base;
+    this.now = options.now ?? (() => /* @__PURE__ */ new Date());
+  }
+  base;
+  review;
+  queue = Promise.resolve();
+  now;
+  serial(work) {
+    const next = this.queue.then(work, work);
+    this.queue = next.catch(() => void 0);
+    return next;
+  }
+  async record(change) {
+    try {
+      await updateSyncState(this.options.projectRoot, change);
+    } catch (error) {
+      this.options.log?.(
+        `Workspace sync: the state could not be saved: ${error.message}`
+      );
+    }
+  }
+  /**
+   * Records the base a `/pull` or `/sync` moved to, before the step reports success: if this
+   * process dies before the end-of-session save, `taskmarket agent pull --recover` compares the
+   * sandbox with this base, not the one the session started from, so a change already pulled and
+   * then edited (or deleted) here is not offered back as the sandbox's.
+   */
+  /** Refuses to write when another process holds the project under another claim. */
+  assertHeld(state) {
+    const nonce = this.options.claimNonce;
+    if (nonce && state.claim?.nonce !== nonce) throw new ClaimLostError();
+  }
+  /**
+   * Before `/pull` writes local files or `/sync` writes the sandbox: refuses, touching nothing,
+   * when another process has taken the project.
+   */
+  async ensureHeld() {
+    const nonce = this.options.claimNonce;
+    if (!nonce) return;
+    const state = await loadSyncState(this.options.projectRoot);
+    if (claimLost(nonce) || state.claim?.nonce !== nonce) {
+      const error = new ClaimLostError();
+      this.options.log?.(`Workspace sync: sync_claim_lost: ${error.message}`);
+      throw new SyncStepError("sync_claim_lost", error.message);
+    }
+  }
+  async keepBase(change) {
+    const base = this.base;
+    try {
+      await updateSyncState(this.options.projectRoot, (state) => {
+        this.assertHeld(state);
+        change(state);
+        if (state.session?.pid === process.pid && !state.session.endedAt) {
+          state.session.base = base;
+        }
+      });
+    } catch (error) {
+      this.options.log?.(`Workspace sync: sync_state_failed: ${error.message}`);
+      if (error instanceof ClaimLostError)
+        throw new SyncStepError("sync_claim_lost", error.message);
+      throw new SyncStepError(
+        "sync_state_failed",
+        `The step was done, but its record could not be saved (${error.message}); if this session is cut off, taskmarket agent pull --recover may offer these paths again`
+      );
+    }
+  }
+  fail(error) {
+    if (error instanceof SyncStepError) throw error;
+    const code = error instanceof SyncError ? `sync_${error.code}` : error.name === "SandboxUnavailableError" ? "sandbox_unavailable" : error instanceof ManifestLimitError ? "sync_too_many_files" : "sync_failed";
+    this.options.log?.(`Workspace sync: ${code}: ${error.message}`);
+    throw new SyncStepError(code, error.message);
+  }
+  /** `/pull`: what the sandbox changed since the base, compared with this computer. */
+  reviewChanges() {
+    return this.serial(async () => {
+      let changeSet;
+      try {
+        changeSet = await diffWorkspace(this.options.backend, this.options.projectRoot, this.base);
+      } catch (error) {
+        this.fail(error);
+      }
+      const id = randomUUID();
+      this.review = { id, changeSet };
+      const { changes, counts } = summarize(changeSet);
+      await this.record((state) => {
+        if (state.session)
+          state.session.pending = { ...counts, checkedAt: this.now().toISOString() };
+      });
+      return {
+        version: SYNC_VIEW_VERSION,
+        reviewId: id,
+        changes: changes.slice(0, MAX_LISTED_CHANGES),
+        total: changes.length,
+        counts,
+        ...changeSet.leftOut ? { leftOut: changeSet.leftOut } : {}
+      };
+    });
+  }
+  reviewed(reviewId) {
+    if (!this.review || this.review.id !== reviewId) {
+      throw new SyncStepError(
+        "review_stale",
+        "That review is no longer current; run /pull again to see the changes as they are now"
+      );
+    }
+    return this.review.changeSet;
+  }
+  /** The full diff of the current review. */
+  diff(reviewId) {
+    return this.serial(async () => fullDiff(this.reviewed(reviewId)));
+  }
+  /**
+   * Applies the reviewed changes the person approved: every `clean` one. Conflicts are never
+   * overwritten from inside the session, and each path is checked again before it is written.
+   */
+  apply(reviewId) {
+    return this.serial(async () => {
+      const changeSet = this.reviewed(reviewId);
+      this.review = void 0;
+      await this.ensureHeld();
+      let result;
+      try {
+        result = await applyChanges(changeSet, this.base);
+      } catch (error) {
+        this.fail(error);
+      }
+      this.base = result.base;
+      const remaining = remainingAfter(changeSet, result.applied);
+      await this.keepBase((state) => {
+        if (!state.session) return;
+        state.session.lastPullAt = this.now().toISOString();
+        state.session.pending = { ...remaining, checkedAt: this.now().toISOString() };
+      });
+      return {
+        version: SYNC_VIEW_VERSION,
+        applied: result.applied,
+        skipped: result.skipped,
+        remaining
+      };
+    });
+  }
+  /** `/sync`: re-sends local edits; a path the sandbox changed too is left alone on both sides. */
+  push() {
+    return this.serial(async () => {
+      if (!this.options.uploaded) {
+        throw new SyncStepError(
+          "sync_not_uploaded",
+          "This session started with --no-sync, so nothing of this project is sent to the sandbox"
+        );
+      }
+      this.review = void 0;
+      await this.ensureHeld();
+      let result;
+      try {
+        result = await pushLocalChanges(this.options.backend, this.options.projectRoot, this.base, {
+          includeSecrets: this.options.includeSecrets
+        });
+      } catch (error) {
+        this.fail(error);
+      }
+      this.base = result.base;
+      await this.keepBase((state) => {
+        if (state.session) state.session.lastPushAt = this.now().toISOString();
+      });
+      return { version: SYNC_VIEW_VERSION, pushed: result.pushed, conflicts: result.conflicts };
+    });
+  }
+  /**
+   * Pi has exited, so the session is over: records the `saving` marker now, before running
+   * purchases drain and `capture` starts. A controller that dies anywhere from here until the
+   * save is recorded then leaves an interrupted save (`sync_capture_interrupted`, in `status` with
+   * its sandbox), in either mode, rather than a session that looks cut off while Pi ran. `capture`
+   * writes the marker again; a failure here is only logged, since `capture` still runs.
+   */
+  beginSave() {
+    return this.serial(async () => {
+      const { projectRoot, sandboxId } = this.options;
+      const base = this.base;
+      try {
+        await updateSyncState(projectRoot, (state) => {
+          this.assertHeld(state);
+          state.saving = savingMarker(this.now().toISOString(), sandboxId, base);
+        });
+      } catch (error) {
+        this.options.log?.(
+          `Workspace sync: the start of the save was not recorded: ${error.message}`
+        );
+      }
+    });
+  }
+  /**
+   * At the end of the session, before the sandbox stops: saves what is left to pull, so
+   * `taskmarket agent pull` can review it without the sandbox. Never throws: a failure is
+   * recorded (and `status`, `pull` and the next launch say so) and returned, and the caller then
+   * keeps the sandbox rather than stopping it.
+   *
+   * Crash-safe in this order: a `saving` marker first (left behind, it tells the next launch the
+   * save was interrupted); then the new files, under their hashes beside the old ones; then the
+   * new record, replacing the old one and the marker in one atomic write; only then are the files
+   * no record names deleted.
+   */
+  capture(signal, options = {}) {
+    const endSession = options.endSession ?? true;
+    return this.serial(async () => {
+      const { projectRoot, sandboxId } = this.options;
+      const startedAt = this.now().toISOString();
+      const base = this.base;
+      const budget = this.options.saveBudgetBytes ?? DEFAULT_SYNC_LIMITS.maxTotalBytes;
+      try {
+        await updateSyncState(projectRoot, (state) => {
+          this.assertHeld(state);
+          state.saving = savingMarker(startedAt, sandboxId, base);
+        });
+        const recording = recordingBackend(this.options.backend);
+        const changeSet = await diffWorkspace(recording.backend, projectRoot, base, { signal });
+        const changed = new Set(changeSet.changes.map((change) => change.path));
+        const known = new Map(base.entries.map((entry) => [entry.path, entry]));
+        const manifest = [];
+        const unsaved = /* @__PURE__ */ new Map();
+        let saved = 0;
+        if (changeSet.changes.some((change) => change.status !== "in_sync")) {
+          for (const entry of recording.manifest()) {
+            const was = known.get(entry.path);
+            const unchanged = entry.type === "symlink" ? was?.type === "symlink" && was.target === entry.target : was?.type === "file" && was.sha256 === entry.sha256;
+            if (!unchanged && !changed.has(entry.path)) continue;
+            if (entry.type === "symlink" || unchanged) {
+              manifest.push({ ...entry });
+              continue;
+            }
+            signal?.throwIfAborted();
+            const data = recording.files.get(`${recording.backend.root}/${entry.path}`);
+            if (data && saved + data.length <= budget) {
+              saved += data.length;
+              const sha256 = await saveBlob(projectRoot, data);
+              manifest.push({ path: entry.path, type: "file", size: data.length, sha256 });
+              continue;
+            }
+            const reason = data ? "budget" : entry.sha256 === "" ? void 0 : entry.size > DEFAULT_SYNC_LIMITS.maxFileBytes ? "too_large" : "skipped";
+            if (reason) unsaved.set(entry.path, reason);
+            manifest.push({ ...entry, ...reason ? { unsaved: reason } : {} });
+          }
+        }
+        const { counts } = summarize(changeSet, unsaved);
+        const tooDeep = (changeSet.leftOut ?? []).filter((dir) => dir.reason === "too_deep");
+        if (tooDeep.length > 0) counts.tooDeep = tooDeep.length;
+        const total = counts.clean + counts.conflict + counts.blocked + (counts.notSaved ?? 0) + (counts.tooDeep ?? 0);
+        await updateSyncState(projectRoot, (state) => {
+          this.assertHeld(state);
+          const earlier = state.capture;
+          if (earlier?.state === "failed" && earlier.sandboxId !== sandboxId) {
+            throw new Error(
+              `the changes of an earlier session (sandbox ${earlier.sandboxId ?? "unknown"}) are still unresolved`
+            );
+          }
+          if (total > 0) {
+            state.capture = {
+              state: "saved",
+              capturedAt: startedAt,
+              ...sandboxId ? { sandboxId } : {},
+              base,
+              manifest,
+              pending: counts,
+              ...changeSet.leftOut ? { leftOut: changeSet.leftOut } : {}
+            };
+          } else {
+            delete state.capture;
+          }
+          delete state.saving;
+          if (state.orphan && state.orphan.sandboxId === sandboxId) delete state.orphan;
+          if (ownSession(state, endSession, sandboxId)) {
+            state.session.endedAt = startedAt;
+            state.session.pending = { ...counts, checkedAt: startedAt };
+          }
+        });
+        await pruneBlobs(projectRoot).catch(
+          (error) => this.options.log?.(`Workspace sync: old saved files were not removed: ${error.message}`)
+        );
+        return {
+          saved: true,
+          pending: counts,
+          ...changeSet.leftOut ? { leftOut: changeSet.leftOut } : {}
+        };
+      } catch (error) {
+        if (error instanceof ClaimLostError) {
+          this.options.log?.(`Workspace sync: ${error.message}`);
+          return { saved: false, reason: error.message, claimLost: true };
+        }
+        const reason = error instanceof ManifestLimitError ? `the sandbox holds more than ${error.limit} files outside what the project ignores` : error.message;
+        this.options.log?.(`Workspace sync: the session's changes could not be saved: ${reason}`);
+        await this.record((state) => {
+          const nonce = this.options.claimNonce;
+          if (nonce && state.claim?.nonce !== nonce) return;
+          const earlier = state.capture;
+          if (earlier?.state !== "failed" || earlier.sandboxId === sandboxId) {
+            state.capture = {
+              state: "failed",
+              capturedAt: startedAt,
+              ...sandboxId ? { sandboxId } : {},
+              base,
+              reason
+            };
+          }
+          if (state.saving?.pid === process.pid) delete state.saving;
+          if (ownSession(state, endSession, sandboxId)) state.session.endedAt = startedAt;
+        });
+        return { saved: false, reason };
+      }
+    });
+  }
+};
+function savingMarker(startedAt, sandboxId, base) {
+  return { pid: process.pid, startedAt, ...sandboxId ? { sandboxId } : {}, base };
+}
+function ownSession(state, endSession, sandboxId) {
+  const session = state.session;
+  if (!session || session.endedAt) return false;
+  if (endSession && session.pid === process.pid) return true;
+  return !!sandboxId && session.sandboxId === sandboxId;
+}
+async function recordSessionStart(input) {
+  const now = (input.now ?? /* @__PURE__ */ new Date()).toISOString();
+  await updateSyncState(input.projectRoot, (state) => {
+    state.session = {
+      ...input.sandboxId ? { sandboxId: input.sandboxId } : {},
+      pid: process.pid,
+      startedAt: now,
+      uploaded: input.plan !== void 0,
+      base: input.base,
+      ...input.plan ? {
+        lastUploadAt: now,
+        uploadedFiles: input.base.entries.length,
+        uploadedBytes: input.plan.totalBytes
+      } : {}
+    };
+  });
+}
+async function recordSessionEnd(projectRoot, now = /* @__PURE__ */ new Date()) {
+  await updateSyncState(projectRoot, (state) => {
+    if (!state.session || state.session.pid !== process.pid || state.session.endedAt) return;
+    state.session.endedAt = now.toISOString();
+  });
+}
+
+export {
+  SYNC_VIEW_VERSION,
+  changeLine,
+  countsLine,
+  leftOutNote,
+  emptyBase,
+  captureProblemMessage,
+  prepareWorkspaceSync,
+  uploadPlan,
+  summarize,
+  fullDiff,
+  savedState,
+  unsavedPaths,
+  savedWorkspace,
+  SessionSync,
+  recordSessionStart,
+  recordSessionEnd
+};