@right-link/paperclip-plugin-codex-remote 0.3.1 → 0.3.2

package/dist/chunk-ZLN6QQMX.js

@@ -0,0 +1,3267 @@
+// ../../adapter-utils/src/server-utils.ts
+import { spawn as spawn2 } from "node:child_process";
+import { createHash as createHash2, randomUUID as randomUUID2 } from "node:crypto";
+import { constants as fsConstants3, promises as fs3 } from "node:fs";
+import os2 from "node:os";
+import path3 from "node:path";
+
+// ../../adapter-utils/src/remote-execution-env.ts
+var REMOTE_EXECUTION_ENV_IDENTITY_KEYS = /* @__PURE__ */ new Set([
+  "PATH",
+  "HOME",
+  "PWD",
+  "SHELL",
+  "USER",
+  "LOGNAME",
+  "NVM_DIR",
+  "TMPDIR",
+  "TMP",
+  "TEMP",
+  "XDG_CONFIG_HOME",
+  "XDG_CACHE_HOME",
+  "XDG_DATA_HOME",
+  "XDG_STATE_HOME",
+  "XDG_RUNTIME_DIR"
+]);
+function readEnvValueCaseInsensitive(env, key) {
+  const direct = env[key];
+  if (typeof direct === "string") return direct;
+  const upper = key.toUpperCase();
+  for (const [candidateKey, candidateValue] of Object.entries(env)) {
+    if (candidateKey.toUpperCase() === upper && typeof candidateValue === "string") {
+      return candidateValue;
+    }
+  }
+  return void 0;
+}
+function sanitizeRemoteExecutionEnv(env, inheritedEnv = process.env) {
+  const sanitized = {};
+  for (const [key, value] of Object.entries(env)) {
+    const normalizedKey = key.toUpperCase();
+    if (!REMOTE_EXECUTION_ENV_IDENTITY_KEYS.has(normalizedKey)) {
+      sanitized[key] = value;
+      continue;
+    }
+    const inheritedValue = readEnvValueCaseInsensitive(inheritedEnv, key);
+    if (typeof inheritedValue === "string" && inheritedValue === value) {
+      continue;
+    }
+    sanitized[key] = value;
+  }
+  return sanitized;
+}
+
+// ../../adapter-utils/src/ssh.ts
+import { randomUUID } from "node:crypto";
+import { execFile, spawn } from "node:child_process";
+import { constants as fsConstants2, createReadStream as createReadStream2, createWriteStream, promises as fs2 } from "node:fs";
+import os from "node:os";
+import path2 from "node:path";
+import { Transform } from "node:stream";
+
+// ../../adapter-utils/src/workspace-restore-merge.ts
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { constants as fsConstants, promises as fs } from "node:fs";
+import path from "node:path";
+
+// ../../adapter-utils/src/exclude-patterns.ts
+function isRelativePathOrDescendant(relative, candidate) {
+  return relative === candidate || relative.startsWith(`${candidate}/`);
+}
+function pathContainsSegmentOrDescendant(relative, segment) {
+  return relative === segment || relative.startsWith(`${segment}/`) || relative.endsWith(`/${segment}`) || relative.includes(`/${segment}/`);
+}
+function excludePatternMatches(relative, pattern) {
+  if (pattern.startsWith("*/") && pattern.endsWith("/*")) {
+    return pathContainsSegmentOrDescendant(relative, pattern.slice(2, -2));
+  }
+  if (pattern.startsWith("*/")) {
+    return pathContainsSegmentOrDescendant(relative, pattern.slice(2));
+  }
+  if (pattern.endsWith("/*")) {
+    const base = pattern.slice(0, -2);
+    return relative.startsWith(`${base}/`);
+  }
+  return isRelativePathOrDescendant(relative, pattern);
+}
+function shouldExcludePath(relative, exclude) {
+  return exclude.some((entry) => excludePatternMatches(relative, entry));
+}
+
+// ../../adapter-utils/src/workspace-restore-merge.ts
+async function hashFile(filePath) {
+  return await new Promise((resolve, reject) => {
+    const hash = createHash("sha256");
+    const stream = createReadStream(filePath);
+    stream.on("data", (chunk) => hash.update(chunk));
+    stream.on("error", reject);
+    stream.on("end", () => resolve(hash.digest("hex")));
+  });
+}
+async function walkDirectory(root, exclude, relative = "", out = /* @__PURE__ */ new Map()) {
+  const current = relative ? path.join(root, relative) : root;
+  const entries = await fs.readdir(current, { withFileTypes: true }).catch(() => []);
+  entries.sort((left, right) => left.name.localeCompare(right.name));
+  for (const entry of entries) {
+    const nextRelative = relative ? path.posix.join(relative, entry.name) : entry.name;
+    if (shouldExcludePath(nextRelative, exclude)) continue;
+    const fullPath = path.join(root, nextRelative);
+    const stats = await fs.lstat(fullPath);
+    if (!stats.isDirectory() && !stats.isSymbolicLink() && !stats.isFile()) {
+      continue;
+    }
+    if (stats.isDirectory()) {
+      out.set(nextRelative, { kind: "dir" });
+      await walkDirectory(root, exclude, nextRelative, out);
+      continue;
+    }
+    if (stats.isSymbolicLink()) {
+      out.set(nextRelative, {
+        kind: "symlink",
+        target: await fs.readlink(fullPath)
+      });
+      continue;
+    }
+    out.set(nextRelative, {
+      kind: "file",
+      mode: stats.mode,
+      hash: await hashFile(fullPath)
+    });
+  }
+  return out;
+}
+function entriesMatch(left, right) {
+  if (!left || !right) return false;
+  if (left.kind !== right.kind) return false;
+  if (left.kind === "dir") return true;
+  if (left.kind === "symlink" && right.kind === "symlink") {
+    return left.target === right.target;
+  }
+  if (left.kind === "file" && right.kind === "file") {
+    return left.mode === right.mode && left.hash === right.hash;
+  }
+  return false;
+}
+async function isHolderAlive(lockDir) {
+  try {
+    const raw = await fs.readFile(path.join(lockDir, "owner.json"), "utf8");
+    const owner = JSON.parse(raw);
+    const pid = typeof owner.pid === "number" && Number.isFinite(owner.pid) && owner.pid > 0 ? owner.pid : null;
+    if (pid === null) {
+      return false;
+    }
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch {
+      return false;
+    }
+  } catch {
+    return false;
+  }
+}
+async function acquireDirectoryMergeLock(lockDir) {
+  const deadline = Date.now() + 3e4;
+  while (true) {
+    try {
+      await fs.mkdir(lockDir);
+      await fs.writeFile(
+        path.join(lockDir, "owner.json"),
+        `${JSON.stringify({ pid: process.pid, createdAt: (/* @__PURE__ */ new Date()).toISOString() })}
+`,
+        "utf8"
+      );
+      return async () => {
+        await fs.rm(lockDir, { recursive: true, force: true }).catch(() => void 0);
+      };
+    } catch (error) {
+      const code = error && typeof error === "object" ? error.code : null;
+      if (code !== "EEXIST") throw error;
+      if (!await isHolderAlive(lockDir)) {
+        await fs.rm(lockDir, { recursive: true, force: true }).catch(() => void 0);
+        continue;
+      }
+      if (Date.now() >= deadline) {
+        throw new Error(`Timed out waiting for workspace restore lock at ${lockDir}`);
+      }
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+  }
+}
+async function withDirectoryMergeLock(targetDir, fn) {
+  const releaseLock = await acquireDirectoryMergeLock(`${targetDir}.paperclip-restore.lock`);
+  try {
+    return await fn();
+  } finally {
+    await releaseLock();
+  }
+}
+async function copySnapshotEntry(sourceDir, targetDir, relative, entry) {
+  const sourcePath = path.join(sourceDir, relative);
+  const targetPath = path.join(targetDir, relative);
+  if (entry.kind === "dir") {
+    const existing = await fs.lstat(targetPath).catch(() => null);
+    if (existing?.isDirectory()) {
+      return;
+    }
+    if (existing) {
+      await fs.rm(targetPath, { recursive: true, force: true }).catch(() => void 0);
+    }
+    await fs.mkdir(targetPath, { recursive: true });
+    return;
+  }
+  await fs.mkdir(path.dirname(targetPath), { recursive: true });
+  await fs.rm(targetPath, { recursive: true, force: true }).catch(() => void 0);
+  if (entry.kind === "symlink") {
+    await fs.symlink(entry.target, targetPath);
+    return;
+  }
+  await fs.copyFile(sourcePath, targetPath, fsConstants.COPYFILE_FICLONE).catch(async () => {
+    await fs.copyFile(sourcePath, targetPath);
+  });
+  await fs.chmod(targetPath, entry.mode);
+}
+async function captureDirectorySnapshot(rootDir, options = {}) {
+  const exclude = [...new Set(options.exclude ?? [])];
+  return {
+    exclude,
+    entries: await walkDirectory(rootDir, exclude)
+  };
+}
+async function mergeDirectoryWithBaseline(input) {
+  const source = await captureDirectorySnapshot(input.sourceDir, { exclude: input.baseline.exclude });
+  await withDirectoryMergeLock(input.targetDir, async () => {
+    await input.beforeApply?.();
+    const current = await captureDirectorySnapshot(input.targetDir, { exclude: input.baseline.exclude });
+    const deletedLeafEntries = [...input.baseline.entries.entries()].filter(([relative, entry]) => entry.kind !== "dir" && !source.entries.has(relative)).sort(([left], [right]) => right.length - left.length);
+    for (const [relative, baselineEntry] of deletedLeafEntries) {
+      if (!entriesMatch(current.entries.get(relative), baselineEntry)) continue;
+      await fs.rm(path.join(input.targetDir, relative), { recursive: true, force: true }).catch(() => void 0);
+    }
+    const deletedDirs = [...input.baseline.entries.entries()].filter(([relative, entry]) => entry.kind === "dir" && !source.entries.has(relative)).sort(([left], [right]) => right.length - left.length);
+    for (const [relative] of deletedDirs) {
+      await fs.rmdir(path.join(input.targetDir, relative)).catch(() => void 0);
+    }
+    const changedSourceEntries = [...source.entries.entries()].filter(([relative, entry]) => !entriesMatch(input.baseline.entries.get(relative), entry)).sort(([left], [right]) => left.localeCompare(right));
+    for (const [relative, entry] of changedSourceEntries) {
+      await copySnapshotEntry(input.sourceDir, input.targetDir, relative, entry);
+    }
+  });
+}
+
+// ../../adapter-utils/src/runtime-progress.ts
+var BYTES_PER_MB = 1024 * 1024;
+function formatMb(bytes) {
+  return (Math.max(0, bytes) / BYTES_PER_MB).toFixed(1);
+}
+function clampPercent(value) {
+  if (!Number.isFinite(value)) return 0;
+  return Math.min(100, Math.max(0, Math.round(value)));
+}
+function createRuntimeProgressReporter(options) {
+  const stepPercent = options.stepPercent && options.stepPercent > 0 ? options.stepPercent : 10;
+  const minIntervalMs = options.minIntervalMs && options.minIntervalMs > 0 ? options.minIntervalMs : 2e3;
+  const now = options.now ?? Date.now;
+  const prefix = `[paperclip] ${options.phase}${options.label ? ` ${options.label}` : ""} ${options.direction} ${options.target}`;
+  let lastEmitAt = null;
+  let lastStep = -1;
+  let lastDoneBytes = 0;
+  let lastTotalBytes = null;
+  let completed = false;
+  function buildLine(doneBytes, totalBytes) {
+    if (totalBytes != null && totalBytes > 0) {
+      const pct = clampPercent(doneBytes / totalBytes * 100);
+      return `${prefix}: ${pct}% (${formatMb(doneBytes)}/${formatMb(totalBytes)} MB)
+`;
+    }
+    return `${prefix}: ${formatMb(doneBytes)} MB
+`;
+  }
+  function buildFailLine(doneBytes, totalBytes) {
+    if (totalBytes != null && totalBytes > 0) {
+      const pct = clampPercent(doneBytes / totalBytes * 100);
+      return `${prefix}: failed at ${pct}% (${formatMb(doneBytes)}/${formatMb(totalBytes)} MB)
+`;
+    }
+    return `${prefix}: failed after ${formatMb(doneBytes)} MB
+`;
+  }
+  async function emit(doneBytes, totalBytes) {
+    lastEmitAt = now();
+    if (totalBytes != null && totalBytes > 0) {
+      lastStep = Math.floor(doneBytes / totalBytes * 100 / stepPercent);
+    }
+    await options.sink(buildLine(doneBytes, totalBytes));
+  }
+  return {
+    async report(doneBytes, totalBytes) {
+      lastDoneBytes = doneBytes;
+      lastTotalBytes = totalBytes;
+      if (completed) return;
+      const elapsedOk = lastEmitAt == null || now() - lastEmitAt >= minIntervalMs;
+      if (totalBytes != null && totalBytes > 0) {
+        const terminal = doneBytes >= totalBytes;
+        const step = Math.floor(doneBytes / totalBytes * 100 / stepPercent);
+        const stepOk = step > lastStep;
+        if (terminal || stepOk || elapsedOk) {
+          await emit(doneBytes, totalBytes);
+        }
+        if (terminal) completed = true;
+        return;
+      }
+      if (elapsedOk) {
+        await emit(doneBytes, totalBytes);
+      }
+    },
+    async complete(doneBytes, totalBytes) {
+      if (completed) return;
+      completed = true;
+      const total = totalBytes !== void 0 ? totalBytes : lastTotalBytes;
+      const done = doneBytes !== void 0 ? doneBytes : total != null && total > 0 ? total : lastDoneBytes;
+      await options.sink(buildLine(done, total));
+    },
+    async fail(doneBytes, totalBytes) {
+      if (completed) return;
+      completed = true;
+      const total = totalBytes !== void 0 ? totalBytes : lastTotalBytes;
+      const done = doneBytes !== void 0 ? doneBytes : lastDoneBytes;
+      await options.sink(buildFailLine(done, total));
+    }
+  };
+}
+
+// ../../adapter-utils/src/ssh.ts
+function createSshCommandManagedRuntimeRunner(input) {
+  const defaultCwd = input.defaultCwd?.trim() || input.spec.remoteCwd;
+  const maxBufferBytes = typeof input.maxBufferBytes === "number" && Number.isFinite(input.maxBufferBytes) && input.maxBufferBytes > 0 ? Math.trunc(input.maxBufferBytes) : 1024 * 1024;
+  return {
+    execute: async (commandInput) => {
+      const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+      const command = commandInput.command.trim();
+      const args = commandInput.args ?? [];
+      const cwd = commandInput.cwd?.trim() || defaultCwd;
+      const envEntries = Object.entries(commandInput.env ?? {}).filter((entry) => typeof entry[1] === "string");
+      const envPrefix = envEntries.length > 0 ? `env ${envEntries.map(([key, value]) => `${key}=${shellQuote(value)}`).join(" ")} ` : "";
+      const exportPrefix = envEntries.length > 0 ? envEntries.map(([key, value]) => `export ${key}=${shellQuote(value)};`).join(" ") + " " : "";
+      const commandScript = command === "sh" || command === "bash" ? (args[0] === "-c" || args[0] === "-lc") && typeof args[1] === "string" ? `${exportPrefix}${args[1]}` : `${envPrefix}exec ${[shellQuote(command), ...args.map((arg) => shellQuote(arg))].join(" ")}` : `${envPrefix}exec ${[shellQuote(command), ...args.map((arg) => shellQuote(arg))].join(" ")}`;
+      const remoteCommand = `cd ${shellQuote(cwd)} && ${commandScript}`;
+      try {
+        const result = await runSshCommand(input.spec, remoteCommand, {
+          stdin: commandInput.stdin,
+          timeoutMs: commandInput.timeoutMs,
+          maxBuffer: maxBufferBytes
+        });
+        if (result.stdout) await commandInput.onLog?.("stdout", result.stdout);
+        if (result.stderr) await commandInput.onLog?.("stderr", result.stderr);
+        return {
+          exitCode: 0,
+          signal: null,
+          timedOut: false,
+          stdout: result.stdout,
+          stderr: result.stderr,
+          pid: null,
+          startedAt
+        };
+      } catch (error) {
+        const failure = error;
+        const stdout = typeof failure.stdout === "string" ? failure.stdout : "";
+        const stderr = typeof failure.stderr === "string" ? failure.stderr : error instanceof Error ? error.message : String(error);
+        if (stdout) await commandInput.onLog?.("stdout", stdout);
+        if (stderr) await commandInput.onLog?.("stderr", stderr);
+        return {
+          exitCode: typeof failure.code === "number" ? failure.code : null,
+          signal: typeof failure.signal === "string" ? failure.signal : null,
+          timedOut: failure.killed === true,
+          stdout,
+          stderr,
+          pid: null,
+          startedAt
+        };
+      }
+    }
+  };
+}
+function shellQuote(value) {
+  return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+function isValidShellEnvKey(value) {
+  return /^[A-Za-z_][A-Za-z0-9_]*$/.test(value);
+}
+function parseSshRemoteExecutionSpec(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  const parsed = value;
+  const host = typeof parsed.host === "string" ? parsed.host.trim() : "";
+  const username = typeof parsed.username === "string" ? parsed.username.trim() : "";
+  const remoteCwd = typeof parsed.remoteCwd === "string" ? parsed.remoteCwd.trim() : "";
+  const portValue = typeof parsed.port === "number" ? parsed.port : Number(parsed.port);
+  if (!host || !username || !remoteCwd || !Number.isInteger(portValue) || portValue < 1 || portValue > 65535) {
+    return null;
+  }
+  return {
+    host,
+    port: portValue,
+    username,
+    remoteCwd,
+    remoteWorkspacePath: typeof parsed.remoteWorkspacePath === "string" && parsed.remoteWorkspacePath.trim().length > 0 ? parsed.remoteWorkspacePath.trim() : remoteCwd,
+    privateKey: typeof parsed.privateKey === "string" && parsed.privateKey.length > 0 ? parsed.privateKey : null,
+    knownHosts: typeof parsed.knownHosts === "string" && parsed.knownHosts.length > 0 ? parsed.knownHosts : null,
+    strictHostKeyChecking: typeof parsed.strictHostKeyChecking === "boolean" ? parsed.strictHostKeyChecking : true
+  };
+}
+async function execFileText(file, args, options = {}) {
+  return await new Promise((resolve, reject) => {
+    execFile(
+      file,
+      args,
+      {
+        timeout: options.timeout ?? 15e3,
+        maxBuffer: options.maxBuffer ?? 1024 * 128
+      },
+      (error, stdout, stderr) => {
+        if (error) {
+          reject(Object.assign(error, { stdout: stdout ?? "", stderr: stderr ?? "" }));
+          return;
+        }
+        resolve({
+          stdout: stdout ?? "",
+          stderr: stderr ?? ""
+        });
+      }
+    );
+  });
+}
+async function spawnText(file, args, options = {}) {
+  return await new Promise((resolve, reject) => {
+    const child = spawn(file, args, {
+      stdio: [options.stdin != null ? "pipe" : "ignore", "pipe", "pipe"]
+    });
+    const maxBuffer = options.maxBuffer ?? 1024 * 128;
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    let timedOut = false;
+    const finishReject = (error) => {
+      if (settled) return;
+      settled = true;
+      error.stdout = stdout;
+      error.stderr = stderr;
+      error.killed = timedOut;
+      reject(error);
+    };
+    const append = (streamName, chunk) => {
+      const text = String(chunk);
+      if (streamName === "stdout") {
+        stdout += text;
+      } else {
+        stderr += text;
+      }
+      if (Buffer.byteLength(stdout, "utf8") > maxBuffer || Buffer.byteLength(stderr, "utf8") > maxBuffer) {
+        child.kill("SIGTERM");
+        finishReject(Object.assign(new Error(`Process output exceeded maxBuffer of ${maxBuffer} bytes.`), {
+          code: null
+        }));
+      }
+    };
+    let killEscalation = null;
+    const timeout = options.timeout && options.timeout > 0 ? setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGTERM");
+      killEscalation = setTimeout(() => {
+        try {
+          child.kill("SIGKILL");
+        } catch {
+        }
+      }, 5e3);
+      killEscalation.unref?.();
+    }, options.timeout) : null;
+    const clearTimers = () => {
+      if (timeout) clearTimeout(timeout);
+      if (killEscalation) clearTimeout(killEscalation);
+    };
+    child.stdout?.on("data", (chunk) => {
+      append("stdout", chunk);
+    });
+    child.stderr?.on("data", (chunk) => {
+      append("stderr", chunk);
+    });
+    child.on("error", (error) => {
+      clearTimers();
+      finishReject(Object.assign(error, { code: null }));
+    });
+    child.on("close", (code, signal) => {
+      clearTimers();
+      if (settled) return;
+      settled = true;
+      if (code === 0) {
+        resolve({ stdout, stderr });
+        return;
+      }
+      reject(Object.assign(new Error(stderr.trim() || stdout.trim() || `Process exited with code ${code ?? -1}`), {
+        stdout,
+        stderr,
+        code,
+        signal,
+        killed: timedOut
+      }));
+    });
+    if (options.stdin != null && child.stdin) {
+      child.stdin.end(options.stdin);
+    }
+  });
+}
+async function runLocalGit(localDir, args, options = {}) {
+  return await execFileText("git", ["-C", localDir, ...args], options);
+}
+async function withTempFile(prefix, contents, mode) {
+  const dir = await fs2.mkdtemp(path2.join(os.tmpdir(), prefix));
+  const filePath = path2.join(dir, "payload");
+  const normalizedContents = contents.endsWith("\n") ? contents : `${contents}
+`;
+  await fs2.writeFile(filePath, normalizedContents, { mode, encoding: "utf8" });
+  return {
+    path: filePath,
+    cleanup: async () => {
+      await fs2.rm(dir, { recursive: true, force: true }).catch(() => void 0);
+    }
+  };
+}
+async function createSshAuthArgs(config) {
+  const tempFiles = [];
+  const sshArgs = [
+    "-o",
+    "BatchMode=yes",
+    "-o",
+    "ConnectTimeout=10",
+    "-o",
+    `StrictHostKeyChecking=${config.strictHostKeyChecking ? "yes" : "no"}`
+  ];
+  if (config.strictHostKeyChecking) {
+    if (config.knownHosts) {
+      const knownHosts = await withTempFile("paperclip-ssh-known-hosts-", config.knownHosts, 384);
+      tempFiles.push(knownHosts.cleanup);
+      sshArgs.push("-o", `UserKnownHostsFile=${knownHosts.path}`);
+    }
+  } else {
+    sshArgs.push("-o", "UserKnownHostsFile=/dev/null");
+  }
+  if (config.privateKey) {
+    const privateKey = await withTempFile("paperclip-ssh-key-", config.privateKey, 384);
+    tempFiles.push(privateKey.cleanup);
+    sshArgs.push("-i", privateKey.path);
+  }
+  return {
+    args: sshArgs,
+    cleanup: async () => {
+      await Promise.all(tempFiles.map((cleanup) => cleanup()));
+    }
+  };
+}
+function tarExcludeArgs(exclude) {
+  const combined = ["._*", ...exclude ?? []];
+  return combined.flatMap((entry) => ["--exclude", entry]);
+}
+function tarSpawnEnv() {
+  return {
+    ...process.env,
+    // Prevent macOS bsdtar from emitting AppleDouble metadata files like ._README.md.
+    COPYFILE_DISABLE: "1"
+  };
+}
+function tarPatternToRegExp(pattern) {
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]");
+  return new RegExp(`^${escaped}$`);
+}
+async function estimateLocalDirSize(input) {
+  const regexes = ["._*", ...input.exclude ?? []].map(tarPatternToRegExp);
+  const isExcluded = (relPath, base) => regexes.some((regex) => regex.test(relPath) || regex.test(base));
+  let total = 0;
+  const walk = async (dir, relative) => {
+    const entries = await fs2.readdir(dir, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+      const entryRelative = relative ? `${relative}/${entry.name}` : entry.name;
+      if (isExcluded(entryRelative, entry.name)) continue;
+      const full = path2.join(dir, entry.name);
+      const stats = await (input.followSymlinks ? fs2.stat(full) : fs2.lstat(full)).catch(() => null);
+      if (!stats) continue;
+      if (stats.isDirectory()) {
+        await walk(full, entryRelative);
+      } else if (stats.isFile()) {
+        total += stats.size;
+      }
+    }
+  };
+  await walk(input.localDir, "");
+  return total;
+}
+async function probeRemoteDirSize(input) {
+  try {
+    const result = await runSshScript(
+      input.spec,
+      `du -sk ${shellQuote(input.remoteDir)} 2>/dev/null | cut -f1`,
+      { timeoutMs: 15e3, maxBuffer: 16 * 1024 }
+    );
+    const kilobytes = Number.parseInt(result.stdout.trim(), 10);
+    return Number.isFinite(kilobytes) && kilobytes > 0 ? kilobytes * 1024 : null;
+  } catch {
+    return null;
+  }
+}
+function createTransferProgress(input) {
+  const reporter = createRuntimeProgressReporter({
+    sink: input.onProgress,
+    phase: input.phase,
+    direction: input.direction,
+    label: input.label,
+    target: "ssh"
+  });
+  let total = null;
+  let cap = null;
+  const applyTotal = (value) => {
+    total = value != null && value > 0 ? value : null;
+    cap = total != null && input.estimated ? Math.floor(total * 0.99) : null;
+  };
+  const totalReady = input.totalBytes != null && typeof input.totalBytes.then === "function" ? input.totalBytes.then(applyTotal, () => applyTotal(null)) : (applyTotal(input.totalBytes), Promise.resolve());
+  let transferred = 0;
+  let chain = Promise.resolve();
+  const enqueue = (work) => {
+    chain = chain.then(work).catch(() => void 0);
+  };
+  const counter = new Transform({
+    transform(chunk, _encoding, callback) {
+      transferred += chunk.length;
+      const reported = cap != null ? Math.min(transferred, cap) : transferred;
+      const totalSnapshot = total;
+      enqueue(() => reporter.report(reported, totalSnapshot));
+      callback(null, chunk);
+    }
+  });
+  return {
+    counter,
+    transferred: () => transferred,
+    finish: async () => {
+      await chain.catch(() => void 0);
+      await totalReady.catch(() => void 0);
+      await reporter.complete(total != null ? total : transferred, total).catch(() => void 0);
+    },
+    fail: async () => {
+      await chain.catch(() => void 0);
+      await reporter.fail(transferred, total).catch(() => void 0);
+    }
+  };
+}
+async function runSshScript(config, script, options = {}) {
+  return await runSshCommand(
+    config,
+    script,
+    options
+  );
+}
+async function clearLocalDirectory(localDir, preserveEntries = []) {
+  await fs2.mkdir(localDir, { recursive: true });
+  const preserve = new Set(preserveEntries);
+  const entries = await fs2.readdir(localDir);
+  await Promise.all(
+    entries.filter((entry) => !preserve.has(entry)).map((entry) => fs2.rm(path2.join(localDir, entry), { recursive: true, force: true }))
+  );
+}
+async function copyDirectoryContents(sourceDir, targetDir) {
+  await fs2.mkdir(targetDir, { recursive: true });
+  const entries = await fs2.readdir(sourceDir);
+  await Promise.all(entries.map(async (entry) => {
+    await fs2.cp(path2.join(sourceDir, entry), path2.join(targetDir, entry), {
+      recursive: true,
+      force: true,
+      preserveTimestamps: true
+    });
+  }));
+}
+async function readLocalGitWorkspaceSnapshot(localDir) {
+  try {
+    const insideWorkTree = await runLocalGit(localDir, ["rev-parse", "--is-inside-work-tree"], {
+      timeout: 1e4,
+      maxBuffer: 16 * 1024
+    });
+    if (insideWorkTree.stdout.trim() !== "true") {
+      return null;
+    }
+    const [headCommitResult, branchResult, deletedResult] = await Promise.all([
+      runLocalGit(localDir, ["rev-parse", "HEAD"], {
+        timeout: 1e4,
+        maxBuffer: 16 * 1024
+      }),
+      runLocalGit(localDir, ["rev-parse", "--abbrev-ref", "HEAD"], {
+        timeout: 1e4,
+        maxBuffer: 16 * 1024
+      }),
+      runLocalGit(localDir, ["ls-files", "--deleted", "-z"], {
+        timeout: 1e4,
+        maxBuffer: 256 * 1024
+      })
+    ]);
+    const branchName = branchResult.stdout.trim();
+    return {
+      headCommit: headCommitResult.stdout.trim(),
+      branchName: branchName && branchName !== "HEAD" ? branchName : null,
+      deletedPaths: deletedResult.stdout.split("\0").map((entry) => entry.trim()).filter(Boolean)
+    };
+  } catch {
+    return null;
+  }
+}
+async function streamLocalFileToSsh(input) {
+  const auth = await createSshAuthArgs(input.spec);
+  const sshArgs = [
+    ...auth.args,
+    "-p",
+    String(input.spec.port),
+    `${input.spec.username}@${input.spec.host}`,
+    `sh -c ${shellQuote(input.remoteScript)}`
+  ];
+  await new Promise((resolve, reject) => {
+    const source = createReadStream2(input.localFile);
+    const ssh = spawn("ssh", sshArgs, {
+      stdio: ["pipe", "ignore", "pipe"]
+    });
+    let sshStderr = "";
+    let settled = false;
+    const fail = (error) => {
+      if (settled) return;
+      settled = true;
+      source.destroy();
+      ssh.kill("SIGTERM");
+      reject(error);
+    };
+    ssh.stderr?.on("data", (chunk) => {
+      sshStderr += String(chunk);
+    });
+    source.on("error", fail);
+    ssh.on("error", fail);
+    if (input.progress) {
+      input.progress.counter.on("error", fail);
+      source.pipe(input.progress.counter).pipe(ssh.stdin ?? null);
+    } else {
+      source.pipe(ssh.stdin ?? null);
+    }
+    ssh.on("close", (code) => {
+      if (settled) return;
+      settled = true;
+      if ((code ?? 0) !== 0) {
+        reject(new Error(sshStderr.trim() || `ssh exited with code ${code ?? -1}`));
+        return;
+      }
+      resolve();
+    });
+  }).finally(auth.cleanup);
+}
+async function streamSshToLocalFile(input) {
+  const auth = await createSshAuthArgs(input.spec);
+  const sshArgs = [
+    ...auth.args,
+    "-p",
+    String(input.spec.port),
+    `${input.spec.username}@${input.spec.host}`,
+    `sh -c ${shellQuote(input.remoteScript)}`
+  ];
+  await new Promise((resolve, reject) => {
+    const ssh = spawn("ssh", sshArgs, {
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    const sink = createWriteStream(input.localFile, { mode: 384 });
+    let sshStderr = "";
+    let settled = false;
+    const fail = (error) => {
+      if (settled) return;
+      settled = true;
+      ssh.kill("SIGTERM");
+      sink.destroy();
+      reject(error);
+    };
+    if (input.progress) {
+      input.progress.counter.on("error", fail);
+      ssh.stdout?.pipe(input.progress.counter).pipe(sink);
+    } else {
+      ssh.stdout?.pipe(sink);
+    }
+    ssh.stderr?.on("data", (chunk) => {
+      sshStderr += String(chunk);
+    });
+    ssh.on("error", fail);
+    sink.on("error", fail);
+    ssh.on("close", (code) => {
+      sink.end(() => {
+        if (settled) return;
+        settled = true;
+        if ((code ?? 0) !== 0) {
+          reject(new Error(sshStderr.trim() || `ssh exited with code ${code ?? -1}`));
+          return;
+        }
+        resolve();
+      });
+    });
+  }).finally(auth.cleanup);
+}
+async function importGitWorkspaceToSsh(input) {
+  const bundleDir = await fs2.mkdtemp(path2.join(os.tmpdir(), "paperclip-ssh-bundle-"));
+  const bundlePath = path2.join(bundleDir, "workspace.bundle");
+  const tempRef = `refs/paperclip/ssh-sync/import/${randomUUID()}`;
+  try {
+    await runLocalGit(input.localDir, ["update-ref", tempRef, input.snapshot.headCommit], {
+      timeout: 1e4,
+      maxBuffer: 16 * 1024
+    });
+    await runLocalGit(input.localDir, ["bundle", "create", bundlePath, tempRef], {
+      timeout: 6e4,
+      maxBuffer: 1024 * 1024
+    });
+    const remoteSetupScript = [
+      "set -e",
+      `mkdir -p ${shellQuote(path2.posix.join(input.remoteDir, ".paperclip-runtime"))}`,
+      `tmp_bundle=$(mktemp ${shellQuote(path2.posix.join(input.remoteDir, ".paperclip-runtime", "import-XXXXXX.bundle"))})`,
+      `trap 'rm -f "$tmp_bundle"' EXIT`,
+      'cat > "$tmp_bundle"',
+      `if [ ! -d ${shellQuote(path2.posix.join(input.remoteDir, ".git"))} ]; then git init ${shellQuote(input.remoteDir)} >/dev/null; fi`,
+      `git -C ${shellQuote(input.remoteDir)} fetch --force "$tmp_bundle" '${tempRef}:${tempRef}' >/dev/null`,
+      input.snapshot.branchName ? `git -C ${shellQuote(input.remoteDir)} checkout --force -B ${shellQuote(input.snapshot.branchName)} ${shellQuote(input.snapshot.headCommit)} >/dev/null` : `git -C ${shellQuote(input.remoteDir)} -c advice.detachedHead=false checkout --force --detach ${shellQuote(input.snapshot.headCommit)} >/dev/null`,
+      `git -C ${shellQuote(input.remoteDir)} reset --hard ${shellQuote(input.snapshot.headCommit)} >/dev/null`,
+      `git -C ${shellQuote(input.remoteDir)} clean -fdx -e .paperclip-runtime >/dev/null`,
+      // Drop the per-import ref on the remote side too so it can't accumulate.
+      `git -C ${shellQuote(input.remoteDir)} update-ref -d ${shellQuote(tempRef)} >/dev/null 2>&1 || true`
+    ].join("\n");
+    const progress = input.onProgress ? createTransferProgress({
+      onProgress: input.onProgress,
+      phase: "Importing git history",
+      direction: "to",
+      totalBytes: (await fs2.stat(bundlePath)).size,
+      estimated: false
+    }) : null;
+    try {
+      await streamLocalFileToSsh({
+        spec: input.spec,
+        localFile: bundlePath,
+        remoteScript: remoteSetupScript,
+        progress: progress ?? void 0
+      });
+      await progress?.finish();
+    } catch (error) {
+      await progress?.fail();
+      throw error;
+    }
+  } finally {
+    await runLocalGit(input.localDir, ["update-ref", "-d", tempRef], {
+      timeout: 1e4,
+      maxBuffer: 16 * 1024
+    }).catch(() => void 0);
+    await fs2.rm(bundleDir, { recursive: true, force: true }).catch(() => void 0);
+  }
+}
+async function exportGitWorkspaceFromSsh(input) {
+  const bundleDir = await fs2.mkdtemp(path2.join(os.tmpdir(), "paperclip-ssh-bundle-"));
+  const bundlePath = path2.join(bundleDir, "workspace.bundle");
+  const importedRef = input.importedRef ?? `refs/paperclip/ssh-sync/imported/${randomUUID()}`;
+  try {
+    const exportScript = [
+      "set -e",
+      `git -C ${shellQuote(input.remoteDir)} update-ref refs/paperclip/ssh-sync/export HEAD`,
+      `mkdir -p ${shellQuote(path2.posix.join(input.remoteDir, ".paperclip-runtime"))}`,
+      `tmp_bundle=$(mktemp ${shellQuote(path2.posix.join(input.remoteDir, ".paperclip-runtime", "export-XXXXXX.bundle"))})`,
+      'cleanup() { rm -f "$tmp_bundle"; git -C ' + shellQuote(input.remoteDir) + " update-ref -d refs/paperclip/ssh-sync/export >/dev/null 2>&1 || true; }",
+      "trap cleanup EXIT",
+      `git -C ${shellQuote(input.remoteDir)} bundle create "$tmp_bundle" refs/paperclip/ssh-sync/export >/dev/null`,
+      'cat "$tmp_bundle"'
+    ].join("\n");
+    const progress = input.onProgress ? createTransferProgress({
+      onProgress: input.onProgress,
+      phase: "Exporting git history",
+      direction: "from",
+      totalBytes: null,
+      estimated: false
+    }) : null;
+    try {
+      await streamSshToLocalFile({
+        spec: input.spec,
+        remoteScript: exportScript,
+        localFile: bundlePath,
+        progress: progress ?? void 0
+      });
+      await progress?.finish();
+    } catch (error) {
+      await progress?.fail();
+      throw error;
+    }
+    await runLocalGit(input.localDir, ["fetch", "--force", bundlePath, `refs/paperclip/ssh-sync/export:${importedRef}`], {
+      timeout: 6e4,
+      maxBuffer: 1024 * 1024
+    });
+    if (input.resetLocalWorkspace !== false) {
+      await runLocalGit(input.localDir, ["reset", "--hard", importedRef], {
+        timeout: 6e4,
+        maxBuffer: 1024 * 1024
+      });
+    }
+    const importedHead = await runLocalGit(input.localDir, ["rev-parse", importedRef], {
+      timeout: 1e4,
+      maxBuffer: 16 * 1024
+    });
+    return importedHead.stdout.trim();
+  } finally {
+    if (input.resetLocalWorkspace !== false) {
+      await runLocalGit(input.localDir, ["update-ref", "-d", importedRef], {
+        timeout: 1e4,
+        maxBuffer: 16 * 1024
+      }).catch(() => void 0);
+    }
+    await fs2.rm(bundleDir, { recursive: true, force: true }).catch(() => void 0);
+  }
+}
+async function integrateImportedGitHead(input) {
+  const isConcurrentRefUpdateError = (error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.includes("cannot lock ref") && message.includes("expected");
+  };
+  for (let attempt = 0; attempt < 5; attempt += 1) {
+    const snapshot = await readLocalGitWorkspaceSnapshot(input.localDir);
+    if (!snapshot) return;
+    const currentHead = snapshot.headCommit;
+    if (!currentHead || currentHead === input.importedHead) return;
+    const headRef = snapshot.branchName ? `refs/heads/${snapshot.branchName}` : "HEAD";
+    const mergeBase = await runLocalGit(input.localDir, ["merge-base", currentHead, input.importedHead], {
+      timeout: 1e4,
+      maxBuffer: 16 * 1024
+    }).catch(() => null);
+    const mergeBaseHead = mergeBase?.stdout.trim() ?? "";
+    if (mergeBaseHead === input.importedHead) {
+      return;
+    }
+    if (mergeBaseHead === currentHead) {
+      try {
+        await runLocalGit(input.localDir, ["update-ref", headRef, input.importedHead, currentHead], {
+          timeout: 1e4,
+          maxBuffer: 16 * 1024
+        });
+        return;
+      } catch (error) {
+        if (isConcurrentRefUpdateError(error) && attempt < 4) continue;
+        throw error;
+      }
+    }
+    let mergedTree;
+    try {
+      mergedTree = await runLocalGit(input.localDir, ["merge-tree", "--write-tree", currentHead, input.importedHead], {
+        timeout: 6e4,
+        maxBuffer: 256 * 1024
+      });
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      throw new Error(
+        `Failed to merge concurrent SSH git histories for ${currentHead.slice(0, 12)} and ${input.importedHead.slice(0, 12)}: ${reason}`
+      );
+    }
+    const mergedTreeId = mergedTree.stdout.trim().split("\n")[0]?.trim() ?? "";
+    if (!mergedTreeId) {
+      throw new Error("Failed to compute a merged git tree for SSH workspace restore.");
+    }
+    const mergeCommit = await runLocalGit(
+      input.localDir,
+      [
+        "commit-tree",
+        mergedTreeId,
+        "-p",
+        currentHead,
+        "-p",
+        input.importedHead,
+        "-m",
+        `Paperclip SSH sync merge ${input.importedHead.slice(0, 12)}`
+      ],
+      {
+        timeout: 6e4,
+        maxBuffer: 64 * 1024
+      }
+    );
+    try {
+      await runLocalGit(input.localDir, ["update-ref", headRef, mergeCommit.stdout.trim(), currentHead], {
+        timeout: 1e4,
+        maxBuffer: 16 * 1024
+      });
+      return;
+    } catch (error) {
+      if (isConcurrentRefUpdateError(error) && attempt < 4) continue;
+      throw error;
+    }
+  }
+  throw new Error(`Failed to integrate concurrent SSH git history for ${input.importedHead.slice(0, 12)} after multiple retries.`);
+}
+async function clearRemoteDirectory(input) {
+  const preservePatterns = (input.preserveEntries ?? []).map((entry) => `! -name ${shellQuote(entry)}`).join(" ");
+  const script = [
+    "set -e",
+    `mkdir -p ${shellQuote(input.remoteDir)}`,
+    `find ${shellQuote(input.remoteDir)} -mindepth 1 -maxdepth 1 ${preservePatterns} -exec rm -rf -- {} +`
+  ].join("\n");
+  await runSshScript(input.spec, script, {
+    timeoutMs: 3e4,
+    maxBuffer: 256 * 1024
+  });
+}
+async function removeDeletedPathsOnSsh(input) {
+  if (input.deletedPaths.length === 0) return;
+  const quotedPaths = input.deletedPaths.map((entry) => shellQuote(entry)).join(" ");
+  const script = `cd ${shellQuote(input.remoteDir)} && rm -rf -- ${quotedPaths}`;
+  await runSshScript(input.spec, script, {
+    timeoutMs: 3e4,
+    maxBuffer: 256 * 1024
+  });
+}
+async function runSshCommand(config, remoteCommand, options = {}) {
+  let cleanup = () => Promise.resolve();
+  try {
+    const auth = await createSshAuthArgs(config);
+    cleanup = auth.cleanup;
+    const sshArgs = [...auth.args];
+    const envEntries = Object.entries(options.env ?? {}).filter((entry) => typeof entry[1] === "string");
+    for (const [key] of envEntries) {
+      if (!isValidShellEnvKey(key)) {
+        throw new Error(`Invalid SSH environment variable key: ${key}`);
+      }
+    }
+    const envArgs = envEntries.map(([key, value]) => `${key}=${shellQuote(value)}`);
+    const remoteScript = [
+      'if [ -f "$HOME/.profile" ]; then . "$HOME/.profile" >/dev/null 2>&1 || true; fi',
+      'if [ -f "$HOME/.bash_profile" ]; then . "$HOME/.bash_profile" >/dev/null 2>&1 || true; fi',
+      'if [ -f "$HOME/.zprofile" ]; then . "$HOME/.zprofile" >/dev/null 2>&1 || true; fi',
+      envArgs.length > 0 ? `exec env ${envArgs.join(" ")} sh -c ${shellQuote(remoteCommand)}` : `exec sh -c ${shellQuote(remoteCommand)}`
+    ].join(" && ");
+    sshArgs.push(
+      "-p",
+      String(config.port),
+      `${config.username}@${config.host}`,
+      `sh -c ${shellQuote(remoteScript)}`
+    );
+    return options.stdin != null ? await spawnText("ssh", sshArgs, {
+      stdin: options.stdin,
+      timeout: options.timeoutMs ?? 15e3,
+      maxBuffer: options.maxBuffer ?? 1024 * 128
+    }) : await execFileText("ssh", sshArgs, {
+      timeout: options.timeoutMs ?? 15e3,
+      maxBuffer: options.maxBuffer ?? 1024 * 128
+    });
+  } finally {
+    await cleanup();
+  }
+}
+async function buildSshSpawnTarget(input) {
+  for (const key of Object.keys(input.env)) {
+    if (!isValidShellEnvKey(key)) {
+      throw new Error(`Invalid SSH environment variable key: ${key}`);
+    }
+  }
+  const auth = await createSshAuthArgs(input.spec);
+  const sshArgs = [...auth.args];
+  const envArgs = Object.entries(input.env).filter((entry) => typeof entry[1] === "string").map(([key, value]) => `${key}=${shellQuote(value)}`);
+  const remoteCommandParts = [shellQuote(input.command), ...input.args.map((arg) => shellQuote(arg))].join(" ");
+  const remoteScript = [
+    'if [ -f "$HOME/.profile" ]; then . "$HOME/.profile" >/dev/null 2>&1 || true; fi',
+    'if [ -f "$HOME/.bash_profile" ]; then . "$HOME/.bash_profile" >/dev/null 2>&1 || true; fi',
+    'if [ -f "$HOME/.zprofile" ]; then . "$HOME/.zprofile" >/dev/null 2>&1 || true; fi',
+    'export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"',
+    '[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh" >/dev/null 2>&1 || true',
+    `cd ${shellQuote(input.spec.remoteCwd)}`,
+    envArgs.length > 0 ? `exec env ${envArgs.join(" ")} ${remoteCommandParts}` : `exec ${remoteCommandParts}`
+  ].join(" && ");
+  sshArgs.push(
+    "-p",
+    String(input.spec.port),
+    `${input.spec.username}@${input.spec.host}`,
+    `sh -c ${shellQuote(remoteScript)}`
+  );
+  return {
+    command: "ssh",
+    args: sshArgs,
+    cleanup: auth.cleanup
+  };
+}
+async function syncDirectoryToSsh(input) {
+  const auth = await createSshAuthArgs(input.spec);
+  const sshArgs = [
+    ...auth.args,
+    "-p",
+    String(input.spec.port),
+    `${input.spec.username}@${input.spec.host}`,
+    `sh -c ${shellQuote(`mkdir -p ${shellQuote(input.remoteDir)} && tar -xf - -C ${shellQuote(input.remoteDir)}`)}`
+  ];
+  const progress = input.onProgress ? createTransferProgress({
+    onProgress: input.onProgress,
+    phase: "Syncing",
+    direction: "to",
+    label: input.progressLabel,
+    totalBytes: estimateLocalDirSize({
+      localDir: input.localDir,
+      exclude: input.exclude,
+      followSymlinks: input.followSymlinks
+    }),
+    estimated: true
+  }) : null;
+  try {
+    await new Promise((resolve, reject) => {
+      const tarArgs = [
+        ...input.followSymlinks ? ["-h"] : [],
+        "-C",
+        input.localDir,
+        ...tarExcludeArgs(input.exclude),
+        "-cf",
+        "-",
+        "."
+      ];
+      const tar = spawn("tar", tarArgs, {
+        stdio: ["ignore", "pipe", "pipe"],
+        env: tarSpawnEnv()
+      });
+      const ssh = spawn("ssh", sshArgs, {
+        stdio: ["pipe", "ignore", "pipe"]
+      });
+      let tarStderr = "";
+      let sshStderr = "";
+      let settled = false;
+      let tarExited = false;
+      let sshExited = false;
+      let tarExitCode = null;
+      let sshExitCode = null;
+      const maybeFinish = () => {
+        if (settled || !tarExited || !sshExited) {
+          return;
+        }
+        settled = true;
+        if ((tarExitCode ?? 0) !== 0) {
+          reject(new Error(tarStderr.trim() || `tar exited with code ${tarExitCode ?? -1}`));
+          return;
+        }
+        if ((sshExitCode ?? 0) !== 0) {
+          reject(new Error(sshStderr.trim() || `ssh exited with code ${sshExitCode ?? -1}`));
+          return;
+        }
+        resolve();
+      };
+      const fail = (error) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        tar.kill("SIGTERM");
+        ssh.kill("SIGTERM");
+        reject(error);
+      };
+      if (progress) {
+        progress.counter.on("error", fail);
+        tar.stdout?.pipe(progress.counter).pipe(ssh.stdin ?? null);
+      } else {
+        tar.stdout?.pipe(ssh.stdin ?? null);
+      }
+      tar.stderr?.on("data", (chunk) => {
+        tarStderr += String(chunk);
+      });
+      ssh.stderr?.on("data", (chunk) => {
+        sshStderr += String(chunk);
+      });
+      tar.on("error", fail);
+      ssh.on("error", fail);
+      tar.on("close", (code) => {
+        tarExited = true;
+        tarExitCode = code;
+        maybeFinish();
+      });
+      ssh.on("close", (code) => {
+        sshExited = true;
+        sshExitCode = code;
+        maybeFinish();
+      });
+    }).finally(auth.cleanup);
+    await progress?.finish();
+  } catch (error) {
+    await progress?.fail();
+    throw error;
+  }
+}
+async function syncDirectoryFromSsh(input) {
+  const auth = await createSshAuthArgs(input.spec);
+  const stagingDir = await fs2.mkdtemp(path2.join(os.tmpdir(), "paperclip-ssh-sync-back-"));
+  const remoteTarScript = [
+    `cd ${shellQuote(input.remoteDir)}`,
+    `tar ${[...tarExcludeArgs(input.exclude).map(shellQuote), "-cf", "-", "."].join(" ")}`
+  ].join(" && ");
+  const sshArgs = [
+    ...auth.args,
+    "-p",
+    String(input.spec.port),
+    `${input.spec.username}@${input.spec.host}`,
+    `sh -c ${shellQuote(remoteTarScript)}`
+  ];
+  const progress = input.onProgress ? createTransferProgress({
+    onProgress: input.onProgress,
+    phase: "Restoring",
+    direction: "from",
+    label: input.progressLabel,
+    totalBytes: probeRemoteDirSize({ spec: input.spec, remoteDir: input.remoteDir }),
+    estimated: true
+  }) : null;
+  try {
+    await new Promise((resolve, reject) => {
+      const ssh = spawn("ssh", sshArgs, {
+        stdio: ["ignore", "pipe", "pipe"]
+      });
+      const tar = spawn("tar", ["-xf", "-", "-C", stagingDir], {
+        stdio: ["pipe", "ignore", "pipe"],
+        env: tarSpawnEnv()
+      });
+      let sshStderr = "";
+      let tarStderr = "";
+      let settled = false;
+      let sshExited = false;
+      let tarExited = false;
+      let sshExitCode = null;
+      let tarExitCode = null;
+      const maybeFinish = () => {
+        if (settled || !sshExited || !tarExited) return;
+        settled = true;
+        if ((sshExitCode ?? 0) !== 0) {
+          reject(new Error(sshStderr.trim() || `ssh exited with code ${sshExitCode ?? -1}`));
+          return;
+        }
+        if ((tarExitCode ?? 0) !== 0) {
+          reject(new Error(tarStderr.trim() || `tar exited with code ${tarExitCode ?? -1}`));
+          return;
+        }
+        resolve();
+      };
+      const fail = (error) => {
+        if (settled) return;
+        settled = true;
+        ssh.kill("SIGTERM");
+        tar.kill("SIGTERM");
+        reject(error);
+      };
+      if (progress) {
+        progress.counter.on("error", fail);
+        ssh.stdout?.pipe(progress.counter).pipe(tar.stdin ?? null);
+      } else {
+        ssh.stdout?.pipe(tar.stdin ?? null);
+      }
+      ssh.stderr?.on("data", (chunk) => {
+        sshStderr += String(chunk);
+      });
+      tar.stderr?.on("data", (chunk) => {
+        tarStderr += String(chunk);
+      });
+      ssh.on("error", fail);
+      tar.on("error", fail);
+      ssh.on("close", (code) => {
+        sshExited = true;
+        sshExitCode = code;
+        maybeFinish();
+      });
+      tar.on("close", (code) => {
+        tarExited = true;
+        tarExitCode = code;
+        maybeFinish();
+      });
+    });
+    await progress?.finish();
+    await clearLocalDirectory(input.localDir, input.preserveLocalEntries);
+    await copyDirectoryContents(stagingDir, input.localDir);
+  } catch (error) {
+    await progress?.fail();
+    throw error;
+  } finally {
+    await fs2.rm(stagingDir, { recursive: true, force: true }).catch(() => void 0);
+    await auth.cleanup();
+  }
+}
+async function prepareWorkspaceForSshExecution(input) {
+  const remoteDir = input.remoteDir ?? input.spec.remoteCwd;
+  const gitSnapshot = await readLocalGitWorkspaceSnapshot(input.localDir);
+  if (gitSnapshot) {
+    await importGitWorkspaceToSsh({
+      spec: input.spec,
+      localDir: input.localDir,
+      remoteDir,
+      snapshot: gitSnapshot,
+      onProgress: input.onProgress
+    });
+    await syncDirectoryToSsh({
+      spec: input.spec,
+      localDir: input.localDir,
+      remoteDir,
+      exclude: [".git", ".paperclip-runtime"],
+      onProgress: input.onProgress,
+      progressLabel: "workspace"
+    });
+    await removeDeletedPathsOnSsh({
+      spec: input.spec,
+      remoteDir,
+      deletedPaths: gitSnapshot.deletedPaths
+    });
+    return { gitBacked: true };
+  }
+  await clearRemoteDirectory({
+    spec: input.spec,
+    remoteDir,
+    preserveEntries: [".paperclip-runtime"]
+  });
+  await syncDirectoryToSsh({
+    spec: input.spec,
+    localDir: input.localDir,
+    remoteDir,
+    exclude: [".paperclip-runtime"],
+    onProgress: input.onProgress,
+    progressLabel: "workspace"
+  });
+  return { gitBacked: false };
+}
+async function restoreWorkspaceFromSshExecution(input) {
+  const remoteDir = input.remoteDir ?? input.spec.remoteCwd;
+  if (input.baselineSnapshot) {
+    const stagingDir = await fs2.mkdtemp(path2.join(os.tmpdir(), "paperclip-ssh-sync-back-"));
+    const importedRef = input.restoreGitHistory ? `refs/paperclip/ssh-sync/imported/${randomUUID()}` : null;
+    try {
+      const importedHead = input.restoreGitHistory ? await exportGitWorkspaceFromSsh({
+        spec: input.spec,
+        remoteDir,
+        localDir: input.localDir,
+        importedRef: importedRef ?? void 0,
+        resetLocalWorkspace: false,
+        onProgress: input.onProgress
+      }) : null;
+      await syncDirectoryFromSsh({
+        spec: input.spec,
+        remoteDir,
+        localDir: stagingDir,
+        exclude: input.baselineSnapshot.exclude,
+        onProgress: input.onProgress,
+        progressLabel: "workspace"
+      });
+      await mergeDirectoryWithBaseline({
+        baseline: input.baselineSnapshot,
+        sourceDir: stagingDir,
+        targetDir: input.localDir,
+        // Git history advances via integrateImportedGitHead; the working tree
+        // still comes from the remote file snapshot so dirty remote edits win.
+        beforeApply: importedHead ? async () => {
+          await integrateImportedGitHead({
+            localDir: input.localDir,
+            importedHead
+          });
+        } : void 0
+      });
+    } finally {
+      if (importedRef) {
+        await runLocalGit(input.localDir, ["update-ref", "-d", importedRef], {
+          timeout: 1e4,
+          maxBuffer: 16 * 1024
+        }).catch(() => void 0);
+      }
+      await fs2.rm(stagingDir, { recursive: true, force: true }).catch(() => void 0);
+    }
+    return;
+  }
+  const gitSnapshot = await readLocalGitWorkspaceSnapshot(input.localDir);
+  if (gitSnapshot) {
+    await exportGitWorkspaceFromSsh({
+      spec: input.spec,
+      remoteDir,
+      localDir: input.localDir,
+      onProgress: input.onProgress
+    });
+    await syncDirectoryFromSsh({
+      spec: input.spec,
+      remoteDir,
+      localDir: input.localDir,
+      exclude: [".git", ".paperclip-runtime"],
+      preserveLocalEntries: [".git"],
+      onProgress: input.onProgress,
+      progressLabel: "workspace"
+    });
+    return;
+  }
+  await syncDirectoryFromSsh({
+    spec: input.spec,
+    remoteDir,
+    localDir: input.localDir,
+    exclude: [".paperclip-runtime"],
+    onProgress: input.onProgress,
+    progressLabel: "workspace"
+  });
+}
+
+// ../../adapter-utils/src/command-redaction.ts
+var REDACTED_COMMAND_TEXT_VALUE = "***REDACTED***";
+var SECRET_NAME_PATTERN = String.raw`[A-Za-z0-9_-]*(?:api[-_]?key|(?:access[-_]?|auth[-_]?)?token|token|authorization|bearer|secret|passwd|password|credential|jwt|private[-_]?key|cookie|connectionstring)[A-Za-z0-9_-]*`;
+var COMMAND_CLI_SECRET_OPTION_RE = new RegExp(
+  String.raw`(\B-{1,2}${SECRET_NAME_PATTERN}(?:\s+|=)(["']?))[^\s"'` + "`" + String.raw`]+(\2)`,
+  "gi"
+);
+var COMMAND_ENV_SECRET_ASSIGNMENT_RE = new RegExp(
+  String.raw`(\b${SECRET_NAME_PATTERN}\s*=\s*)(?:(["'])([^"'` + "`" + String.raw`\r\n]*)\2|([^\s"'` + "`" + String.raw`]+))`,
+  "gi"
+);
+var COMMAND_AUTHORIZATION_BEARER_RE = /(\bAuthorization\s*:\s*Bearer\s+)[^\s"'`]+/gi;
+var COMMAND_OPENAI_KEY_RE = /\bsk-[A-Za-z0-9_-]{12,}\b/g;
+var COMMAND_GITHUB_TOKEN_RE = /\bgh[pousr]_[A-Za-z0-9_]{20,}\b/g;
+var COMMAND_JWT_RE = /\b[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}(?:\.[A-Za-z0-9_-]{8,})?\b/g;
+var COMMAND_SECRET_HINTS = [
+  "api",
+  "key",
+  "token",
+  "auth",
+  "bearer",
+  "secret",
+  "pass",
+  "credential",
+  "jwt",
+  "private",
+  "cookie",
+  "connectionstring",
+  "sk-",
+  "ghp_",
+  "gho_",
+  "ghu_",
+  "ghs_",
+  "ghr_"
+];
+function maybeContainsSecretText(command) {
+  const lower = command.toLowerCase();
+  return COMMAND_SECRET_HINTS.some((hint) => lower.includes(hint)) || command.includes(".");
+}
+function redactCommandText(command, redactedValue = REDACTED_COMMAND_TEXT_VALUE) {
+  if (!maybeContainsSecretText(command)) return command;
+  return command.replace(COMMAND_AUTHORIZATION_BEARER_RE, `$1${redactedValue}`).replace(COMMAND_CLI_SECRET_OPTION_RE, `$1${redactedValue}$3`).replace(
+    COMMAND_ENV_SECRET_ASSIGNMENT_RE,
+    (_match, prefix, quote) => quote ? `${prefix}${quote}${redactedValue}${quote}` : `${prefix}${redactedValue}`
+  ).replace(COMMAND_OPENAI_KEY_RE, redactedValue).replace(COMMAND_GITHUB_TOKEN_RE, redactedValue).replace(COMMAND_JWT_RE, redactedValue);
+}
+
+// ../../adapter-utils/src/server-utils.ts
+function resolveProcessGroupId(child) {
+  if (process.platform === "win32") return null;
+  return typeof child.pid === "number" && child.pid > 0 ? child.pid : null;
+}
+function signalRunningProcess(running, signal) {
+  if (process.platform !== "win32" && running.processGroupId && running.processGroupId > 0) {
+    try {
+      process.kill(-running.processGroupId, signal);
+      return;
+    } catch {
+    }
+  }
+  if (!running.child.killed) {
+    running.child.kill(signal);
+  }
+}
+var runningProcesses = /* @__PURE__ */ new Map();
+var MAX_CAPTURE_BYTES = 4 * 1024 * 1024;
+var MAX_EXCERPT_BYTES = 32 * 1024;
+var TERMINAL_RESULT_SCAN_OVERLAP_CHARS = 64 * 1024;
+var DEFAULT_PAPERCLIP_INSTANCE_ID = "default";
+var PATH_SEGMENT_RE = /^[a-zA-Z0-9_-]+$/;
+var SENSITIVE_ENV_KEY = /(key|token|secret|password|passwd|authorization|cookie)/i;
+var REDACTED_LOG_VALUE = "***REDACTED***";
+var PAPERCLIP_SKILL_ROOT_RELATIVE_CANDIDATES = [
+  "../../skills",
+  "../../../../../skills"
+];
+var MATERIALIZED_SKILL_SENTINEL = ".paperclip-materialized-skill.json";
+var MATERIALIZED_SKILL_LOCK_OWNER = "owner.json";
+var MATERIALIZED_SKILL_LOCK_STALE_MS = 3e4;
+function expandHomePrefix(value) {
+  if (value === "~") return os2.homedir();
+  if (value.startsWith("~/")) return path3.resolve(os2.homedir(), value.slice(2));
+  return value;
+}
+function resolvePaperclipInstanceRootForAdapter(input = {}) {
+  const env = input.env ?? process.env;
+  const homeRaw = input.homeDir?.trim() || env.PAPERCLIP_HOME?.trim();
+  const homeDir = path3.resolve(homeRaw ? expandHomePrefix(homeRaw) : path3.resolve(os2.homedir(), ".paperclip"));
+  const instanceId = input.instanceId?.trim() || env.PAPERCLIP_INSTANCE_ID?.trim() || DEFAULT_PAPERCLIP_INSTANCE_ID;
+  if (!PATH_SEGMENT_RE.test(instanceId)) throw new Error(`Invalid PAPERCLIP_INSTANCE_ID '${instanceId}'.`);
+  return path3.resolve(homeDir, "instances", instanceId);
+}
+var DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE = [
+  "You are agent {{agent.id}} ({{agent.name}}). Continue your Paperclip work.",
+  "",
+  "Execution contract:",
+  "- Start actionable work in this heartbeat; do not stop at a plan unless the issue asks for planning.",
+  "- Leave durable progress in comments, documents, or work products, then update the issue to a clear final disposition before ending the heartbeat.",
+  "- Comments, documents, screenshots, work products, and `Remaining` bullets are evidence, not valid liveness paths by themselves.",
+  "- Final disposition checklist: mark `done` when complete; use `in_review` only with a real reviewer, approval, interaction, or monitor path; use `blocked` only with first-class blockers or a named unblock owner/action; create delegated follow-up issues with blockers when another agent owns the next step; keep `in_progress` only when a live continuation path exists.",
+  "- Prefer the smallest verification that proves the change; do not default to full workspace typecheck/build/test on every heartbeat unless the task scope warrants it.",
+  "- Use child issues for parallel or long delegated work instead of polling agents, sessions, or processes.",
+  "- If woken by a human comment on a dependency-blocked issue, respond or triage the comment without treating the blocked deliverable work as unblocked.",
+  "- Create child issues directly when you know what needs to be done; use issue-thread interactions when the board/user must choose suggested tasks, answer structured questions, or confirm a proposal.",
+  "- To ask for that input, create an interaction on the current issue with POST /api/issues/{issueId}/interactions using kind suggest_tasks, ask_user_questions, or request_confirmation. Use continuationPolicy wake_assignee when you need to resume after a response; for request_confirmation this resumes only after acceptance.",
+  "- When you intentionally restart follow-up work on a completed assigned issue, include structured `resume: true` with the POST /api/issues/{issueId}/comments or PATCH /api/issues/{issueId} comment payload. Generic agent comments on closed issues are inert by default.",
+  "- For plan approval, update the plan document first, then create request_confirmation targeting the latest plan revision with idempotencyKey confirmation:{issueId}:plan:{revisionId}. Wait for acceptance before creating implementation subtasks, and create a fresh confirmation after superseding board/user comments if approval is still needed.",
+  "- If blocked, mark the issue blocked and name the unblock owner and action.",
+  "- Respect budget, pause/cancel, approval gates, and company boundaries."
+].join("\n");
+var WATCHDOG_DEFAULT_MANDATE = [
+  "You are running as a task watchdog, not as the original deliverable worker.",
+  "Your mission is to keep the watched issue tree moving by verifying stopped work, not by trusting agent claims.",
+  "",
+  "Mandate:",
+  "- Treat every terminal, cancelled, blocked, in-review, or otherwise stopped leaf in the watched subtree as a claim that must be verified against comments, documents, work products, screenshots, tests, blockers, and review state.",
+  '- Do not accept "I could not" or "waiting for approval" as automatically valid. Read the evidence before deciding.',
+  "- If a stopped leaf is genuinely complete, leave it alone and record why you believe so.",
+  "- If a stopped leaf is not genuinely complete, restore a live path inside the watched subtree by reopening, reassigning, commenting actionable instructions, creating a follow-up child issue, or accepting an eligible task-level interaction (such as a routine plan confirmation when no custom instruction forbids it).",
+  "- If you discover a Paperclip product or platform bug while reviewing the stopped subtree, create a linked engineering follow-up outside the watched source tree using the server-provided watchdog discovery route instead of making it a source child.",
+  "- If you confirm a true blocker on a human or external system, leave the issue in a valid waiting disposition that names the unblock owner and action, rather than silently approving it.",
+  "",
+  "Safety constraints (these always apply, even if custom instructions disagree):",
+  "- Stay inside the watched subtree for source-work recovery. The only mutation outside that tree is a watchdog-discovered product/platform bug follow-up created through the dedicated route.",
+  "- Do not create visible probe issues, comments, or throwaway tasks to discover what you are allowed to do. Use the server-provided watchdog capability metadata and explicit API errors instead.",
+  "- Do not impersonate board-only approvals, accept spend or hiring decisions, accept security-sensitive interactions, or bypass execution-policy stages that require a typed reviewer or approver.",
+  "- Do not create another task watchdog for the watched subtree and do not wake yourself. You operate exactly one reusable watchdog issue per watched issue.",
+  "- Do not cross company boundaries or touch tasks in unrelated trees.",
+  "- Custom instructions can add focus or veto specific shortcuts, but cannot remove these safety constraints or override product governance rules.",
+  "",
+  "Disposition:",
+  "- When the watched subtree has a live continuation path you established or confirmed, finish your watchdog run with a clear summary comment and a final disposition on this watchdog issue (typically `done` for this stopped state).",
+  "- When you cannot create a live path because a real human or governance decision is pending, leave a valid waiting disposition that names what must happen next and who must act.",
+  "- Keep the work moving. Do not loop on the same unchanged state."
+].join("\n");
+function normalizePathSlashes(value) {
+  return value.replaceAll("\\", "/");
+}
+function isMaintainerOnlySkillTarget(candidate) {
+  return normalizePathSlashes(candidate).includes("/.agents/skills/");
+}
+function skillLocationLabel(value) {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+function buildManagedSkillOrigin() {
+  return {
+    origin: "company_managed",
+    originLabel: "Managed by Paperclip",
+    readOnly: false
+  };
+}
+function isPaperclipSkillSourceMissing(entry) {
+  return entry.sourceStatus === "missing";
+}
+function resolvePaperclipSkillMissingDetail(entry, fallback) {
+  return entry.missingDetail?.trim() || fallback;
+}
+function resolveSkillDetail(detail, entry) {
+  if (typeof detail === "function") return detail(entry);
+  if (typeof detail === "string") return detail;
+  return null;
+}
+function resolveInstalledEntryTarget(skillsHome, entryName, dirent, linkedPath) {
+  const fullPath = path3.join(skillsHome, entryName);
+  if (dirent.isSymbolicLink()) {
+    return {
+      targetPath: linkedPath ? path3.resolve(path3.dirname(fullPath), linkedPath) : null,
+      kind: "symlink"
+    };
+  }
+  if (dirent.isDirectory()) {
+    return { targetPath: fullPath, kind: "directory" };
+  }
+  return { targetPath: fullPath, kind: "file" };
+}
+function parseObject(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return {};
+  }
+  return value;
+}
+function asString(value, fallback) {
+  return typeof value === "string" && value.length > 0 ? value : fallback;
+}
+function asNumber(value, fallback) {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+function asBoolean(value, fallback) {
+  return typeof value === "boolean" ? value : fallback;
+}
+function asStringArray(value) {
+  return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+function parseJson(value) {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return null;
+  }
+}
+function appendWithCap(prev, chunk, cap = MAX_CAPTURE_BYTES) {
+  const combined = prev + chunk;
+  return combined.length > cap ? combined.slice(combined.length - cap) : combined;
+}
+function appendWithByteCap(prev, chunk, cap = MAX_CAPTURE_BYTES) {
+  const combined = prev + chunk;
+  const bytes = Buffer.byteLength(combined, "utf8");
+  if (bytes <= cap) return combined;
+  const buffer = Buffer.from(combined, "utf8");
+  let start = Math.max(0, bytes - cap);
+  while (start < buffer.length && (buffer[start] & 192) === 128) start += 1;
+  return buffer.subarray(start).toString("utf8");
+}
+function resumeReadable(readable) {
+  if (!readable || readable.destroyed) return;
+  readable.resume();
+}
+function resolvePathValue(obj, dottedPath) {
+  const parts = dottedPath.split(".");
+  let cursor = obj;
+  for (const part of parts) {
+    if (typeof cursor !== "object" || cursor === null || Array.isArray(cursor)) {
+      return "";
+    }
+    cursor = cursor[part];
+  }
+  if (cursor === null || cursor === void 0) return "";
+  if (typeof cursor === "string") return cursor;
+  if (typeof cursor === "number" || typeof cursor === "boolean") return String(cursor);
+  try {
+    return JSON.stringify(cursor);
+  } catch {
+    return "";
+  }
+}
+function renderTemplate(template, data) {
+  return template.replace(/{{\s*([a-zA-Z0-9_.-]+)\s*}}/g, (_, path4) => resolvePathValue(data, path4));
+}
+function joinPromptSections(sections, separator = "\n\n") {
+  return sections.map((value) => typeof value === "string" ? value.trim() : "").filter(Boolean).join(separator);
+}
+function normalizePaperclipWakeIssue(value) {
+  const issue = parseObject(value);
+  const id = asString(issue.id, "").trim() || null;
+  const identifier = asString(issue.identifier, "").trim() || null;
+  const title = asString(issue.title, "").trim() || null;
+  const status = asString(issue.status, "").trim() || null;
+  const workMode = asString(issue.workMode, "").trim() || null;
+  const priority = asString(issue.priority, "").trim() || null;
+  if (!id && !identifier && !title) return null;
+  return {
+    id,
+    identifier,
+    title,
+    status,
+    workMode,
+    priority
+  };
+}
+function normalizePaperclipWakeComment(value) {
+  const comment = parseObject(value);
+  const author = parseObject(comment.author);
+  const body = asString(comment.body, "");
+  if (!body.trim()) return null;
+  return {
+    id: asString(comment.id, "").trim() || null,
+    issueId: asString(comment.issueId, "").trim() || null,
+    body,
+    bodyTruncated: asBoolean(comment.bodyTruncated, false),
+    createdAt: asString(comment.createdAt, "").trim() || null,
+    authorType: asString(author.type, "").trim() || null,
+    authorId: asString(author.id, "").trim() || null
+  };
+}
+function normalizePaperclipWakeContinuationSummary(value) {
+  const summary = parseObject(value);
+  const body = asString(summary.body, "").trim();
+  if (!body) return null;
+  return {
+    key: asString(summary.key, "").trim() || null,
+    title: asString(summary.title, "").trim() || null,
+    body,
+    bodyTruncated: asBoolean(summary.bodyTruncated, false),
+    updatedAt: asString(summary.updatedAt, "").trim() || null
+  };
+}
+function normalizePaperclipWakeLivenessContinuation(value) {
+  const continuation = parseObject(value);
+  const attempt = asNumber(continuation.attempt, 0);
+  const maxAttempts = asNumber(continuation.maxAttempts, 0);
+  const sourceRunId = asString(continuation.sourceRunId, "").trim() || null;
+  const state = asString(continuation.state, "").trim() || null;
+  const reason = asString(continuation.reason, "").trim() || null;
+  const instruction = asString(continuation.instruction, "").trim() || null;
+  if (!attempt && !maxAttempts && !sourceRunId && !state && !reason && !instruction) return null;
+  return {
+    attempt: attempt > 0 ? attempt : null,
+    maxAttempts: maxAttempts > 0 ? maxAttempts : null,
+    sourceRunId,
+    state,
+    reason,
+    instruction
+  };
+}
+function normalizePaperclipWakeChildIssueSummary(value) {
+  const child = parseObject(value);
+  const id = asString(child.id, "").trim() || null;
+  const identifier = asString(child.identifier, "").trim() || null;
+  const title = asString(child.title, "").trim() || null;
+  const status = asString(child.status, "").trim() || null;
+  const priority = asString(child.priority, "").trim() || null;
+  const summary = asString(child.summary, "").trim() || null;
+  if (!id && !identifier && !title && !status && !summary) return null;
+  return { id, identifier, title, status, priority, summary };
+}
+function normalizePaperclipWakeBlockerSummary(value) {
+  const blocker = parseObject(value);
+  const id = asString(blocker.id, "").trim() || null;
+  const identifier = asString(blocker.identifier, "").trim() || null;
+  const title = asString(blocker.title, "").trim() || null;
+  const status = asString(blocker.status, "").trim() || null;
+  const priority = asString(blocker.priority, "").trim() || null;
+  if (!id && !identifier && !title && !status) return null;
+  return { id, identifier, title, status, priority };
+}
+function normalizePaperclipWakeTreeHoldSummary(value) {
+  const hold = parseObject(value);
+  const holdId = asString(hold.holdId, "").trim() || null;
+  const rootIssueId = asString(hold.rootIssueId, "").trim() || null;
+  const mode = asString(hold.mode, "").trim() || null;
+  const reason = asString(hold.reason, "").trim() || null;
+  if (!holdId && !rootIssueId && !mode && !reason) return null;
+  return { holdId, rootIssueId, mode, reason };
+}
+function normalizePaperclipWakeExecutionPrincipal(value) {
+  const principal = parseObject(value);
+  const typeRaw = asString(principal.type, "").trim().toLowerCase();
+  if (typeRaw !== "agent" && typeRaw !== "user") return null;
+  return {
+    type: typeRaw,
+    agentId: asString(principal.agentId, "").trim() || null,
+    userId: asString(principal.userId, "").trim() || null
+  };
+}
+var MAX_WATCHDOG_INSTRUCTIONS_CHARS = 4e3;
+var MAX_WATCHDOG_LEAF_SUMMARIES = 25;
+var MAX_WATCHDOG_CAPABILITY_ITEMS = 50;
+function normalizePaperclipWakeTaskWatchdogLeaf(value) {
+  const leaf = parseObject(value);
+  const id = asString(leaf.id, "").trim() || null;
+  const identifier = asString(leaf.identifier, "").trim() || null;
+  const title = asString(leaf.title, "").trim() || null;
+  const status = asString(leaf.status, "").trim() || null;
+  const priority = asString(leaf.priority, "").trim() || null;
+  const role = asString(leaf.role, "").trim() || null;
+  const summary = asString(leaf.summary, "").trim() || null;
+  if (!id && !identifier && !title && !status && !summary) return null;
+  return { id, identifier, title, status, priority, role, summary };
+}
+function normalizeStringList(value, maxItems) {
+  if (!Array.isArray(value)) return [];
+  return value.filter((entry) => typeof entry === "string" && entry.trim().length > 0).map((entry) => entry.trim()).slice(0, maxItems);
+}
+function normalizePaperclipWakeTaskWatchdogCapabilities(value) {
+  const capabilities = parseObject(value);
+  const operations = normalizeStringList(capabilities.operations, MAX_WATCHDOG_CAPABILITY_ITEMS);
+  const deniedOperations = normalizeStringList(capabilities.deniedOperations, MAX_WATCHDOG_CAPABILITY_ITEMS);
+  const targetScopeRaw = parseObject(capabilities.targetScope);
+  const targetScope = {
+    watchedIssueId: asString(targetScopeRaw.watchedIssueId, "").trim() || null,
+    watchedIssueIdentifier: asString(targetScopeRaw.watchedIssueIdentifier, "").trim() || null,
+    watchdogIssueId: asString(targetScopeRaw.watchdogIssueId, "").trim() || null,
+    includeNonWatchdogDescendants: asBoolean(targetScopeRaw.includeNonWatchdogDescendants, false),
+    excludedOriginKinds: normalizeStringList(targetScopeRaw.excludedOriginKinds, MAX_WATCHDOG_CAPABILITY_ITEMS)
+  };
+  const hasTargetScope = Boolean(
+    targetScope.watchedIssueId || targetScope.watchedIssueIdentifier || targetScope.watchdogIssueId || targetScope.includeNonWatchdogDescendants || targetScope.excludedOriginKinds.length > 0
+  );
+  if (operations.length === 0 && deniedOperations.length === 0 && !hasTargetScope) return null;
+  return {
+    operations,
+    deniedOperations,
+    targetScope: hasTargetScope ? targetScope : null
+  };
+}
+function normalizePaperclipWakeTaskWatchdog(value) {
+  const watchdog = parseObject(value);
+  const watchedIssueId = asString(watchdog.watchedIssueId, "").trim() || null;
+  const watchedIssueIdentifier = asString(watchdog.watchedIssueIdentifier, "").trim() || null;
+  const watchedIssueTitle = asString(watchdog.watchedIssueTitle, "").trim() || null;
+  const stopFingerprint = asString(watchdog.stopFingerprint, "").trim() || null;
+  const customInstructionsRaw = asString(watchdog.customInstructions, "");
+  const customInstructionsTrimmed = customInstructionsRaw.trim();
+  const customInstructions = customInstructionsTrimmed ? customInstructionsTrimmed.length > MAX_WATCHDOG_INSTRUCTIONS_CHARS ? customInstructionsTrimmed.slice(0, MAX_WATCHDOG_INSTRUCTIONS_CHARS) : customInstructionsTrimmed : null;
+  const terminalLeafSummaries = Array.isArray(watchdog.terminalLeafSummaries) ? watchdog.terminalLeafSummaries.slice(0, MAX_WATCHDOG_LEAF_SUMMARIES).map((entry) => normalizePaperclipWakeTaskWatchdogLeaf(entry)).filter((entry) => Boolean(entry)) : [];
+  const capabilities = normalizePaperclipWakeTaskWatchdogCapabilities(watchdog.capabilities);
+  if (!watchedIssueId && !watchedIssueIdentifier && !watchedIssueTitle && !stopFingerprint && !customInstructions && terminalLeafSummaries.length === 0 && !capabilities) {
+    return null;
+  }
+  return {
+    watchedIssueId,
+    watchedIssueIdentifier,
+    watchedIssueTitle,
+    stopFingerprint,
+    terminalLeafSummaries,
+    customInstructions,
+    capabilities
+  };
+}
+function normalizePaperclipWakeExecutionStage(value) {
+  const stage = parseObject(value);
+  const wakeRoleRaw = asString(stage.wakeRole, "").trim().toLowerCase();
+  const wakeRole = wakeRoleRaw === "reviewer" || wakeRoleRaw === "approver" || wakeRoleRaw === "executor" ? wakeRoleRaw : null;
+  const allowedActions = Array.isArray(stage.allowedActions) ? stage.allowedActions.filter((entry) => typeof entry === "string" && entry.trim().length > 0).map((entry) => entry.trim()) : [];
+  const currentParticipant = normalizePaperclipWakeExecutionPrincipal(stage.currentParticipant);
+  const returnAssignee = normalizePaperclipWakeExecutionPrincipal(stage.returnAssignee);
+  const reviewRequestRaw = parseObject(stage.reviewRequest);
+  const reviewInstructions = asString(reviewRequestRaw.instructions, "").trim();
+  const reviewRequest = reviewInstructions ? { instructions: reviewInstructions } : null;
+  const stageId = asString(stage.stageId, "").trim() || null;
+  const stageType = asString(stage.stageType, "").trim() || null;
+  const lastDecisionOutcome = asString(stage.lastDecisionOutcome, "").trim() || null;
+  if (!wakeRole && !stageId && !stageType && !currentParticipant && !returnAssignee && !reviewRequest && !lastDecisionOutcome && allowedActions.length === 0) {
+    return null;
+  }
+  return {
+    wakeRole,
+    stageId,
+    stageType,
+    currentParticipant,
+    returnAssignee,
+    reviewRequest,
+    lastDecisionOutcome,
+    allowedActions
+  };
+}
+function normalizePaperclipWakePayload(value) {
+  const payload = parseObject(value);
+  const comments = Array.isArray(payload.comments) ? payload.comments.map((entry) => normalizePaperclipWakeComment(entry)).filter((entry) => Boolean(entry)) : [];
+  const commentWindow = parseObject(payload.commentWindow);
+  const commentIds = Array.isArray(payload.commentIds) ? payload.commentIds.filter((entry) => typeof entry === "string" && entry.trim().length > 0).map((entry) => entry.trim()) : [];
+  const executionStage = normalizePaperclipWakeExecutionStage(payload.executionStage);
+  const continuationSummary = normalizePaperclipWakeContinuationSummary(payload.continuationSummary);
+  const livenessContinuation = normalizePaperclipWakeLivenessContinuation(payload.livenessContinuation);
+  const taskWatchdog = normalizePaperclipWakeTaskWatchdog(payload.taskWatchdog);
+  const childIssueSummaries = Array.isArray(payload.childIssueSummaries) ? payload.childIssueSummaries.map((entry) => normalizePaperclipWakeChildIssueSummary(entry)).filter((entry) => Boolean(entry)) : [];
+  const unresolvedBlockerIssueIds = Array.isArray(payload.unresolvedBlockerIssueIds) ? payload.unresolvedBlockerIssueIds.map((entry) => asString(entry, "").trim()).filter(Boolean) : [];
+  const unresolvedBlockerSummaries = Array.isArray(payload.unresolvedBlockerSummaries) ? payload.unresolvedBlockerSummaries.map((entry) => normalizePaperclipWakeBlockerSummary(entry)).filter((entry) => Boolean(entry)) : [];
+  const activeTreeHold = normalizePaperclipWakeTreeHoldSummary(payload.activeTreeHold);
+  if (comments.length === 0 && commentIds.length === 0 && childIssueSummaries.length === 0 && unresolvedBlockerIssueIds.length === 0 && unresolvedBlockerSummaries.length === 0 && !activeTreeHold && !executionStage && !continuationSummary && !livenessContinuation && !taskWatchdog && !normalizePaperclipWakeIssue(payload.issue)) {
+    return null;
+  }
+  return {
+    reason: asString(payload.reason, "").trim() || null,
+    issue: normalizePaperclipWakeIssue(payload.issue),
+    checkedOutByHarness: asBoolean(payload.checkedOutByHarness, false),
+    dependencyBlockedInteraction: asBoolean(payload.dependencyBlockedInteraction, false),
+    treeHoldInteraction: asBoolean(payload.treeHoldInteraction, false),
+    activeTreeHold,
+    unresolvedBlockerIssueIds,
+    unresolvedBlockerSummaries,
+    executionStage,
+    continuationSummary,
+    livenessContinuation,
+    taskWatchdog,
+    interactionKind: asString(payload.interactionKind, "").trim() || null,
+    interactionStatus: asString(payload.interactionStatus, "").trim() || null,
+    childIssueSummaries,
+    childIssueSummaryTruncated: asBoolean(payload.childIssueSummaryTruncated, false),
+    commentIds,
+    latestCommentId: asString(payload.latestCommentId, "").trim() || null,
+    comments,
+    requestedCount: asNumber(commentWindow.requestedCount, comments.length || commentIds.length),
+    includedCount: asNumber(commentWindow.includedCount, comments.length),
+    missingCount: asNumber(commentWindow.missingCount, 0),
+    truncated: asBoolean(payload.truncated, false),
+    fallbackFetchNeeded: asBoolean(payload.fallbackFetchNeeded, false)
+  };
+}
+function stringifyPaperclipWakePayload(value) {
+  const normalized = normalizePaperclipWakePayload(value);
+  if (!normalized) return null;
+  return JSON.stringify(normalized);
+}
+function readPaperclipIssueWorkModeFromContext(value) {
+  const context = parseObject(value);
+  const issue = parseObject(context.paperclipIssue);
+  const direct = asString(issue.workMode, "").trim();
+  if (direct) return direct;
+  const wake = normalizePaperclipWakePayload(context.paperclipWake);
+  return wake?.issue?.workMode ?? null;
+}
+function renderPaperclipWakePrompt(value, options = {}) {
+  const normalized = normalizePaperclipWakePayload(value);
+  if (!normalized) return "";
+  const resumedSession = options.resumedSession === true;
+  const executionStage = normalized.executionStage;
+  const principalLabel = (principal) => {
+    if (!principal || !principal.type) return "unknown";
+    if (principal.type === "agent") return principal.agentId ? `agent ${principal.agentId}` : "agent";
+    return principal.userId ? `user ${principal.userId}` : "user";
+  };
+  const lines = resumedSession ? [
+    "## Paperclip Resume Delta",
+    "",
+    "You are resuming an existing Paperclip session.",
+    "This heartbeat is scoped to the issue below. Do not switch to another issue until you have handled this wake.",
+    "Focus on the new wake delta below and continue the current task without restating the full heartbeat boilerplate.",
+    "Fetch the API thread only when `fallbackFetchNeeded` is true or you need broader history than this batch.",
+    "",
+    "Execution contract: take concrete action in this heartbeat when the issue is actionable; do not stop at a plan unless planning was requested. Leave durable progress and then give the issue a clear final disposition before ending the heartbeat: `done`, `in_review` with a real reviewer/approval/interaction path, `blocked` with first-class blockers or a named unblock owner/action, delegated follow-up issues with blockers, or `in_progress` only when a live continuation path exists. Use child issues for long or parallel delegated work instead of polling. Comments, documents, screenshots, work products, and `Remaining` bullets are evidence, not valid liveness paths by themselves.",
+    "",
+    `- reason: ${normalized.reason ?? "unknown"}`,
+    `- issue: ${normalized.issue?.identifier ?? normalized.issue?.id ?? "unknown"}${normalized.issue?.title ? ` ${normalized.issue.title}` : ""}`,
+    `- pending comments: ${normalized.includedCount}/${normalized.requestedCount}`,
+    `- latest comment id: ${normalized.latestCommentId ?? "unknown"}`,
+    `- fallback fetch needed: ${normalized.fallbackFetchNeeded ? "yes" : "no"}`
+  ] : [
+    "## Paperclip Wake Payload",
+    "",
+    "Treat this wake payload as the highest-priority change for the current heartbeat.",
+    "This heartbeat is scoped to the issue below. Do not switch to another issue until you have handled this wake.",
+    "Before generic repo exploration or boilerplate heartbeat updates, acknowledge the latest comment and explain how it changes your next action.",
+    "Use this inline wake data first before refetching the issue thread.",
+    "Only fetch the API thread when `fallbackFetchNeeded` is true or you need broader history than this batch.",
+    "",
+    "Execution contract: take concrete action in this heartbeat when the issue is actionable; do not stop at a plan unless planning was requested. Leave durable progress and then give the issue a clear final disposition before ending the heartbeat: `done`, `in_review` with a real reviewer/approval/interaction path, `blocked` with first-class blockers or a named unblock owner/action, delegated follow-up issues with blockers, or `in_progress` only when a live continuation path exists. Use child issues for long or parallel delegated work instead of polling. Comments, documents, screenshots, work products, and `Remaining` bullets are evidence, not valid liveness paths by themselves.",
+    "",
+    `- reason: ${normalized.reason ?? "unknown"}`,
+    `- issue: ${normalized.issue?.identifier ?? normalized.issue?.id ?? "unknown"}${normalized.issue?.title ? ` ${normalized.issue.title}` : ""}`,
+    `- pending comments: ${normalized.includedCount}/${normalized.requestedCount}`,
+    `- latest comment id: ${normalized.latestCommentId ?? "unknown"}`,
+    `- fallback fetch needed: ${normalized.fallbackFetchNeeded ? "yes" : "no"}`
+  ];
+  if (normalized.issue?.status) {
+    lines.push(`- issue status: ${normalized.issue.status}`);
+  }
+  if (normalized.issue?.workMode) {
+    lines.push(`- issue work mode: ${normalized.issue.workMode}`);
+  }
+  if (normalized.issue?.priority) {
+    lines.push(`- issue priority: ${normalized.issue.priority}`);
+  }
+  if (normalized.issue?.workMode === "planning" && !normalized.taskWatchdog) {
+    const hasWakeComments = normalized.comments.length > 0;
+    const acceptedPlanContinuation = !hasWakeComments && normalized.interactionKind === "request_confirmation" && normalized.interactionStatus === "accepted";
+    let directive = "Make the plan only. Do not write code or perform implementation work.";
+    if (hasWakeComments) {
+      directive = "Update the plan only. Do not write code or perform implementation work.";
+    }
+    if (acceptedPlanContinuation) {
+      directive = "Create child issues from the approved plan only. Do not write code or perform implementation work on the planning issue.";
+    }
+    lines.push(`- planning directive: ${directive}`);
+    if (acceptedPlanContinuation) {
+      lines.push(
+        "- accepted-plan continuation: you may create child implementation issues from the approved plan, but must not start implementation work on the planning issue itself"
+      );
+    }
+  }
+  if (normalized.checkedOutByHarness) {
+    lines.push("- checkout: already claimed by the harness for this run");
+  }
+  if (normalized.dependencyBlockedInteraction) {
+    lines.push("- dependency-blocked interaction: yes");
+    lines.push("- execution scope: respond or triage the human comment; do not treat blocker-dependent deliverable work as unblocked");
+    if (normalized.unresolvedBlockerSummaries.length > 0) {
+      const blockers = normalized.unresolvedBlockerSummaries.map((blocker) => `${blocker.identifier ?? blocker.id ?? "unknown"}${blocker.title ? ` ${blocker.title}` : ""}${blocker.status ? ` (${blocker.status})` : ""}`).join("; ");
+      lines.push(`- unresolved blockers: ${blockers}`);
+    } else if (normalized.unresolvedBlockerIssueIds.length > 0) {
+      lines.push(`- unresolved blocker issue ids: ${normalized.unresolvedBlockerIssueIds.join(", ")}`);
+    }
+  }
+  if (normalized.treeHoldInteraction) {
+    lines.push("- tree-hold interaction: yes");
+    lines.push("- execution scope: respond or triage the human comment; the subtree remains paused until an explicit resume action");
+    if (normalized.activeTreeHold) {
+      const hold = normalized.activeTreeHold;
+      lines.push(`- active tree hold: ${hold.holdId ?? "unknown"}${hold.rootIssueId ? ` rooted at ${hold.rootIssueId}` : ""}${hold.mode ? ` (${hold.mode})` : ""}`);
+    }
+  }
+  if (normalized.missingCount > 0) {
+    lines.push(`- omitted comments: ${normalized.missingCount}`);
+  }
+  if (executionStage) {
+    lines.push(
+      `- execution wake role: ${executionStage.wakeRole ?? "unknown"}`,
+      `- execution stage: ${executionStage.stageType ?? "unknown"}`,
+      `- execution participant: ${principalLabel(executionStage.currentParticipant)}`,
+      `- execution return assignee: ${principalLabel(executionStage.returnAssignee)}`,
+      `- last decision outcome: ${executionStage.lastDecisionOutcome ?? "none"}`
+    );
+    if (executionStage.allowedActions.length > 0) {
+      lines.push(`- allowed actions: ${executionStage.allowedActions.join(", ")}`);
+    }
+    if (executionStage.reviewRequest) {
+      lines.push(
+        "",
+        "Review request instructions:",
+        executionStage.reviewRequest.instructions
+      );
+    }
+    lines.push("");
+    if (executionStage.wakeRole === "reviewer" || executionStage.wakeRole === "approver") {
+      lines.push(
+        `You are waking as the active ${executionStage.wakeRole} for this issue.`,
+        "Do not execute the task itself or continue executor work.",
+        "Review the issue and choose one of the allowed actions above.",
+        "If you request changes, the workflow routes back to the stored return assignee.",
+        ""
+      );
+    } else if (executionStage.wakeRole === "executor") {
+      lines.push(
+        "You are waking because changes were requested in the execution workflow.",
+        "Address the requested changes on this issue and resubmit when the work is ready.",
+        ""
+      );
+    }
+  }
+  if (normalized.taskWatchdog) {
+    const watchdog = normalized.taskWatchdog;
+    const watchedLabel = watchdog.watchedIssueIdentifier ?? watchdog.watchedIssueId ?? "unknown";
+    lines.push(
+      "",
+      "## Task Watchdog Mandate",
+      "",
+      `Watched issue: ${watchedLabel}${watchdog.watchedIssueTitle ? ` ${watchdog.watchedIssueTitle}` : ""}`
+    );
+    if (watchdog.stopFingerprint) {
+      lines.push(`Stop fingerprint: ${watchdog.stopFingerprint}`);
+    }
+    lines.push("", WATCHDOG_DEFAULT_MANDATE);
+    if (watchdog.capabilities) {
+      lines.push("", "Server-derived watchdog capability metadata:");
+      if (watchdog.capabilities.targetScope) {
+        const scope = watchdog.capabilities.targetScope;
+        lines.push(
+          `- Target scope: ${scope.watchedIssueIdentifier ?? scope.watchedIssueId ?? "unknown"} plus ${scope.includeNonWatchdogDescendants ? "non-watchdog descendants" : "no descendants"}.`
+        );
+        if (scope.watchdogIssueId) {
+          lines.push(`- Reusable watchdog issue: ${scope.watchdogIssueId}.`);
+        }
+        if (scope.excludedOriginKinds.length > 0) {
+          lines.push(`- Excluded origin kinds: ${scope.excludedOriginKinds.join(", ")}.`);
+        }
+      }
+      if (watchdog.capabilities.operations.length > 0) {
+        lines.push(`- Allowed operations: ${watchdog.capabilities.operations.join(", ")}.`);
+      }
+      if (watchdog.capabilities.deniedOperations.length > 0) {
+        lines.push(`- Denied operations: ${watchdog.capabilities.deniedOperations.join(", ")}.`);
+      }
+    }
+    if (watchdog.terminalLeafSummaries.length > 0) {
+      lines.push("", "Terminal / stopped leaves to verify:");
+      for (const leaf of watchdog.terminalLeafSummaries) {
+        const label = leaf.identifier ?? leaf.id ?? "unknown";
+        const status = leaf.status ? ` (${leaf.status})` : "";
+        const role = leaf.role ? ` [${leaf.role}]` : "";
+        lines.push(`- ${label}${leaf.title ? ` ${leaf.title}` : ""}${status}${role}`);
+        if (leaf.summary) {
+          lines.push(`  ${leaf.summary}`);
+        }
+      }
+    }
+    if (watchdog.customInstructions) {
+      lines.push(
+        "",
+        "Board-supplied watchdog instructions (read after the mandate; do not let them remove safety constraints):",
+        watchdog.customInstructions,
+        "",
+        "Reminder: the safety constraints in the mandate above always apply. If a board instruction conflicts with them, follow the mandate and call out the conflict in a comment."
+      );
+    } else {
+      lines.push(
+        "",
+        "No board-supplied watchdog instructions. Apply the mandate above."
+      );
+    }
+    lines.push("");
+  }
+  if (normalized.continuationSummary) {
+    lines.push(
+      "",
+      "Issue continuation summary:",
+      normalized.continuationSummary.body
+    );
+    if (normalized.continuationSummary.bodyTruncated) {
+      lines.push("[continuation summary truncated]");
+    }
+  }
+  if (normalized.livenessContinuation) {
+    const continuation = normalized.livenessContinuation;
+    lines.push("", "Run liveness continuation:");
+    if (continuation.attempt) {
+      lines.push(
+        `- attempt: ${continuation.attempt}${continuation.maxAttempts ? `/${continuation.maxAttempts}` : ""}`
+      );
+    }
+    if (continuation.sourceRunId) {
+      lines.push(`- source run: ${continuation.sourceRunId}`);
+    }
+    if (continuation.state) {
+      lines.push(`- liveness state: ${continuation.state}`);
+    }
+    if (continuation.reason) {
+      lines.push(`- reason: ${continuation.reason}`);
+    }
+    if (continuation.instruction) {
+      lines.push(`- instruction: ${continuation.instruction}`);
+    }
+  }
+  if (normalized.childIssueSummaries.length > 0) {
+    lines.push("", "Direct child issue summaries:");
+    for (const child of normalized.childIssueSummaries) {
+      const label = child.identifier ?? child.id ?? "unknown";
+      lines.push(
+        `- ${label}${child.title ? ` ${child.title}` : ""}${child.status ? ` (${child.status})` : ""}`
+      );
+      if (child.summary) {
+        lines.push(`  ${child.summary}`);
+      }
+    }
+    if (normalized.childIssueSummaryTruncated) {
+      lines.push("[child issue summaries truncated]");
+    }
+  }
+  if (normalized.checkedOutByHarness) {
+    lines.push(
+      "",
+      "The harness already checked out this issue for the current run.",
+      "Do not call `/api/issues/{id}/checkout` again unless you intentionally switch to a different task.",
+      ""
+    );
+  }
+  if (normalized.comments.length > 0) {
+    lines.push("New comments in order:");
+  }
+  for (const [index, comment] of normalized.comments.entries()) {
+    const authorLabel = comment.authorId ? `${comment.authorType ?? "unknown"} ${comment.authorId}` : comment.authorType ?? "unknown";
+    lines.push(
+      `${index + 1}. comment ${comment.id ?? "unknown"} at ${comment.createdAt ?? "unknown"} by ${authorLabel}`,
+      comment.body
+    );
+    if (comment.bodyTruncated) {
+      lines.push("[comment body truncated]");
+    }
+    lines.push("");
+  }
+  return lines.join("\n").trim();
+}
+function redactEnvForLogs(env) {
+  const redacted = {};
+  for (const [key, value] of Object.entries(env)) {
+    redacted[key] = SENSITIVE_ENV_KEY.test(key) ? REDACTED_LOG_VALUE : value;
+  }
+  return redacted;
+}
+function redactCommandTextForLogs(command) {
+  return redactCommandText(command, REDACTED_LOG_VALUE);
+}
+function buildInvocationEnvForLogs(env, options = {}) {
+  const merged = { ...env };
+  const runtimeEnv = options.runtimeEnv ?? {};
+  for (const key of options.includeRuntimeKeys ?? []) {
+    if (key in merged) continue;
+    const value = runtimeEnv[key];
+    if (typeof value !== "string" || value.length === 0) continue;
+    merged[key] = value;
+  }
+  const resolvedCommand = options.resolvedCommand?.trim();
+  if (resolvedCommand) {
+    merged[options.resolvedCommandEnvKey ?? "PAPERCLIP_RESOLVED_COMMAND"] = redactCommandTextForLogs(resolvedCommand);
+  }
+  return redactEnvForLogs(merged);
+}
+function buildPaperclipEnv(agent) {
+  const resolveHostForUrl = (rawHost) => {
+    const host = rawHost.trim();
+    if (!host || host === "0.0.0.0" || host === "::") return "localhost";
+    if (host.includes(":") && !host.startsWith("[") && !host.endsWith("]")) return `[${host}]`;
+    return host;
+  };
+  const vars = {
+    PAPERCLIP_AGENT_ID: agent.id,
+    PAPERCLIP_COMPANY_ID: agent.companyId
+  };
+  const runtimeHost = resolveHostForUrl(
+    process.env.PAPERCLIP_LISTEN_HOST ?? process.env.HOST ?? "localhost"
+  );
+  const runtimePort = process.env.PAPERCLIP_LISTEN_PORT ?? process.env.PORT ?? "3100";
+  const apiUrl = process.env.PAPERCLIP_RUNTIME_API_URL ?? process.env.PAPERCLIP_API_URL ?? `http://${runtimeHost}:${runtimePort}`;
+  vars.PAPERCLIP_API_URL = apiUrl;
+  return vars;
+}
+function applyPaperclipWorkspaceEnv(env, input) {
+  const mappings = [
+    ["PAPERCLIP_WORKSPACE_CWD", input.workspaceCwd],
+    ["PAPERCLIP_WORKSPACE_SOURCE", input.workspaceSource],
+    ["PAPERCLIP_WORKSPACE_STRATEGY", input.workspaceStrategy],
+    ["PAPERCLIP_WORKSPACE_ID", input.workspaceId],
+    ["PAPERCLIP_WORKSPACE_REPO_URL", input.workspaceRepoUrl],
+    ["PAPERCLIP_WORKSPACE_REPO_REF", input.workspaceRepoRef],
+    ["PAPERCLIP_WORKSPACE_BRANCH", input.workspaceBranch],
+    ["PAPERCLIP_WORKSPACE_WORKTREE_PATH", input.workspaceWorktreePath],
+    ["AGENT_HOME", input.agentHome]
+  ];
+  for (const [key, value] of mappings) {
+    if (typeof value === "string" && value.length > 0) {
+      env[key] = value;
+    }
+  }
+  return env;
+}
+function shapePaperclipWorkspaceEnvForExecution(input) {
+  const workspaceCwd = typeof input.workspaceCwd === "string" && input.workspaceCwd.trim().length > 0 ? input.workspaceCwd.trim() : null;
+  const workspaceWorktreePath = typeof input.workspaceWorktreePath === "string" && input.workspaceWorktreePath.trim().length > 0 ? input.workspaceWorktreePath.trim() : null;
+  const workspaceHints = Array.isArray(input.workspaceHints) ? input.workspaceHints : [];
+  if (!input.executionTargetIsRemote) {
+    return {
+      workspaceCwd,
+      workspaceWorktreePath,
+      workspaceHints
+    };
+  }
+  const executionCwd = typeof input.executionCwd === "string" && input.executionCwd.trim().length > 0 ? input.executionCwd.trim() : null;
+  if (executionCwd === null) {
+    console.warn(
+      "[paperclip] shapePaperclipWorkspaceEnvForExecution called with executionCwd=null on a remote target; stripping workspaceCwd to avoid leaking local paths into the remote environment."
+    );
+  }
+  const realizedWorkspaceCwd = executionCwd;
+  const localWorkspaceCwd = workspaceCwd ? path3.resolve(workspaceCwd) : null;
+  const shapedWorkspaceHints = workspaceHints.map((hint) => {
+    const nextHint = { ...hint };
+    const hintCwd = typeof nextHint.cwd === "string" ? nextHint.cwd.trim() : "";
+    if (!hintCwd) return nextHint;
+    if (localWorkspaceCwd && path3.resolve(hintCwd) === localWorkspaceCwd) {
+      if (realizedWorkspaceCwd) {
+        nextHint.cwd = realizedWorkspaceCwd;
+      } else {
+        delete nextHint.cwd;
+      }
+      return nextHint;
+    }
+    delete nextHint.cwd;
+    return nextHint;
+  });
+  return {
+    workspaceCwd: realizedWorkspaceCwd,
+    workspaceWorktreePath: null,
+    workspaceHints: shapedWorkspaceHints
+  };
+}
+function rewriteWorkspaceCwdEnvVarsForExecution(input) {
+  const nextEnv = Object.fromEntries(
+    Object.entries(input.env).filter((entry) => typeof entry[1] === "string")
+  );
+  const localWorkspaceCwd = typeof input.workspaceCwd === "string" && input.workspaceCwd.trim().length > 0 ? path3.resolve(input.workspaceCwd) : null;
+  const remoteWorkspaceCwd = typeof input.executionCwd === "string" && input.executionCwd.trim().length > 0 ? input.executionCwd.trim() : null;
+  if (!input.executionTargetIsRemote || !localWorkspaceCwd || !remoteWorkspaceCwd) {
+    return nextEnv;
+  }
+  for (const [key, value] of Object.entries(nextEnv)) {
+    if (!key.endsWith("_WORKSPACE_CWD")) continue;
+    const trimmed = value.trim();
+    if (!trimmed) continue;
+    if (path3.resolve(trimmed) !== localWorkspaceCwd) continue;
+    nextEnv[key] = remoteWorkspaceCwd;
+  }
+  return nextEnv;
+}
+function refreshPaperclipWorkspaceEnvForExecution(input) {
+  const shapedWorkspaceEnv = shapePaperclipWorkspaceEnvForExecution({
+    workspaceCwd: input.workspaceCwd,
+    workspaceWorktreePath: input.workspaceWorktreePath,
+    workspaceHints: input.workspaceHints,
+    executionTargetIsRemote: input.executionTargetIsRemote,
+    executionCwd: input.executionCwd
+  });
+  delete input.env.PAPERCLIP_WORKSPACE_CWD;
+  delete input.env.PAPERCLIP_WORKSPACE_WORKTREE_PATH;
+  delete input.env.PAPERCLIP_WORKSPACES_JSON;
+  applyPaperclipWorkspaceEnv(input.env, {
+    workspaceCwd: shapedWorkspaceEnv.workspaceCwd,
+    workspaceSource: input.workspaceSource,
+    workspaceStrategy: input.workspaceStrategy,
+    workspaceId: input.workspaceId,
+    workspaceRepoUrl: input.workspaceRepoUrl,
+    workspaceRepoRef: input.workspaceRepoRef,
+    workspaceBranch: input.workspaceBranch,
+    workspaceWorktreePath: shapedWorkspaceEnv.workspaceWorktreePath,
+    agentHome: input.agentHome
+  });
+  if (shapedWorkspaceEnv.workspaceHints.length > 0) {
+    input.env.PAPERCLIP_WORKSPACES_JSON = JSON.stringify(shapedWorkspaceEnv.workspaceHints);
+  }
+  const shapedEnvConfig = rewriteWorkspaceCwdEnvVarsForExecution({
+    env: input.envConfig ?? {},
+    workspaceCwd: input.workspaceCwd,
+    executionCwd: shapedWorkspaceEnv.workspaceCwd,
+    executionTargetIsRemote: input.executionTargetIsRemote
+  });
+  for (const [key, value] of Object.entries(shapedEnvConfig)) {
+    input.env[key] = value;
+  }
+  return shapedWorkspaceEnv;
+}
+function sanitizeInheritedPaperclipEnv(baseEnv) {
+  const env = { ...baseEnv };
+  for (const key of Object.keys(env)) {
+    if (!key.startsWith("PAPERCLIP_")) continue;
+    if (key === "PAPERCLIP_RUNTIME_API_URL") continue;
+    if (key === "PAPERCLIP_LISTEN_HOST") continue;
+    if (key === "PAPERCLIP_LISTEN_PORT") continue;
+    delete env[key];
+  }
+  return env;
+}
+function defaultPathForPlatform() {
+  if (process.platform === "win32") {
+    return "C:\\Windows\\System32;C:\\Windows;C:\\Windows\\System32\\Wbem";
+  }
+  return "/usr/local/bin:/opt/homebrew/bin:/usr/local/sbin:/usr/bin:/bin:/usr/sbin:/sbin";
+}
+function windowsPathExts(env) {
+  return (env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";").filter(Boolean);
+}
+async function pathExists(candidate) {
+  try {
+    await fs3.access(candidate, process.platform === "win32" ? fsConstants3.F_OK : fsConstants3.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function resolveCommandPath(command, cwd, env) {
+  const hasPathSeparator = command.includes("/") || command.includes("\\");
+  if (hasPathSeparator) {
+    const absolute = path3.isAbsolute(command) ? command : path3.resolve(cwd, command);
+    return await pathExists(absolute) ? absolute : null;
+  }
+  const pathValue = env.PATH ?? env.Path ?? "";
+  const delimiter = process.platform === "win32" ? ";" : ":";
+  const dirs = pathValue.split(delimiter).filter(Boolean);
+  const exts = process.platform === "win32" ? windowsPathExts(env) : [""];
+  const hasExtension = process.platform === "win32" && path3.extname(command).length > 0;
+  for (const dir of dirs) {
+    const candidates = process.platform === "win32" ? hasExtension ? [path3.join(dir, command)] : exts.map((ext) => path3.join(dir, `${command}${ext}`)) : [path3.join(dir, command)];
+    for (const candidate of candidates) {
+      if (await pathExists(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+async function resolveCommandForLogs(command, cwd, env, options = {}) {
+  const remote = options.remoteExecution ?? null;
+  if (remote) {
+    return `ssh://${remote.username}@${remote.host}:${remote.port}/${remote.remoteCwd} :: ${command}`;
+  }
+  return await resolveCommandPath(command, cwd, env) ?? command;
+}
+function quoteForCmd(arg) {
+  if (!arg.length) return '""';
+  const escaped = arg.replace(/"/g, '""');
+  return /[\s"&<>|^()]/.test(escaped) ? `"${escaped}"` : escaped;
+}
+function sanitizeSshRemoteEnv(env, inheritedEnv = process.env) {
+  return sanitizeRemoteExecutionEnv(env, inheritedEnv);
+}
+function resolveWindowsCmdShell(env) {
+  const fallbackRoot = env.SystemRoot || process.env.SystemRoot || "C:\\Windows";
+  return path3.join(fallbackRoot, "System32", "cmd.exe");
+}
+async function resolveSpawnTarget(command, args, cwd, env, options = {}) {
+  const remote = options.remoteExecution ?? null;
+  if (remote) {
+    const sshResolved = await resolveCommandPath("ssh", process.cwd(), env);
+    if (!sshResolved) {
+      throw new Error('Command not found in PATH: "ssh"');
+    }
+    const spawnTarget = await buildSshSpawnTarget({
+      spec: remote,
+      command,
+      args,
+      env: Object.fromEntries(
+        Object.entries(options.remoteEnv ?? {}).filter((entry) => typeof entry[1] === "string")
+      )
+    });
+    return {
+      command: sshResolved,
+      args: spawnTarget.args,
+      cwd: process.cwd(),
+      cleanup: spawnTarget.cleanup
+    };
+  }
+  const resolved = await resolveCommandPath(command, cwd, env);
+  const executable = resolved ?? command;
+  if (process.platform !== "win32") {
+    return { command: executable, args };
+  }
+  if (/\.(cmd|bat)$/i.test(executable)) {
+    const shell = resolveWindowsCmdShell(env);
+    const commandLine = [quoteForCmd(executable), ...args.map(quoteForCmd)].join(" ");
+    return {
+      command: shell,
+      args: ["/d", "/s", "/c", commandLine]
+    };
+  }
+  return { command: executable, args };
+}
+function ensurePathInEnv(env) {
+  if (typeof env.PATH === "string" && env.PATH.length > 0) return env;
+  if (typeof env.Path === "string" && env.Path.length > 0) return env;
+  return { ...env, PATH: defaultPathForPlatform() };
+}
+async function ensureAbsoluteDirectory(cwd, opts = {}) {
+  if (!path3.isAbsolute(cwd)) {
+    throw new Error(`Working directory must be an absolute path: "${cwd}"`);
+  }
+  const assertDirectory = async () => {
+    const stats = await fs3.stat(cwd);
+    if (!stats.isDirectory()) {
+      throw new Error(`Working directory is not a directory: "${cwd}"`);
+    }
+  };
+  try {
+    await assertDirectory();
+    return;
+  } catch (err) {
+    const code = err.code;
+    if (!opts.createIfMissing || code !== "ENOENT") {
+      if (code === "ENOENT") {
+        throw new Error(`Working directory does not exist: "${cwd}"`);
+      }
+      throw err instanceof Error ? err : new Error(String(err));
+    }
+  }
+  try {
+    await fs3.mkdir(cwd, { recursive: true });
+    await assertDirectory();
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    throw new Error(`Could not create working directory "${cwd}": ${reason}`);
+  }
+}
+async function resolvePaperclipSkillsDir(moduleDir, additionalCandidates = []) {
+  const candidates = [
+    ...PAPERCLIP_SKILL_ROOT_RELATIVE_CANDIDATES.map((relativePath) => path3.resolve(moduleDir, relativePath)),
+    ...additionalCandidates.map((candidate) => path3.resolve(candidate))
+  ];
+  const seenRoots = /* @__PURE__ */ new Set();
+  for (const root of candidates) {
+    if (seenRoots.has(root)) continue;
+    seenRoots.add(root);
+    const isDirectory = await fs3.stat(root).then((stats) => stats.isDirectory()).catch(() => false);
+    if (isDirectory) return root;
+  }
+  return null;
+}
+async function listPaperclipSkillEntries(moduleDir, additionalCandidates = []) {
+  const root = await resolvePaperclipSkillsDir(moduleDir, additionalCandidates);
+  if (!root) return [];
+  try {
+    const entries = await fs3.readdir(root, { withFileTypes: true });
+    const dirs = entries.filter((entry) => entry.isDirectory());
+    return dirs.map((entry) => ({
+      key: `paperclipai/paperclip/${entry.name}`,
+      runtimeName: entry.name,
+      source: path3.join(root, entry.name)
+    }));
+  } catch {
+    return [];
+  }
+}
+async function readInstalledSkillTargets(skillsHome) {
+  const entries = await fs3.readdir(skillsHome, { withFileTypes: true }).catch(() => []);
+  const out = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    const fullPath = path3.join(skillsHome, entry.name);
+    const linkedPath = entry.isSymbolicLink() ? await fs3.readlink(fullPath).catch(() => null) : null;
+    out.set(entry.name, resolveInstalledEntryTarget(skillsHome, entry.name, entry, linkedPath));
+  }
+  return out;
+}
+function buildRuntimeMountedSkillSnapshot(options) {
+  const {
+    adapterType,
+    availableEntries,
+    desiredSkills,
+    configuredDetail,
+    missingDetail = "Paperclip cannot find this skill in the local runtime skills directory.",
+    mode = "ephemeral",
+    externalInstalled,
+    externalLocationLabel,
+    externalDetail = "Installed outside Paperclip management.",
+    skillsHome
+  } = options;
+  const supported = options.supported ?? mode !== "unsupported";
+  const availableByKey = new Map(availableEntries.map((entry) => [entry.key, entry]));
+  const desiredSet = new Set(desiredSkills);
+  const entries = [];
+  const warnings = [...options.warnings ?? []];
+  for (const available of availableEntries) {
+    const desired = desiredSet.has(available.key);
+    if (isPaperclipSkillSourceMissing(available)) {
+      entries.push({
+        key: available.key,
+        runtimeName: available.runtimeName,
+        versionId: available.versionId ?? null,
+        currentVersionId: available.currentVersionId ?? null,
+        desired,
+        managed: true,
+        state: "missing",
+        sourcePath: null,
+        targetPath: null,
+        detail: resolvePaperclipSkillMissingDetail(available, missingDetail),
+        ...buildManagedSkillOrigin()
+      });
+      continue;
+    }
+    const configured = supported && mode === "ephemeral" && desired;
+    entries.push({
+      key: available.key,
+      runtimeName: available.runtimeName,
+      versionId: available.versionId ?? null,
+      currentVersionId: available.currentVersionId ?? null,
+      desired,
+      managed: true,
+      state: configured ? "configured" : "available",
+      sourcePath: available.source,
+      targetPath: null,
+      detail: desired ? configured ? resolveSkillDetail(configuredDetail, available) : resolveSkillDetail(
+        options.unsupportedDetail ?? "Desired state is stored in Paperclip only; this adapter cannot apply skills at runtime.",
+        available
+      ) : null,
+      ...buildManagedSkillOrigin()
+    });
+  }
+  for (const desiredSkill of desiredSkills) {
+    if (availableByKey.has(desiredSkill)) continue;
+    warnings.push(`Desired skill "${desiredSkill}" is not available from the Paperclip skills directory.`);
+    entries.push({
+      key: desiredSkill,
+      runtimeName: null,
+      desired: true,
+      managed: true,
+      state: "missing",
+      sourcePath: null,
+      targetPath: null,
+      detail: missingDetail,
+      origin: "external_unknown",
+      originLabel: "External or unavailable",
+      readOnly: false
+    });
+  }
+  if (externalInstalled) {
+    for (const [name, installedEntry] of externalInstalled.entries()) {
+      if (availableEntries.some((entry) => entry.runtimeName === name)) continue;
+      entries.push({
+        key: name,
+        runtimeName: name,
+        desired: false,
+        managed: false,
+        state: "external",
+        origin: "user_installed",
+        originLabel: "User-installed",
+        locationLabel: skillLocationLabel(externalLocationLabel),
+        readOnly: true,
+        sourcePath: null,
+        targetPath: installedEntry.targetPath ?? (skillsHome ? path3.join(skillsHome, name) : null),
+        detail: externalDetail
+      });
+    }
+  }
+  entries.sort((left, right) => left.key.localeCompare(right.key));
+  return {
+    adapterType,
+    supported,
+    mode,
+    desiredSkills,
+    desiredSkillEntries: desiredSkills.map((key) => ({
+      key,
+      versionId: availableByKey.get(key)?.versionId ?? null
+    })),
+    entries,
+    warnings
+  };
+}
+function buildPersistentSkillSnapshot(options) {
+  const {
+    adapterType,
+    availableEntries,
+    desiredSkills,
+    installed,
+    skillsHome,
+    locationLabel,
+    installedDetail,
+    missingDetail,
+    externalConflictDetail,
+    externalDetail
+  } = options;
+  const availableByKey = new Map(availableEntries.map((entry) => [entry.key, entry]));
+  const desiredSet = new Set(desiredSkills);
+  const entries = [];
+  const warnings = [...options.warnings ?? []];
+  for (const available of availableEntries) {
+    const installedEntry = installed.get(available.runtimeName) ?? null;
+    const desired = desiredSet.has(available.key);
+    if (isPaperclipSkillSourceMissing(available)) {
+      entries.push({
+        key: available.key,
+        runtimeName: available.runtimeName,
+        versionId: available.versionId ?? null,
+        currentVersionId: available.currentVersionId ?? null,
+        desired,
+        managed: true,
+        state: "missing",
+        sourcePath: null,
+        targetPath: path3.join(skillsHome, available.runtimeName),
+        detail: resolvePaperclipSkillMissingDetail(
+          available,
+          missingDetail
+        ),
+        ...buildManagedSkillOrigin()
+      });
+      continue;
+    }
+    let state = "available";
+    let managed = false;
+    let detail = null;
+    if (installedEntry?.targetPath === available.source) {
+      managed = true;
+      state = desired ? "installed" : "stale";
+      detail = installedDetail ?? null;
+    } else if (installedEntry) {
+      state = "external";
+      detail = desired ? externalConflictDetail : externalDetail;
+    } else if (desired) {
+      state = "missing";
+      detail = missingDetail;
+    }
+    entries.push({
+      key: available.key,
+      runtimeName: available.runtimeName,
+      versionId: available.versionId ?? null,
+      currentVersionId: available.currentVersionId ?? null,
+      desired,
+      managed,
+      state,
+      sourcePath: available.source,
+      targetPath: path3.join(skillsHome, available.runtimeName),
+      detail,
+      ...buildManagedSkillOrigin()
+    });
+  }
+  for (const desiredSkill of desiredSkills) {
+    if (availableByKey.has(desiredSkill)) continue;
+    warnings.push(`Desired skill "${desiredSkill}" is not available from the Paperclip skills directory.`);
+    entries.push({
+      key: desiredSkill,
+      runtimeName: null,
+      desired: true,
+      managed: true,
+      state: "missing",
+      sourcePath: null,
+      targetPath: null,
+      detail: "Paperclip cannot find this skill in the local runtime skills directory.",
+      origin: "external_unknown",
+      originLabel: "External or unavailable",
+      readOnly: false
+    });
+  }
+  for (const [name, installedEntry] of installed.entries()) {
+    if (availableEntries.some((entry) => entry.runtimeName === name)) continue;
+    entries.push({
+      key: name,
+      runtimeName: name,
+      desired: false,
+      managed: false,
+      state: "external",
+      origin: "user_installed",
+      originLabel: "User-installed",
+      locationLabel: skillLocationLabel(locationLabel),
+      readOnly: true,
+      sourcePath: null,
+      targetPath: installedEntry.targetPath ?? path3.join(skillsHome, name),
+      detail: externalDetail
+    });
+  }
+  entries.sort((left, right) => left.key.localeCompare(right.key));
+  return {
+    adapterType,
+    supported: true,
+    mode: "persistent",
+    desiredSkills,
+    desiredSkillEntries: desiredSkills.map((key) => ({
+      key,
+      versionId: availableByKey.get(key)?.versionId ?? null
+    })),
+    entries,
+    warnings
+  };
+}
+function normalizeConfiguredPaperclipRuntimeSkills(value) {
+  if (!Array.isArray(value)) return [];
+  const out = [];
+  for (const rawEntry of value) {
+    const entry = parseObject(rawEntry);
+    const key = asString(entry.key, asString(entry.name, "")).trim();
+    const runtimeName = asString(entry.runtimeName, asString(entry.name, "")).trim();
+    const source = asString(entry.source, "").trim();
+    if (!key || !runtimeName || !source) continue;
+    out.push({
+      key,
+      runtimeName,
+      source,
+      versionId: typeof entry.versionId === "string" && entry.versionId.trim().length > 0 ? entry.versionId.trim() : null,
+      currentVersionId: typeof entry.currentVersionId === "string" && entry.currentVersionId.trim().length > 0 ? entry.currentVersionId.trim() : null,
+      sourceStatus: entry.sourceStatus === "missing" ? "missing" : "available",
+      missingDetail: typeof entry.missingDetail === "string" && entry.missingDetail.trim().length > 0 ? entry.missingDetail.trim() : null
+    });
+  }
+  return out;
+}
+async function readPaperclipRuntimeSkillEntries(config, moduleDir, additionalCandidates = []) {
+  const configuredEntries = normalizeConfiguredPaperclipRuntimeSkills(config.paperclipRuntimeSkills);
+  if (configuredEntries.length > 0) return configuredEntries;
+  return listPaperclipSkillEntries(moduleDir, additionalCandidates);
+}
+async function readPaperclipSkillMarkdown(moduleDir, skillKey) {
+  const normalized = skillKey.trim().toLowerCase();
+  if (!normalized) return null;
+  const entries = await listPaperclipSkillEntries(moduleDir);
+  const match = entries.find((entry) => entry.key === normalized);
+  if (!match) return null;
+  try {
+    return await fs3.readFile(path3.join(match.source, "SKILL.md"), "utf8");
+  } catch {
+    return null;
+  }
+}
+function readPaperclipSkillSyncPreference(config) {
+  const raw = config.paperclipSkillSync;
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    return { explicit: false, desiredSkills: [], desiredSkillEntries: [] };
+  }
+  const syncConfig = raw;
+  const desiredValues = syncConfig.desiredSkills;
+  const desired = Array.isArray(desiredValues) ? desiredValues.flatMap((value) => {
+    if (typeof value === "string") {
+      const key = value.trim();
+      return key ? [{ key, versionId: null }] : [];
+    }
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+      const record = value;
+      const key = typeof record.key === "string" ? record.key.trim() : "";
+      if (!key) return [];
+      const versionId = typeof record.versionId === "string" && record.versionId.trim() ? record.versionId.trim() : null;
+      return [{ key, versionId }];
+    }
+    return [];
+  }) : [];
+  const byKey = /* @__PURE__ */ new Map();
+  for (const entry of desired) {
+    if (!byKey.has(entry.key)) byKey.set(entry.key, entry);
+  }
+  const desiredSkillEntries = Array.from(byKey.values());
+  return {
+    explicit: Object.prototype.hasOwnProperty.call(raw, "desiredSkills"),
+    desiredSkills: desiredSkillEntries.map((entry) => entry.key),
+    desiredSkillEntries
+  };
+}
+function canonicalizeDesiredPaperclipSkillReference(reference, availableEntries) {
+  const normalizedReference = reference.trim().toLowerCase();
+  if (!normalizedReference) return "";
+  const exactKey = availableEntries.find((entry) => entry.key.trim().toLowerCase() === normalizedReference);
+  if (exactKey) return exactKey.key;
+  const byRuntimeName = availableEntries.filter(
+    (entry) => typeof entry.runtimeName === "string" && entry.runtimeName.trim().toLowerCase() === normalizedReference
+  );
+  if (byRuntimeName.length === 1) return byRuntimeName[0].key;
+  const slugMatches = availableEntries.filter(
+    (entry) => entry.key.trim().toLowerCase().split("/").pop() === normalizedReference
+  );
+  if (slugMatches.length === 1) return slugMatches[0].key;
+  return normalizedReference;
+}
+function resolvePaperclipDesiredSkillNames(config, availableEntries) {
+  const preference = readPaperclipSkillSyncPreference(config);
+  if (!preference.explicit) return [];
+  const desiredSkills = preference.desiredSkills.map((reference) => canonicalizeDesiredPaperclipSkillReference(reference, availableEntries)).filter(Boolean);
+  return Array.from(new Set(desiredSkills));
+}
+function writePaperclipSkillSyncPreference(config, desiredSkills) {
+  const next = { ...config };
+  const raw = next.paperclipSkillSync;
+  const current = typeof raw === "object" && raw !== null && !Array.isArray(raw) ? { ...raw } : {};
+  const entries = desiredSkills.flatMap((value) => {
+    if (typeof value === "string") {
+      const key2 = value.trim();
+      return key2 ? [{ key: key2, versionId: null }] : [];
+    }
+    const key = value.key.trim();
+    if (!key) return [];
+    return [{ key, versionId: value.versionId ?? null }];
+  });
+  const byKey = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    if (!byKey.has(entry.key)) byKey.set(entry.key, entry);
+  }
+  const normalized = Array.from(byKey.values());
+  current.desiredSkills = normalized.some((entry) => entry.versionId) ? normalized : normalized.map((entry) => entry.key);
+  next.paperclipSkillSync = current;
+  return next;
+}
+async function ensurePaperclipSkillSymlink(source, target, linkSkill = (linkSource, linkTarget) => fs3.symlink(linkSource, linkTarget)) {
+  const existing = await fs3.lstat(target).catch(() => null);
+  if (!existing) {
+    await linkSkill(source, target);
+    return "created";
+  }
+  if (!existing.isSymbolicLink()) {
+    return "skipped";
+  }
+  const linkedPath = await fs3.readlink(target).catch(() => null);
+  if (!linkedPath) return "skipped";
+  const resolvedLinkedPath = path3.resolve(path3.dirname(target), linkedPath);
+  if (resolvedLinkedPath === source) {
+    return "skipped";
+  }
+  const linkedPathExists = await fs3.stat(resolvedLinkedPath).then(() => true).catch(() => false);
+  if (linkedPathExists) {
+    return "skipped";
+  }
+  await fs3.unlink(target);
+  await linkSkill(source, target);
+  return "repaired";
+}
+async function hashSkillDirectory(root) {
+  const hash = createHash2("sha256");
+  async function visit(candidate, relativePath) {
+    const stat = await fs3.lstat(candidate);
+    if (stat.isSymbolicLink()) {
+      hash.update(`symlink:${relativePath}
+`);
+      return;
+    }
+    if (stat.isDirectory()) {
+      hash.update(`dir:${relativePath}
+`);
+      const entries = await fs3.readdir(candidate, { withFileTypes: true });
+      entries.sort((left, right) => left.name.localeCompare(right.name));
+      for (const entry of entries) {
+        const childRelativePath = relativePath ? `${relativePath}/${entry.name}` : entry.name;
+        await visit(path3.join(candidate, entry.name), childRelativePath);
+      }
+      return;
+    }
+    if (stat.isFile()) {
+      hash.update(`file:${relativePath}:${stat.mode}
+`);
+      hash.update(await fs3.readFile(candidate));
+      hash.update("\n");
+      return;
+    }
+    hash.update(`other:${relativePath}:${stat.mode}
+`);
+  }
+  await visit(root, "");
+  return hash.digest("hex");
+}
+async function materializedSkillFingerprintMatches(targetRoot, sourceFingerprint) {
+  try {
+    const raw = JSON.parse(await fs3.readFile(path3.join(targetRoot, MATERIALIZED_SKILL_SENTINEL), "utf8"));
+    const parsed = parseObject(raw);
+    return parsed.version === 1 && parsed.sourceFingerprint === sourceFingerprint;
+  } catch {
+    return false;
+  }
+}
+async function acquireMaterializeLock(lockDir) {
+  await fs3.mkdir(path3.dirname(lockDir), { recursive: true });
+  const deadline = Date.now() + MATERIALIZED_SKILL_LOCK_STALE_MS;
+  while (true) {
+    try {
+      await fs3.mkdir(lockDir);
+      await fs3.writeFile(
+        path3.join(lockDir, MATERIALIZED_SKILL_LOCK_OWNER),
+        `${JSON.stringify({ pid: process.pid, createdAt: (/* @__PURE__ */ new Date()).toISOString() })}
+`,
+        "utf8"
+      );
+      return async () => {
+        await fs3.rm(lockDir, { recursive: true, force: true });
+      };
+    } catch (err) {
+      const code = err && typeof err === "object" ? err.code : null;
+      if (code !== "EEXIST") throw err;
+      if (await removeStaleMaterializeLock(lockDir, MATERIALIZED_SKILL_LOCK_STALE_MS)) continue;
+      if (Date.now() >= deadline) {
+        throw new Error(`Timed out waiting for Paperclip skill materialization lock at ${lockDir}`);
+      }
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+  }
+}
+function isPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    const code = err && typeof err === "object" ? err.code : null;
+    return code === "EPERM";
+  }
+}
+async function removeStaleMaterializeLock(lockDir, staleMs) {
+  const ownerPath = path3.join(lockDir, MATERIALIZED_SKILL_LOCK_OWNER);
+  let shouldRemove = false;
+  try {
+    const raw = JSON.parse(await fs3.readFile(ownerPath, "utf8"));
+    const owner = parseObject(raw);
+    const pid = typeof owner.pid === "number" ? owner.pid : 0;
+    const createdAt = typeof owner.createdAt === "string" ? Date.parse(owner.createdAt) : Number.NaN;
+    const ageMs = Number.isFinite(createdAt) ? Date.now() - createdAt : staleMs + 1;
+    shouldRemove = !isPidAlive(pid) || ageMs > staleMs;
+  } catch {
+    const stat = await fs3.stat(lockDir).catch(() => null);
+    shouldRemove = !stat || Date.now() - stat.mtimeMs > staleMs;
+  }
+  if (!shouldRemove) return false;
+  await fs3.rm(lockDir, { recursive: true, force: true }).catch(() => {
+  });
+  return true;
+}
+async function materializePaperclipSkillCopy(source, target) {
+  const sourceRoot = path3.resolve(source);
+  const targetRoot = path3.resolve(target);
+  const relativeTarget = path3.relative(sourceRoot, targetRoot);
+  const relativeSource = path3.relative(targetRoot, sourceRoot);
+  if (!relativeTarget || !relativeTarget.startsWith("..") && !path3.isAbsolute(relativeTarget) || !relativeSource || !relativeSource.startsWith("..") && !path3.isAbsolute(relativeSource)) {
+    throw new Error("Refusing to materialize a skill into itself, an ancestor, or one of its descendants.");
+  }
+  const rootStat = await fs3.lstat(sourceRoot);
+  if (rootStat.isSymbolicLink()) {
+    throw new Error("Refusing to materialize a skill root that is itself a symlink.");
+  }
+  if (!rootStat.isDirectory()) {
+    throw new Error("Paperclip skills must be directories.");
+  }
+  const result = {
+    copiedFiles: 0,
+    skippedSymlinks: []
+  };
+  const lockDir = `${targetRoot}.lock`;
+  const releaseLock = await acquireMaterializeLock(lockDir);
+  const tempRoot = `${targetRoot}.tmp-${process.pid}-${randomUUID2()}`;
+  async function copyEntry(sourcePath, targetPath, relativePath) {
+    const stat = await fs3.lstat(sourcePath);
+    if (stat.isSymbolicLink()) {
+      result.skippedSymlinks.push(relativePath || ".");
+      return;
+    }
+    if (stat.isDirectory()) {
+      await fs3.mkdir(targetPath, { recursive: true });
+      const entries = await fs3.readdir(sourcePath, { withFileTypes: true });
+      entries.sort((left, right) => left.name.localeCompare(right.name));
+      for (const entry of entries) {
+        const childRelativePath = relativePath ? `${relativePath}/${entry.name}` : entry.name;
+        await copyEntry(path3.join(sourcePath, entry.name), path3.join(targetPath, entry.name), childRelativePath);
+      }
+      return;
+    }
+    if (stat.isFile()) {
+      await fs3.mkdir(path3.dirname(targetPath), { recursive: true });
+      await fs3.copyFile(sourcePath, targetPath, fsConstants3.COPYFILE_FICLONE).catch(async () => {
+        await fs3.copyFile(sourcePath, targetPath);
+      });
+      await fs3.chmod(targetPath, stat.mode).catch(() => {
+      });
+      result.copiedFiles += 1;
+    }
+  }
+  try {
+    const sourceFingerprint = await hashSkillDirectory(sourceRoot);
+    if (await materializedSkillFingerprintMatches(targetRoot, sourceFingerprint)) return result;
+    await copyEntry(sourceRoot, tempRoot, "");
+    await fs3.writeFile(
+      path3.join(tempRoot, MATERIALIZED_SKILL_SENTINEL),
+      `${JSON.stringify({
+        version: 1,
+        sourceFingerprint,
+        copiedFiles: result.copiedFiles,
+        skippedSymlinks: result.skippedSymlinks
+      }, null, 2)}
+`,
+      "utf8"
+    );
+    if (await materializedSkillFingerprintMatches(targetRoot, sourceFingerprint)) return result;
+    await fs3.rm(targetRoot, { recursive: true, force: true });
+    await fs3.rename(tempRoot, targetRoot);
+    return result;
+  } finally {
+    await fs3.rm(tempRoot, { recursive: true, force: true }).catch(() => {
+    });
+    await releaseLock();
+  }
+}
+async function removeMaintainerOnlySkillSymlinks(skillsHome, allowedSkillNames) {
+  const allowed = new Set(Array.from(allowedSkillNames));
+  try {
+    const entries = await fs3.readdir(skillsHome, { withFileTypes: true });
+    const removed = [];
+    for (const entry of entries) {
+      if (allowed.has(entry.name)) continue;
+      const target = path3.join(skillsHome, entry.name);
+      const existing = await fs3.lstat(target).catch(() => null);
+      if (!existing?.isSymbolicLink()) continue;
+      const linkedPath = await fs3.readlink(target).catch(() => null);
+      if (!linkedPath) continue;
+      const resolvedLinkedPath = path3.isAbsolute(linkedPath) ? linkedPath : path3.resolve(path3.dirname(target), linkedPath);
+      if (!isMaintainerOnlySkillTarget(linkedPath) && !isMaintainerOnlySkillTarget(resolvedLinkedPath)) {
+        continue;
+      }
+      await fs3.unlink(target);
+      removed.push(entry.name);
+    }
+    return removed;
+  } catch {
+    return [];
+  }
+}
+async function ensureCommandResolvable(command, cwd, env, options = {}) {
+  if (options.remoteExecution) {
+    const resolvedSsh = await resolveCommandPath("ssh", process.cwd(), env);
+    if (resolvedSsh) return;
+    throw new Error('Command not found in PATH: "ssh"');
+  }
+  const resolved = await resolveCommandPath(command, cwd, env);
+  if (resolved) return;
+  if (command.includes("/") || command.includes("\\")) {
+    const absolute = path3.isAbsolute(command) ? command : path3.resolve(cwd, command);
+    throw new Error(`Command is not executable: "${command}" (resolved: "${absolute}")`);
+  }
+  throw new Error(`Command not found in PATH: "${command}"`);
+}
+async function runChildProcess(runId, command, args, opts) {
+  const onLogError = opts.onLogError ?? ((err, id, msg) => console.warn({ err, runId: id }, msg));
+  return new Promise((resolve, reject) => {
+    const rawMerged = {
+      ...sanitizeInheritedPaperclipEnv(process.env),
+      ...opts.env
+    };
+    const CLAUDE_CODE_NESTING_VARS = [
+      "CLAUDECODE",
+      "CLAUDE_CODE_ENTRYPOINT",
+      "CLAUDE_CODE_SESSION",
+      "CLAUDE_CODE_PARENT_SESSION"
+    ];
+    for (const key of CLAUDE_CODE_NESTING_VARS) {
+      delete rawMerged[key];
+    }
+    const mergedEnv = ensurePathInEnv(rawMerged);
+    void resolveSpawnTarget(command, args, opts.cwd, mergedEnv, {
+      remoteExecution: opts.remoteExecution ?? null,
+      remoteEnv: opts.remoteExecution ? opts.env : null
+    }).then((target) => {
+      const child = spawn2(target.command, target.args, {
+        cwd: target.cwd ?? opts.cwd,
+        env: mergedEnv,
+        detached: process.platform !== "win32",
+        shell: false,
+        stdio: [opts.stdin != null ? "pipe" : "ignore", "pipe", "pipe"]
+      });
+      const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+      const processGroupId = resolveProcessGroupId(child);
+      const spawnPersistPromise = typeof child.pid === "number" && child.pid > 0 && opts.onSpawn ? opts.onSpawn({ pid: child.pid, processGroupId, startedAt }).catch((err) => {
+        onLogError(err, runId, "failed to record child process metadata");
+      }) : Promise.resolve();
+      runningProcesses.set(runId, { child, graceSec: opts.graceSec, processGroupId });
+      let timedOut = false;
+      let stdout = "";
+      let stderr = "";
+      let logChain = Promise.resolve();
+      let terminalResultSeen = false;
+      let terminalCleanupStarted = false;
+      let terminalCleanupTimer = null;
+      let terminalCleanupKillTimer = null;
+      let terminalResultStdoutScanOffset = 0;
+      let terminalResultStderrScanOffset = 0;
+      const clearTerminalCleanupTimers = () => {
+        if (terminalCleanupTimer) clearTimeout(terminalCleanupTimer);
+        if (terminalCleanupKillTimer) clearTimeout(terminalCleanupKillTimer);
+        terminalCleanupTimer = null;
+        terminalCleanupKillTimer = null;
+      };
+      const maybeArmTerminalResultCleanup = () => {
+        const terminalCleanup = opts.terminalResultCleanup;
+        if (!terminalCleanup || terminalCleanupStarted || timedOut) return;
+        if (!terminalResultSeen) {
+          const stdoutStart = Math.max(0, terminalResultStdoutScanOffset - TERMINAL_RESULT_SCAN_OVERLAP_CHARS);
+          const stderrStart = Math.max(0, terminalResultStderrScanOffset - TERMINAL_RESULT_SCAN_OVERLAP_CHARS);
+          const scanOutput = {
+            stdout: stdout.slice(stdoutStart),
+            stderr: stderr.slice(stderrStart)
+          };
+          terminalResultStdoutScanOffset = stdout.length;
+          terminalResultStderrScanOffset = stderr.length;
+          if (scanOutput.stdout.length === 0 && scanOutput.stderr.length === 0) return;
+          try {
+            terminalResultSeen = terminalCleanup.hasTerminalResult(scanOutput);
+          } catch (err) {
+            onLogError(err, runId, "failed to inspect terminal adapter output");
+          }
+        }
+        if (!terminalResultSeen) return;
+        if (terminalCleanupTimer) return;
+        const graceMs = Math.max(0, terminalCleanup.graceMs ?? 5e3);
+        terminalCleanupTimer = setTimeout(() => {
+          terminalCleanupTimer = null;
+          if (terminalCleanupStarted || timedOut) return;
+          terminalCleanupStarted = true;
+          signalRunningProcess({ child, processGroupId }, "SIGTERM");
+          terminalCleanupKillTimer = setTimeout(() => {
+            terminalCleanupKillTimer = null;
+            signalRunningProcess({ child, processGroupId }, "SIGKILL");
+          }, Math.max(1, opts.graceSec) * 1e3);
+        }, graceMs);
+      };
+      const timeout = opts.timeoutSec > 0 ? setTimeout(() => {
+        timedOut = true;
+        clearTerminalCleanupTimers();
+        signalRunningProcess({ child, processGroupId }, "SIGTERM");
+        setTimeout(() => {
+          signalRunningProcess({ child, processGroupId }, "SIGKILL");
+        }, Math.max(1, opts.graceSec) * 1e3);
+      }, opts.timeoutSec * 1e3) : null;
+      child.stdout?.on("data", (chunk) => {
+        const readable = child.stdout;
+        if (!readable) return;
+        readable.pause();
+        const text = String(chunk);
+        stdout = appendWithCap(stdout, text);
+        maybeArmTerminalResultCleanup();
+        logChain = logChain.then(() => opts.onLog("stdout", text)).catch((err) => onLogError(err, runId, "failed to append stdout log chunk")).finally(() => {
+          maybeArmTerminalResultCleanup();
+          resumeReadable(readable);
+        });
+      });
+      child.stderr?.on("data", (chunk) => {
+        const readable = child.stderr;
+        if (!readable) return;
+        readable.pause();
+        const text = String(chunk);
+        stderr = appendWithCap(stderr, text);
+        maybeArmTerminalResultCleanup();
+        logChain = logChain.then(() => opts.onLog("stderr", text)).catch((err) => onLogError(err, runId, "failed to append stderr log chunk")).finally(() => {
+          maybeArmTerminalResultCleanup();
+          resumeReadable(readable);
+        });
+      });
+      const stdin = child.stdin;
+      if (opts.stdin != null && stdin) {
+        void spawnPersistPromise.finally(() => {
+          if (child.killed || stdin.destroyed) return;
+          stdin.write(opts.stdin);
+          stdin.end();
+        });
+      }
+      child.on("error", (err) => {
+        if (timeout) clearTimeout(timeout);
+        clearTerminalCleanupTimers();
+        runningProcesses.delete(runId);
+        void target.cleanup?.();
+        const errno = err.code;
+        const pathValue = mergedEnv.PATH ?? mergedEnv.Path ?? "";
+        const msg = errno === "ENOENT" ? `Failed to start command "${command}" in "${opts.cwd}". Verify adapter command, working directory, and PATH (${pathValue}).` : `Failed to start command "${command}" in "${opts.cwd}": ${err.message}`;
+        reject(new Error(msg));
+      });
+      child.on("exit", () => {
+        maybeArmTerminalResultCleanup();
+      });
+      child.on("close", (code, signal) => {
+        if (timeout) clearTimeout(timeout);
+        clearTerminalCleanupTimers();
+        runningProcesses.delete(runId);
+        void logChain.finally(() => {
+          void Promise.resolve().then(() => target.cleanup?.()).finally(() => {
+            resolve({
+              exitCode: code,
+              signal,
+              timedOut,
+              stdout,
+              stderr,
+              pid: child.pid ?? null,
+              startedAt
+            });
+          });
+        });
+      });
+    }).catch(reject);
+  });
+}
+
+export {
+  createRuntimeProgressReporter,
+  shouldExcludePath,
+  captureDirectorySnapshot,
+  mergeDirectoryWithBaseline,
+  createSshCommandManagedRuntimeRunner,
+  shellQuote,
+  parseSshRemoteExecutionSpec,
+  runSshCommand,
+  syncDirectoryToSsh,
+  prepareWorkspaceForSshExecution,
+  restoreWorkspaceFromSshExecution,
+  sanitizeRemoteExecutionEnv,
+  runningProcesses,
+  MAX_CAPTURE_BYTES,
+  MAX_EXCERPT_BYTES,
+  resolvePaperclipInstanceRootForAdapter,
+  DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,
+  WATCHDOG_DEFAULT_MANDATE,
+  parseObject,
+  asString,
+  asNumber,
+  asBoolean,
+  asStringArray,
+  parseJson,
+  appendWithCap,
+  appendWithByteCap,
+  resolvePathValue,
+  renderTemplate,
+  joinPromptSections,
+  normalizePaperclipWakePayload,
+  stringifyPaperclipWakePayload,
+  readPaperclipIssueWorkModeFromContext,
+  renderPaperclipWakePrompt,
+  redactEnvForLogs,
+  redactCommandTextForLogs,
+  buildInvocationEnvForLogs,
+  buildPaperclipEnv,
+  applyPaperclipWorkspaceEnv,
+  shapePaperclipWorkspaceEnvForExecution,
+  rewriteWorkspaceCwdEnvVarsForExecution,
+  refreshPaperclipWorkspaceEnvForExecution,
+  sanitizeInheritedPaperclipEnv,
+  defaultPathForPlatform,
+  resolveCommandForLogs,
+  sanitizeSshRemoteEnv,
+  ensurePathInEnv,
+  ensureAbsoluteDirectory,
+  resolvePaperclipSkillsDir,
+  listPaperclipSkillEntries,
+  readInstalledSkillTargets,
+  buildRuntimeMountedSkillSnapshot,
+  buildPersistentSkillSnapshot,
+  readPaperclipRuntimeSkillEntries,
+  readPaperclipSkillMarkdown,
+  readPaperclipSkillSyncPreference,
+  resolvePaperclipDesiredSkillNames,
+  writePaperclipSkillSyncPreference,
+  ensurePaperclipSkillSymlink,
+  materializePaperclipSkillCopy,
+  removeMaintainerOnlySkillSymlinks,
+  ensureCommandResolvable,
+  runChildProcess
+};