@rallycry/conveyor-agent 10.0.0 → 10.0.2

package/dist/{chunk-34NA4BCK.js → chunk-QKRPJ7DB.js}

@@ -116,6 +116,44 @@ function applyBootstrapToEnv(config) {
 
 // src/connection/agent-connection.ts
 import { io } from "socket.io-client";
+
+// src/setup/bootstrap-poll.ts
+var PollUntilBoundHttpError = class extends Error {
+  constructor(status) {
+    super(`pollUntilBound got unexpected status ${status}`);
+    this.status = status;
+    this.name = "PollUntilBoundHttpError";
+  }
+  status;
+};
+async function sleep2(ms) {
+  await new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+async function pollUntilBound(opts) {
+  const pollIntervalMs = opts.pollIntervalMs ?? 2e3;
+  const maxWaitMs = opts.maxWaitMs ?? 30 * 60 * 1e3;
+  const deadline = Date.now() + maxWaitMs;
+  while (true) {
+    const response = await fetch(`${opts.apiUrl}/api/v3/pods/bootstrap`, {
+      headers: { Authorization: `Bearer ${opts.bootstrapToken}` }
+    });
+    if (response.status === 200) {
+      return await response.json();
+    }
+    if (response.status === 204) {
+      if (Date.now() >= deadline) {
+        throw new Error(`pollUntilBound timed out after ${maxWaitMs}ms waiting for pod bind`);
+      }
+      await sleep2(pollIntervalMs);
+      continue;
+    }
+    throw new PollUntilBoundHttpError(response.status);
+  }
+}
+
+// src/connection/agent-connection.ts
 var EVENT_BATCH_MS = 500;
 var MAX_EVENT_BUFFER = 5e3;
 var TOKEN_REFRESH_INTERVAL_MS = 6 * 60 * 60 * 1e3;
@@ -147,6 +185,7 @@ var AgentConnection = class _AgentConnection {
   modeChangeCallback = null;
   apiKeyUpdateCallback = null;
   pullBranchCallback = null;
+  finalizeSnapshotCallback = null;
   earlyPullBranches = [];
   // PTY relay (S5 terminal). Single-slot callbacks, set per PtySession run.
   ptyInputCallback = null;
@@ -301,6 +340,9 @@ var AgentConnection = class _AgentConnection {
         if (this.pullBranchCallback) this.pullBranchCallback(data);
         else this.earlyPullBranches.push(data);
       });
+      this.socket.on("session:finalizeSnapshot", () => {
+        this.finalizeSnapshotCallback?.();
+      });
       this.socket.on("pty:input", (data) => {
         if (data.sessionId && data.sessionId !== this.config.sessionId) return;
         this.ptyInputCallback?.(data.data);
@@ -523,6 +565,9 @@ var AgentConnection = class _AgentConnection {
     for (const data of this.earlyPullBranches) callback(data);
     this.earlyPullBranches = [];
   }
+  onFinalizeSnapshot(callback) {
+    this.finalizeSnapshotCallback = callback;
+  }
   // ── PTY relay (S5 Connected-TUI terminal) ──────────────────────────
   /**
    * Forward a raw chunk of terminal output to the S2 relay (fire-and-forget).
@@ -671,6 +716,12 @@ var AgentConnection = class _AgentConnection {
       }
     );
   }
+  /** Report the full current set of runtime-discovered listening ports.
+   *  Throws on failure so the PortDiscovery poller can retry on its next
+   *  tick (a swallowed error here would silently drop the delta). */
+  async reportDiscoveredPorts(ports) {
+    await this.call("reportDiscoveredPorts", { sessionId: this.config.sessionId, ports });
+  }
   // ── Typing indicators ───────────────────────────────────────────────
   sendTypingStart() {
     this.sendEvent({ type: "agent_typing_start" });
@@ -738,15 +789,27 @@ ${q.question}${q.options.length ? "\n" + q.options.map((o) => `- ${o.label}: ${o
     const result = await this.refreshFromBootstrap();
     return result.refreshedTaskToken;
   }
-  async refreshFromBootstrap() {
+  refreshFromBootstrap() {
+    const none = Promise.resolve({ refreshedClaude: false, refreshedTaskToken: false });
+    const podBootstrapToken = process.env.POD_BOOTSTRAP_TOKEN;
     const codespaceName = process.env.CODESPACE_NAME || process.env.CLAUDESPACE_NAME;
     const apiUrl = this.config.apiUrl;
-    if (!codespaceName || !apiUrl) return { refreshedClaude: false, refreshedTaskToken: false };
+    if (!apiUrl || !podBootstrapToken && !codespaceName) {
+      return none;
+    }
     const now = Date.now();
     if (now - this.lastTaskTokenRefreshAt < 6e4) {
-      return { refreshedClaude: false, refreshedTaskToken: false };
+      return none;
     }
     this.lastTaskTokenRefreshAt = now;
+    if (podBootstrapToken) {
+      return this.refreshFromV3Bootstrap(apiUrl, podBootstrapToken);
+    }
+    if (!codespaceName) return none;
+    return this.refreshFromCodespaceBootstrap(apiUrl, codespaceName);
+  }
+  /** Legacy GitHub Codespaces refresh path — keys on instance name. */
+  async refreshFromCodespaceBootstrap(apiUrl, codespaceName) {
     const bootstrapToken = process.env.CONVEYOR_BOOTSTRAP_TOKEN;
     const result = await fetchBootstrap({
       apiUrl,
@@ -772,6 +835,61 @@ ${q.question}${q.options.length ? "\n" + q.options.map((o) => `- ${o.label}: ${o
     const refreshedClaude = Boolean(result.config.envVars?.CLAUDE_CODE_OAUTH_TOKEN);
     return { refreshedClaude, refreshedTaskToken };
   }
+  /**
+   * v3 refresh: re-fetch the full bootstrap bundle from the pod's bound v3
+   * route and swap the credentials in place. The GitHub installation token
+   * dies at ~1h and the sessionJwt at 24h; re-polling the bootstrap GET with
+   * the same pod token is the designed refresh mechanism.
+   */
+  async refreshFromV3Bootstrap(apiUrl, bootstrapToken) {
+    const bundle = await this.pollBundleWithRateLimitRetry(apiUrl, bootstrapToken);
+    if (!bundle) {
+      return { refreshedClaude: false, refreshedTaskToken: false };
+    }
+    const previousTaskToken = process.env.CONVEYOR_TASK_TOKEN;
+    for (const [key, value] of Object.entries(bundle.envVars ?? {})) {
+      process.env[key] = value;
+    }
+    if (bundle.githubToken) process.env.CONVEYOR_GITHUB_TOKEN = bundle.githubToken;
+    if (bundle.anthropicKey) process.env.ANTHROPIC_API_KEY = bundle.anthropicKey;
+    if (bundle.gcpToken) process.env.CLOUDSDK_AUTH_ACCESS_TOKEN = bundle.gcpToken;
+    const refreshedTaskToken = Boolean(bundle.sessionJwt) && bundle.sessionJwt !== previousTaskToken;
+    if (refreshedTaskToken) {
+      process.env.CONVEYOR_TASK_TOKEN = bundle.sessionJwt;
+      this.config.taskToken = bundle.sessionJwt;
+      if (this.socket) {
+        const auth = this.socket.auth;
+        if (auth && typeof auth === "object") {
+          auth.taskToken = bundle.sessionJwt;
+        }
+      }
+    }
+    const refreshedClaude = Boolean(bundle.envVars?.CLAUDE_CODE_OAUTH_TOKEN);
+    return { refreshedClaude, refreshedTaskToken };
+  }
+  /**
+   * Poll the bootstrap bundle once (maxWaitMs 0), retrying only on a transient
+   * 429 (standby-pool pods share one Cloud NAT IP against podBootstrapLimiter)
+   * with a short backoff. Returns null when the refresh should be abandoned —
+   * a non-429 error, or 429s past the retry budget — so the caller no-ops
+   * instead of parking a RUNNING pod in a poll loop.
+   */
+  async pollBundleWithRateLimitRetry(apiUrl, bootstrapToken) {
+    const retryDelaysMs = [1e3, 3e3];
+    for (let attempt = 0; ; attempt++) {
+      try {
+        return await pollUntilBound({ apiUrl, bootstrapToken, maxWaitMs: 0 });
+      } catch (err) {
+        const isRateLimited = err instanceof PollUntilBoundHttpError && err.status === 429;
+        if (!isRateLimited || attempt >= retryDelaysMs.length) {
+          return null;
+        }
+        await new Promise((resolve) => {
+          setTimeout(resolve, retryDelaysMs[attempt]);
+        });
+      }
+    }
+  }
   // ── Event buffering ────────────────────────────────────────────────
   sendEvent(event) {
     if (!this.socket) return;
@@ -1356,6 +1474,13 @@ function preToolUse(payload) {
     );
     process.exit(0);
   };
+  // MCP tools are auto-allowed locally \u2014 no socket round trip, no fail-mode.
+  // Plan mode prompts for them despite permissions.allow (the CLI can't
+  // classify MCP tools as read-only), and the pod is the sandbox.
+  if (typeof payload.tool_name === "string" && payload.tool_name.startsWith("mcp__")) {
+    respond("allow");
+    return;
+  }
   // AskUserQuestion is observe-only (status reporting) \u2014 fail OPEN so a
   // missing/slow socket never denies the questionnaire. Everything else
   // (ExitPlanMode) is a Conveyor gate \u2014 fail CLOSED.
@@ -1459,6 +1584,15 @@ async function writeHookSettings(dir) {
           // tool, so the questionnaire is never blocked by Conveyor.
           matcher: "AskUserQuestion",
           hooks: [{ type: "command", command: `node ${JSON.stringify(helperPath)}`, timeout: 30 }]
+        },
+        {
+          // Plan-permission spawns prompt for MCP tools even when they're in
+          // permissions.allow — the CLI can't classify them as read-only. A
+          // hook allow bypasses the permission engine in every mode. Loose by
+          // design: the pod is the sandbox, and planning agents must call
+          // update_task etc. The helper answers locally (no socket).
+          matcher: "mcp__.*",
+          hooks: [{ type: "command", command: `node ${JSON.stringify(helperPath)}`, timeout: 30 }]
         }
       ],
       PostToolUse: [
@@ -1497,8 +1631,8 @@ var PlanSync = class {
         for (const file of readdirSync(plansDir).filter((f) => f.endsWith(".md"))) {
           try {
             const fullPath = join2(plansDir, file);
-            const stat4 = statSync(fullPath);
-            this.planFileSnapshot.set(fullPath, stat4.mtimeMs);
+            const stat6 = statSync(fullPath);
+            this.planFileSnapshot.set(fullPath, stat6.mtimeMs);
           } catch {
             continue;
           }
@@ -1519,11 +1653,11 @@ var PlanSync = class {
       for (const file of files) {
         const fullPath = join2(plansDir, file);
         try {
-          const stat4 = statSync(fullPath);
+          const stat6 = statSync(fullPath);
           const prevMtime = this.planFileSnapshot.get(fullPath);
-          const isNew = prevMtime === void 0 || stat4.mtimeMs > prevMtime;
-          if (isNew && (!newest || stat4.mtimeMs > newest.mtime)) {
-            newest = { path: fullPath, mtime: stat4.mtimeMs };
+          const isNew = prevMtime === void 0 || stat6.mtimeMs > prevMtime;
+          if (isNew && (!newest || stat6.mtimeMs > newest.mtime)) {
+            newest = { path: fullPath, mtime: stat6.mtimeMs };
           }
         } catch {
           continue;
@@ -1564,6 +1698,511 @@ var PlanSync = class {
   }
 };
 
+// src/setup/git-ready.ts
+import { access, stat } from "fs/promises";
+var DEFAULT_FAILED_PATH = "/workspaces/.conveyor-git-failed";
+var DEFAULT_TIMEOUT_MS = 6e5;
+var DEFAULT_POLL_MS = 200;
+async function fileExists(path4) {
+  try {
+    await access(path4);
+    const s = await stat(path4);
+    return s.isFile();
+  } catch {
+    return false;
+  }
+}
+function awaitGitReady(opts = {}) {
+  const markerPath = opts.markerPath ?? process.env.CONVEYOR_GIT_READY_MARKER;
+  if (!markerPath) {
+    return Promise.resolve("not-gated");
+  }
+  const failedPath = opts.failedPath ?? process.env.CONVEYOR_GIT_FAILED_MARKER ?? DEFAULT_FAILED_PATH;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const pollMs = opts.pollMs ?? DEFAULT_POLL_MS;
+  opts.onLog?.(`waiting for workspace git (marker=${markerPath})`);
+  return pollForMarkers(markerPath, failedPath, timeoutMs, pollMs, opts.onLog);
+}
+async function pollForMarkers(markerPath, failedPath, timeoutMs, pollMs, onLog) {
+  const deadline = Date.now() + timeoutMs;
+  for (; ; ) {
+    if (await fileExists(markerPath)) {
+      onLog?.("workspace git ready");
+      return "ready";
+    }
+    if (await fileExists(failedPath)) {
+      onLog?.("workspace git preparation failed (marker present)");
+      return "failed";
+    }
+    if (Date.now() >= deadline) {
+      onLog?.(`workspace git not ready after ${timeoutMs}ms \u2014 giving up`);
+      return "timeout";
+    }
+    await new Promise((resolve) => {
+      setTimeout(resolve, pollMs);
+    });
+  }
+}
+
+// src/runner/work-preservation/index.ts
+import { rm as rm3 } from "fs/promises";
+
+// src/runner/work-preservation/pg-dump.ts
+import { execSync as execSync2 } from "child_process";
+import { randomUUID } from "crypto";
+import { tmpdir } from "os";
+import path from "path";
+var PG_DUMP_FILENAME = ".conveyor-pgdump.sql";
+function connectionDefaults(opts) {
+  return {
+    host: opts.host ?? "localhost",
+    port: opts.port ?? 5432,
+    db: opts.db ?? "conveyor"
+  };
+}
+function buildPgDumpCommand(opts) {
+  const { host, port, db } = connectionDefaults(opts);
+  return `pg_dump -h ${host} -p ${port} -U postgres ${db} -f ${JSON.stringify(
+    opts.outputPath
+  )} --no-owner --no-privileges`;
+}
+function buildPsqlRestoreCommand(opts) {
+  const { host, port, db } = connectionDefaults(opts);
+  return `psql -h ${host} -p ${port} -U postgres -d ${db} -f ${JSON.stringify(opts.dumpPath)}`;
+}
+function hasPostgresDep() {
+  return (process.env.CONVEYOR_DEPS ?? "").split(",").map((dep) => dep.trim()).includes("postgresql");
+}
+function execErrorDetail(err) {
+  const withStreams = err;
+  const stderr = withStreams.stderr instanceof Buffer ? withStreams.stderr.toString("utf8").trim() : typeof withStreams.stderr === "string" ? withStreams.stderr.trim() : "";
+  const message = withStreams.message ?? String(err);
+  return stderr ? `${message} \u2014 stderr: ${stderr}` : message;
+}
+function dumpPostgresIfPresent(exec = execSync2) {
+  if (!hasPostgresDep()) return Promise.resolve({ dumped: false });
+  const outputPath = path.join(tmpdir(), `conveyor-pgdump-${randomUUID()}.sql`);
+  try {
+    exec(buildPgDumpCommand({ outputPath }), {
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 6e4
+    });
+    return Promise.resolve({ dumped: true, path: outputPath });
+  } catch (err) {
+    process.stderr.write(`[conveyor-agent] pg_dump failed: ${execErrorDetail(err)}
+`);
+    return Promise.resolve({ dumped: false });
+  }
+}
+function applyPgDumpIfConfigured(dumpPath, exec = execSync2) {
+  if (!hasPostgresDep()) return false;
+  try {
+    exec(buildPsqlRestoreCommand({ dumpPath }), {
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 12e4
+    });
+    process.stderr.write("[conveyor-agent] Restored postgres state from snapshot pg dump\n");
+    return true;
+  } catch (err) {
+    process.stderr.write(`[conveyor-agent] psql dump restore failed: ${execErrorDetail(err)}
+`);
+    return false;
+  }
+}
+
+// src/runner/work-preservation/restore-precedence.ts
+function selectRestoreSource(probe) {
+  if (probe.gcsAvailable) return "gcs";
+  if (probe.wipRestoreResult === "applied") return "wip";
+  return "clean";
+}
+
+// src/runner/work-preservation/snapshot-tar.ts
+import { execSync as execSync3 } from "child_process";
+import { createReadStream, createWriteStream, mkdtempSync } from "fs";
+import { copyFile, mkdtemp, rm, stat as stat2, writeFile as writeFile2 } from "fs/promises";
+import { tmpdir as tmpdir2 } from "os";
+import path2 from "path";
+import { pipeline } from "stream/promises";
+import { createGzip } from "zlib";
+import * as tar from "tar";
+
+// src/runner/work-preservation/snapshot-artifact.ts
+function planSnapshotFiles(git) {
+  const include = git.trackedAndUntracked();
+  const includeSet = new Set(include);
+  const deletions = [...new Set(git.deletedSinceHead())].filter((path4) => !includeSet.has(path4));
+  return { include, deletions };
+}
+
+// src/runner/work-preservation/snapshot-tar.ts
+var SNAPSHOT_MANIFEST_NAME = ".conveyor-snapshot-manifest.json";
+var STATUS_MAX_BUFFER = 64 * 1024 * 1024;
+function parseStatusPorcelainZ(raw) {
+  const includes = [];
+  const deletions = [];
+  const tokens = raw.split("\0");
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (!token || token.length < 4) continue;
+    const x = token[0];
+    const y = token[1];
+    const filePath = token.slice(3);
+    if (x === "R" || x === "C") {
+      const origPath = tokens[++i];
+      if (x === "R" && origPath) deletions.push(origPath);
+    }
+    if (x === "!") continue;
+    const missingFromWorktree = y === "D" || x === "D" && y === " ";
+    if (missingFromWorktree) deletions.push(filePath);
+    else includes.push(filePath);
+  }
+  return { includes, deletions };
+}
+function realGitSurface(cwd) {
+  let cached = null;
+  const load = () => {
+    if (!cached) {
+      const out = execSync3("git status --porcelain=v1 -z -uall", {
+        cwd,
+        stdio: ["ignore", "pipe", "ignore"],
+        maxBuffer: STATUS_MAX_BUFFER
+      }).toString("utf8");
+      cached = parseStatusPorcelainZ(out);
+    }
+    return cached;
+  };
+  return {
+    trackedAndUntracked: () => load().includes,
+    deletedSinceHead: () => load().deletions
+  };
+}
+function gitHead(cwd) {
+  try {
+    return execSync3("git rev-parse HEAD", { cwd, stdio: ["ignore", "pipe", "ignore"] }).toString().trim() || null;
+  } catch {
+    return null;
+  }
+}
+async function buildSnapshotTar(cwd, opts) {
+  const staging = await mkdtemp(path2.join(tmpdir2(), "conveyor-snapshot-"));
+  const cleanup = async () => {
+    await rm(staging, { recursive: true, force: true }).catch(() => {
+    });
+  };
+  try {
+    const plan = planSnapshotFiles(realGitSurface(cwd));
+    const head = gitHead(cwd);
+    if (!head) throw new Error("cannot snapshot a repo without a resolvable HEAD");
+    const capturedAt = Date.now();
+    const manifest = {
+      head,
+      deletions: plan.deletions,
+      capturedAt,
+      pgDump: Boolean(opts?.pgDumpPath)
+    };
+    await writeFile2(path2.join(staging, SNAPSHOT_MANIFEST_NAME), JSON.stringify(manifest), "utf8");
+    const stagedEntries = [SNAPSHOT_MANIFEST_NAME];
+    if (opts?.pgDumpPath) {
+      await copyFile(opts.pgDumpPath, path2.join(staging, PG_DUMP_FILENAME));
+      stagedEntries.push(PG_DUMP_FILENAME);
+    }
+    const rawTarPath = path2.join(staging, "snapshot.tar");
+    await tar.create({ cwd: staging, file: rawTarPath, portable: true }, stagedEntries);
+    if (plan.include.length > 0) {
+      await tar.replace({ file: rawTarPath, cwd, portable: true }, plan.include);
+    }
+    const tarPath = path2.join(staging, "snapshot.tar.gz");
+    await pipeline(createReadStream(rawTarPath), createGzip(), createWriteStream(tarPath));
+    await rm(rawTarPath, { force: true });
+    const { size } = await stat2(tarPath);
+    return {
+      tarPath,
+      sizeBytes: size,
+      fileCount: plan.include.length,
+      deletionCount: plan.deletions.length,
+      capturedAt,
+      cleanup
+    };
+  } catch (err) {
+    await cleanup();
+    throw err;
+  }
+}
+function isWithinWorkspace(cwd, rel) {
+  if (!rel || path2.isAbsolute(rel)) return false;
+  const root = path2.resolve(cwd);
+  const abs = path2.resolve(root, rel);
+  return abs !== root && abs.startsWith(root + path2.sep);
+}
+async function readSnapshotArchive(tarPath) {
+  let manifestRaw = null;
+  let pgDumpDir = null;
+  let pgDumpPath;
+  let pgDumpWritten = Promise.resolve();
+  const cleanup = async () => {
+    if (pgDumpDir) await rm(pgDumpDir, { recursive: true, force: true }).catch(() => {
+    });
+  };
+  try {
+    await tar.list({
+      file: tarPath,
+      onReadEntry: (entry) => {
+        if (entry.path === SNAPSHOT_MANIFEST_NAME) {
+          const chunks = [];
+          entry.on("data", (chunk) => chunks.push(chunk));
+          entry.on("end", () => {
+            manifestRaw = Buffer.concat(chunks);
+          });
+        } else if (entry.path === PG_DUMP_FILENAME) {
+          pgDumpDir = mkdtempSync(path2.join(tmpdir2(), "conveyor-pgdump-restore-"));
+          pgDumpPath = path2.join(pgDumpDir, "dump.sql");
+          const dest = createWriteStream(pgDumpPath);
+          pgDumpWritten = new Promise((resolve, reject) => {
+            dest.on("finish", () => resolve());
+            dest.on("error", reject);
+          });
+          entry.pipe(dest);
+        }
+      }
+    });
+    await pgDumpWritten;
+  } catch {
+    await cleanup();
+    return null;
+  }
+  if (!manifestRaw) {
+    await cleanup();
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(manifestRaw.toString("utf8"));
+    if (typeof parsed.head !== "string" || !parsed.head) {
+      await cleanup();
+      return null;
+    }
+    return {
+      manifest: {
+        head: parsed.head,
+        deletions: Array.isArray(parsed.deletions) ? parsed.deletions : [],
+        capturedAt: typeof parsed.capturedAt === "number" ? parsed.capturedAt : 0,
+        pgDump: parsed.pgDump === true
+      },
+      ...pgDumpPath ? { pgDumpPath } : {},
+      cleanup
+    };
+  } catch {
+    await cleanup();
+    return null;
+  }
+}
+async function extractSnapshotTar(cwd, tarPath, opts) {
+  const read = await readSnapshotArchive(tarPath);
+  if (!read) return { status: "invalid" };
+  try {
+    const { manifest, pgDumpPath } = read;
+    const currentHead = gitHead(cwd);
+    if (manifest.head !== currentHead) {
+      return { status: "stale-head", snapshotHead: manifest.head, currentHead };
+    }
+    let filesExtracted = 0;
+    await tar.extract({
+      file: tarPath,
+      cwd,
+      filter: (entryPath) => {
+        if (entryPath === SNAPSHOT_MANIFEST_NAME || entryPath === PG_DUMP_FILENAME) return false;
+        filesExtracted++;
+        return true;
+      }
+    });
+    let deletionsApplied = 0;
+    for (const rel of manifest.deletions) {
+      if (typeof rel !== "string" || !isWithinWorkspace(cwd, rel)) continue;
+      await rm(path2.resolve(cwd, rel), { recursive: true, force: true });
+      deletionsApplied++;
+    }
+    const pgDumpApplied = manifest.pgDump && pgDumpPath ? applyPgDumpIfConfigured(pgDumpPath, opts?.pgExec) : false;
+    return { status: "extracted", filesExtracted, deletionsApplied, pgDumpApplied };
+  } finally {
+    await read.cleanup();
+  }
+}
+
+// src/runner/work-preservation/snapshot-transfer.ts
+import { randomUUID as randomUUID2 } from "crypto";
+import { createReadStream as createReadStream2, createWriteStream as createWriteStream2 } from "fs";
+import { rm as rm2 } from "fs/promises";
+import { tmpdir as tmpdir3 } from "os";
+import path3 from "path";
+import { Readable } from "stream";
+import { pipeline as pipeline2 } from "stream/promises";
+var SNAPSHOT_HTTP_TIMEOUT_MS = 6e4;
+var SNAPSHOT_CAPTURED_AT_HEADER = "x-snapshot-captured-at";
+async function putSnapshotToGcs(url, tarResult) {
+  try {
+    const body = Readable.toWeb(createReadStream2(tarResult.tarPath));
+    const res = await fetch(url, {
+      method: "PUT",
+      headers: {
+        "Content-Type": "application/gzip",
+        "Content-Length": String(tarResult.sizeBytes),
+        [SNAPSHOT_CAPTURED_AT_HEADER]: String(tarResult.capturedAt)
+      },
+      body,
+      duplex: "half",
+      signal: AbortSignal.timeout(SNAPSHOT_HTTP_TIMEOUT_MS)
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+async function downloadSnapshotToTemp(url) {
+  const tmpTar = path3.join(tmpdir3(), `conveyor-snapshot-restore-${randomUUID2()}.tar.gz`);
+  try {
+    const res = await fetch(url, {
+      method: "GET",
+      signal: AbortSignal.timeout(SNAPSHOT_HTTP_TIMEOUT_MS)
+    });
+    if (!res.ok || !res.body) return null;
+    await pipeline2(
+      Readable.fromWeb(res.body),
+      createWriteStream2(tmpTar)
+    );
+    return tmpTar;
+  } catch {
+    await rm2(tmpTar, { force: true }).catch(() => {
+    });
+    return null;
+  }
+}
+
+// src/runner/work-preservation/index.ts
+var periodicTimer = null;
+var inFlightCapture = null;
+var inFlightGcsUpload = null;
+var EMPTY_GCS_RESULT = {
+  uploaded: false,
+  fileCount: 0,
+  deletionCount: 0,
+  sizeBytes: 0,
+  pgDumped: false
+};
+async function doUploadSnapshotToGcs(cwd, uploadUrl, opts) {
+  let tarResult;
+  try {
+    tarResult = await buildSnapshotTar(cwd, { pgDumpPath: opts?.pgDumpPath });
+  } catch {
+    return EMPTY_GCS_RESULT;
+  }
+  try {
+    const uploaded = (opts?.forceUpload || tarResult.sizeBytes > 0) && uploadUrl ? await putSnapshotToGcs(uploadUrl, tarResult) : false;
+    return {
+      uploaded,
+      fileCount: tarResult.fileCount,
+      deletionCount: tarResult.deletionCount,
+      sizeBytes: tarResult.sizeBytes,
+      pgDumped: Boolean(opts?.pgDumpPath)
+    };
+  } finally {
+    await tarResult.cleanup();
+  }
+}
+async function uploadSnapshotToGcs(cwd, uploadUrl, opts) {
+  const previous = inFlightGcsUpload;
+  const run = (async () => {
+    if (previous) await previous.catch(() => {
+    });
+    return doUploadSnapshotToGcs(cwd, uploadUrl, opts);
+  })();
+  inFlightGcsUpload = run;
+  try {
+    return await run;
+  } finally {
+    if (inFlightGcsUpload === run) inFlightGcsUpload = null;
+  }
+}
+async function captureSnapshot(ctx) {
+  const gcs = await uploadSnapshotToGcs(ctx.cwd, ctx.snapshotUploadUrl, {
+    pgDumpPath: ctx.pgDumpPath,
+    forceUpload: ctx.forceUpload
+  });
+  const wipResult = await flushPendingChanges(ctx.cwd, {
+    wipMessage: ctx.wipMessage ?? "WIP: WorkPreservation periodic snapshot",
+    refreshToken: ctx.refreshToken
+  });
+  return {
+    fileCount: gcs.fileCount,
+    deletionCount: gcs.deletionCount,
+    sizeBytes: gcs.sizeBytes,
+    gcsUploaded: gcs.uploaded,
+    wipPushed: wipResult.committed || wipResult.pushed,
+    pgDumped: gcs.pgDumped
+  };
+}
+function startPeriodic(intervalMs, ctx) {
+  stop();
+  periodicTimer = setInterval(() => {
+    if (inFlightCapture) return;
+    const run = captureSnapshot(ctx);
+    inFlightCapture = run;
+    void run.catch(() => {
+    }).finally(() => {
+      if (inFlightCapture === run) inFlightCapture = null;
+    });
+  }, intervalMs);
+}
+function stop() {
+  if (periodicTimer) {
+    clearInterval(periodicTimer);
+    periodicTimer = null;
+  }
+}
+async function finalizeForSleep(ctx) {
+  stop();
+  if (inFlightCapture) await inFlightCapture.catch(() => {
+  });
+  const dump = await dumpPostgresIfPresent();
+  try {
+    const artifact = await captureSnapshot({
+      ...ctx,
+      pgDumpPath: dump.path,
+      wipMessage: ctx.wipMessage ?? "WIP: WorkPreservation sleep finalize snapshot",
+      // Always stamp snapshotAt on sleep — even an empty workspace must confirm
+      // the finalize so teardown doesn't wait out the reconciler's cap.
+      forceUpload: true
+    });
+    return { ...artifact, pgDumped: dump.dumped };
+  } finally {
+    if (dump.path) await rm3(dump.path, { force: true }).catch(() => {
+    });
+  }
+}
+async function restoreOnBoot(bundle, cwd) {
+  let gcsAvailable = false;
+  let gcsFileCount;
+  if (bundle.snapshotUrl) {
+    const tmpTar = await downloadSnapshotToTemp(bundle.snapshotUrl);
+    if (tmpTar) {
+      try {
+        const result = await extractSnapshotTar(cwd, tmpTar);
+        if (result.status === "extracted") {
+          gcsAvailable = true;
+          gcsFileCount = result.filesExtracted;
+        }
+      } catch {
+        gcsAvailable = false;
+      } finally {
+        await rm3(tmpTar, { force: true }).catch(() => {
+        });
+      }
+    }
+  }
+  const wipRestoreResult = gcsAvailable ? "none" : restoreWipSnapshot(cwd, bundle.gitPlan.branch);
+  const source = selectRestoreSource({ gcsAvailable, wipRestoreResult });
+  return source === "gcs" ? { source, fileCount: gcsFileCount } : { source };
+}
+
 // ../shared/dist/index.js
 import { z } from "zod";
 import { z as z2 } from "zod";
@@ -1704,6 +2343,16 @@ var NotifyAgentVersionRequestSchema = z.object({
   sessionId: z.string(),
   agentVersion: z.string()
 });
+var DiscoveredPortSchema = z.object({
+  port: z.number().int().min(1).max(65535),
+  label: z.string().min(1).max(64).optional(),
+  protocol: z.enum(["http", "tcp"]).optional(),
+  detectedAt: z.string()
+});
+var ReportDiscoveredPortsRequestSchema = z.object({
+  sessionId: z.string(),
+  ports: z.array(DiscoveredPortSchema).max(64)
+});
 var CreateSubtaskRequestSchema = z.object({
   sessionId: z.string(),
   title: z.string().min(1),
@@ -2037,6 +2686,15 @@ var StopProjectBuildRequestSchema = z2.object({
   taskId: z2.string(),
   requestingUserId: z2.string().optional()
 });
+var StartProjectWorkspaceRequestSchema = z2.object({
+  projectId: z2.string(),
+  requestingUserId: z2.string().optional()
+});
+var StopProjectWorkspaceRequestSchema = z2.object({
+  projectId: z2.string(),
+  destroy: z2.boolean().optional(),
+  requestingUserId: z2.string().optional()
+});
 var CreateProjectReleaseRequestSchema = z2.object({
   projectId: z2.string(),
   taskIds: z2.array(z2.string()).optional(),
@@ -2513,8 +3171,8 @@ var ClaudeCodeHarness = class {
 };
 
 // src/harness/pty/session.ts
-import { mkdtemp, mkdir as mkdir2, rm, stat } from "fs/promises";
-import { tmpdir } from "os";
+import { mkdtemp as mkdtemp2, mkdir as mkdir2, rm as rm4, stat as stat3 } from "fs/promises";
+import { tmpdir as tmpdir4 } from "os";
 import { join as join4, dirname } from "path";
 
 // src/harness/pty/event-queue.ts
@@ -2783,8 +3441,8 @@ function mapTranscriptRecord(raw) {
 // src/harness/pty/jsonl-tailer.ts
 var POLL_INTERVAL_MS = 25;
 var JsonlTailer = class {
-  constructor(path, onEvent) {
-    this.path = path;
+  constructor(path4, onEvent) {
+    this.path = path4;
     this.onEvent = onEvent;
   }
   path;
@@ -2981,7 +3639,7 @@ var PtyOutputCoalescer = class {
 
 // src/harness/pty/tool-server.ts
 import { createServer as createServer2 } from "http";
-import { writeFile as writeFile2 } from "fs/promises";
+import { writeFile as writeFile3 } from "fs/promises";
 import { join as join3 } from "path";
 import { randomBytes } from "crypto";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -3088,7 +3746,7 @@ async function startToolServers(mcpServers, tempDir) {
   }
   if (Object.keys(config).length === 0) return { servers, mcpConfigPath: null };
   const mcpConfigPath = join3(tempDir, "mcp-config.json");
-  await writeFile2(mcpConfigPath, JSON.stringify({ mcpServers: config }, null, 2), "utf8");
+  await writeFile3(mcpConfigPath, JSON.stringify({ mcpServers: config }, null, 2), "utf8");
   return { servers, mcpConfigPath };
 }
 
@@ -3126,14 +3784,14 @@ var SUBMIT_NUDGE_INTERVAL_MS = 2e3;
 var SUBMIT_NUDGE_MAX_PRESSES = 5;
 var SUBMIT_NUDGE_SLOW_INTERVAL_MS = 5e3;
 var SUBMIT_NUDGE_WINDOW_MS = 9e4;
-function sleep2(ms) {
+function sleep3(ms) {
   return new Promise((resolve) => {
     setTimeout(resolve, ms);
   });
 }
-async function transcriptSize(path) {
+async function transcriptSize(path4) {
   try {
-    return (await stat(path)).size;
+    return (await stat3(path4)).size;
   } catch {
     return 0;
   }
@@ -3223,7 +3881,7 @@ var PtySession = class {
       return;
     }
     try {
-      this.tempDir = await mkdtemp(join4(tmpdir(), "conveyor-pty-"));
+      this.tempDir = await mkdtemp2(join4(tmpdir4(), "conveyor-pty-"));
       const socketPath = join4(this.tempDir, "hook.sock");
       this.socket = new HookSocketServer(
         socketPath,
@@ -3323,7 +3981,7 @@ var PtySession = class {
     this.mcpConfigPath = null;
     this.queue.close();
     if (this.tempDir) {
-      await rm(this.tempDir, { recursive: true, force: true });
+      await rm4(this.tempDir, { recursive: true, force: true });
       this.tempDir = "";
     }
   }
@@ -3383,7 +4041,7 @@ var PtySession = class {
   async deliverPrompt(text) {
     this.writeStdin(buildPromptBytes(text));
     if (this.options.promptDelivery === "prefill") return;
-    await sleep2(SUBMIT_SETTLE_MS);
+    await sleep3(SUBMIT_SETTLE_MS);
     if (this._toreDown) return;
     this.writeStdin("\r");
     this.armSubmitNudge();
@@ -3531,7 +4189,7 @@ var PtySession = class {
 };
 
 // src/harness/pty/credentials.ts
-import { chmod as chmod2, mkdir as mkdir3, readFile, rm as rm2, writeFile as writeFile3 } from "fs/promises";
+import { chmod as chmod2, mkdir as mkdir3, readFile, rm as rm5, writeFile as writeFile4 } from "fs/promises";
 import { homedir as homedir2 } from "os";
 import { join as join5 } from "path";
 var SYNTH_TOKEN_TTL_MS = 365 * 24 * 60 * 60 * 1e3;
@@ -3582,26 +4240,26 @@ function planCredentialsWrite(input) {
   if (fresh) return { action: "skip", reason: "current" };
   return { action: "write", contents };
 }
-async function readRaw(path) {
+async function readRaw(path4) {
   try {
-    return await readFile(path, "utf8");
+    return await readFile(path4, "utf8");
   } catch {
     return null;
   }
 }
 async function ensureClaudeCredentials(env = process.env) {
   try {
-    const path = claudeCredentialsPath();
+    const path4 = claudeCredentialsPath();
     const plan = planCredentialsWrite({
       isCloud: isConveyorCloudEnv(env),
       token: env.CLAUDE_CODE_OAUTH_TOKEN,
-      existingRaw: await readRaw(path),
+      existingRaw: await readRaw(path4),
       now: Date.now()
     });
     if (plan.action === "skip") return;
     await mkdir3(claudeConfigHome(), { recursive: true });
-    await writeFile3(path, plan.contents, { encoding: "utf8", mode: 384 });
-    await chmod2(path, 384).catch(() => {
+    await writeFile4(path4, plan.contents, { encoding: "utf8", mode: 384 });
+    await chmod2(path4, 384).catch(() => {
     });
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
@@ -3657,11 +4315,11 @@ function planClaudeJsonSeed(existingRaw, trustCwd) {
 async function ensureClaudeOnboarding(env = process.env, trustCwd) {
   try {
     if (!isConveyorCloudEnv(env)) return;
-    const path = claudeJsonPath();
-    const contents = planClaudeJsonSeed(await readRaw(path), trustCwd);
+    const path4 = claudeJsonPath();
+    const contents = planClaudeJsonSeed(await readRaw(path4), trustCwd);
     if (contents === null) return;
-    await writeFile3(path, contents, "utf8");
-    const verify = await readRaw(path);
+    await writeFile4(path4, contents, "utf8");
+    const verify = await readRaw(path4);
     if (verify === contents) {
       process.stderr.write(
         `[conveyor-agent] claude onboarding seeded${trustCwd ? ` (trust: ${trustCwd})` : ""}
@@ -3669,7 +4327,7 @@ async function ensureClaudeOnboarding(env = process.env, trustCwd) {
       );
     } else {
       process.stderr.write(
-        `[conveyor-agent] claude onboarding seed read-back MISMATCH at ${path}: wrote ${contents.length}B, read ${verify?.length ?? 0}B \u2014 CLI may see stale config and park at a startup dialog
+        `[conveyor-agent] claude onboarding seed read-back MISMATCH at ${path4}: wrote ${contents.length}B, read ${verify?.length ?? 0}B \u2014 CLI may see stale config and park at a startup dialog
 `
       );
     }
@@ -3682,12 +4340,12 @@ async function ensureClaudeOnboarding(env = process.env, trustCwd) {
 async function removeConveyorCredentials(env = process.env) {
   try {
     if (!isConveyorCloudEnv(env)) return;
-    const path = claudeCredentialsPath();
-    const existing = parseClaudeAiOauth(await readRaw(path));
+    const path4 = claudeCredentialsPath();
+    const existing = parseClaudeAiOauth(await readRaw(path4));
     if (existing && typeof existing.refreshToken === "string" && existing.refreshToken.length > 0) {
       return;
     }
-    await rm2(path, { force: true });
+    await rm5(path4, { force: true });
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     process.stderr.write(`[conveyor-agent] claude credentials removal failed: ${message}
@@ -4009,7 +4667,7 @@ function formatIncidents(incidents) {
 }
 
 // src/execution/tag-context-resolver.ts
-import { readFile as readFile2, readdir, stat as stat2 } from "fs/promises";
+import { readFile as readFile2, readdir, stat as stat4 } from "fs/promises";
 var TYPE_PRIORITY = { rule: 0, file: 1, folder: 2, doc: 3 };
 var BINARY_EXTENSIONS = /* @__PURE__ */ new Set([
   ".png",
@@ -4059,7 +4717,7 @@ async function readFileContent(filePath, maxChars) {
     let rawContent;
     let mtimeMs;
     try {
-      const st = await stat2(filePath);
+      const st = await stat4(filePath);
       mtimeMs = st.mtimeMs;
     } catch {
       return null;
@@ -4086,7 +4744,7 @@ async function readFolderListing(folderPath) {
   try {
     let mtimeMs;
     try {
-      const st = await stat2(folderPath);
+      const st = await stat4(folderPath);
       mtimeMs = st.mtimeMs;
     } catch {
       return null;
@@ -5634,7 +6292,7 @@ function buildMutationTools(connection, config) {
 }
 
 // src/tools/attachment-tools.ts
-import { readFile as readFile3, stat as stat3 } from "fs/promises";
+import { readFile as readFile3, stat as stat5 } from "fs/promises";
 import { basename, extname, isAbsolute, join as join6 } from "path";
 import { z as z6 } from "zod";
 var IMAGE_MIME_BY_EXT = {
@@ -5652,16 +6310,16 @@ function buildUploadAttachmentTool(connection, config) {
       path: z6.string().describe("Path to the image file \u2014 absolute, or relative to the workspace root"),
       title: z6.string().optional().describe("Short caption posted with the image (defaults to the file name)")
     },
-    async ({ path, title }) => {
+    async ({ path: path4, title }) => {
       try {
-        const filePath = isAbsolute(path) ? path : join6(config.workspaceDir, path);
+        const filePath = isAbsolute(path4) ? path4 : join6(config.workspaceDir, path4);
         const mimeType = IMAGE_MIME_BY_EXT[extname(filePath).toLowerCase()];
         if (!mimeType) {
           return textResult(
             `Unsupported file type "${extname(filePath) || "(none)"}". Supported: ${Object.keys(IMAGE_MIME_BY_EXT).join(", ")}`
           );
         }
-        const info = await stat3(filePath).catch(() => null);
+        const info = await stat5(filePath).catch(() => null);
         if (!info?.isFile()) {
           return textResult(`File not found: ${filePath}`);
         }
@@ -6568,14 +7226,14 @@ function flushPendingToolCalls(host, turnToolCalls) {
   }
   const outputsByTool = /* @__PURE__ */ new Map();
   for (const entry of host.pendingToolOutputs) {
-    const list = outputsByTool.get(entry.tool) ?? [];
-    list.push(entry.output);
-    outputsByTool.set(entry.tool, list);
+    const list2 = outputsByTool.get(entry.tool) ?? [];
+    list2.push(entry.output);
+    outputsByTool.set(entry.tool, list2);
   }
   for (const call of turnToolCalls) {
-    const list = outputsByTool.get(call.tool);
-    if (list && list.length > 0) {
-      call.output = list.shift();
+    const list2 = outputsByTool.get(call.tool);
+    if (list2 && list2.length > 0) {
+      call.output = list2.shift();
     }
   }
   host.connection.sendEvent({ type: "turn_end", toolCalls: [...turnToolCalls] });
@@ -7063,10 +7721,10 @@ function hasExistingSessionFile(taskId, cwd, lineage) {
   const key = sessionLineageKey(taskId, lineage.agentMode, lineage.runnerMode);
   return sessionFileExists(taskIdToSessionUuid(key), cwd);
 }
-function repairTornSessionFile(path) {
+function repairTornSessionFile(path4) {
   try {
-    if (!existsSync(path)) return false;
-    const content = readFileSync2(path, "utf8");
+    if (!existsSync(path4)) return false;
+    const content = readFileSync2(path4, "utf8");
     if (content.length === 0) return false;
     let keepEnd = content.length;
     if (!content.endsWith("\n")) {
@@ -7085,9 +7743,9 @@ function repairTornSessionFile(path) {
       keepEnd = prevNewline + 1;
     }
     if (keepEnd === content.length) return false;
-    truncateSync(path, Buffer.byteLength(content.slice(0, keepEnd), "utf8"));
+    truncateSync(path4, Buffer.byteLength(content.slice(0, keepEnd), "utf8"));
     logger2.warn("Repaired torn transcript before resume", {
-      path,
+      path: path4,
       trimmedBytes: content.length - keepEnd
     });
     return true;
@@ -7412,12 +8070,14 @@ async function handleAuthError(context, host, options) {
   host.connection.postChatMessage("Authentication expired. Re-bootstrapping credentials...");
   const refreshed = await host.connection.refreshAuthToken();
   if (!refreshed) {
-    host.connection.postChatMessage("Failed to refresh authentication. Agent will restart.");
+    host.connection.postChatMessage(
+      "\u26A0\uFE0F No Claude credential is configured for this project \u2014 the agent can't run and is now idle. Add a Claude Code OAuth token (or Anthropic API key) in Project Settings, then resume this task."
+    );
     host.connection.sendEvent({
       type: "error",
-      message: "Auth re-bootstrap failed, exiting for restart"
+      message: "No Claude credential available \u2014 agent idle (dormant)"
     });
-    process.exit(1);
+    return;
   }
   context.claudeSessionId = null;
   host.connection.storeSessionId("");
@@ -7901,8 +8561,195 @@ function readAgentVersion() {
   return null;
 }
 
+// src/runner/port-discovery.ts
+import { readFile as readFile4 } from "fs/promises";
+import { execFile } from "child_process";
+var PROC_TCP_LISTEN_STATE = "0A";
+function parseProcNetTcpListeners(content) {
+  const ports = [];
+  const lines = content.split("\n");
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line) continue;
+    const cols = line.trim().split(/\s+/);
+    if (cols.length < 4 || cols[3] !== PROC_TCP_LISTEN_STATE) continue;
+    const local = cols[1];
+    if (!local) continue;
+    const portHex = local.split(":").pop();
+    if (!portHex) continue;
+    const port = Number.parseInt(portHex, 16);
+    if (Number.isInteger(port) && port >= 1 && port <= 65535) ports.push(port);
+  }
+  return ports;
+}
+var DEFAULT_PROC_PATHS = ["/proc/net/tcp", "/proc/net/tcp6"];
+async function readProcListeningPorts(procPaths = DEFAULT_PROC_PATHS) {
+  const ports = /* @__PURE__ */ new Set();
+  let readable = false;
+  for (const path4 of procPaths) {
+    try {
+      const content = await readFile4(path4, "utf8");
+      readable = true;
+      for (const port of parseProcNetTcpListeners(content)) ports.add(port);
+    } catch {
+    }
+  }
+  return readable ? ports : null;
+}
+async function readNetstatListeningPorts() {
+  const output = await new Promise((resolve) => {
+    execFile("netstat", ["-an", "-p", "tcp"], { timeout: 5e3 }, (err, stdout) => {
+      resolve(err ? null : stdout);
+    });
+  });
+  if (output === null) return null;
+  const ports = /* @__PURE__ */ new Set();
+  for (const line of output.split("\n")) {
+    if (!line.includes("LISTEN")) continue;
+    const cols = line.trim().split(/\s+/);
+    const local = cols[3];
+    if (!local) continue;
+    const portStr = local.split(".").pop();
+    const port = Number(portStr);
+    if (Number.isInteger(port) && port >= 1 && port <= 65535) ports.add(port);
+  }
+  return ports;
+}
+async function readListeningPorts() {
+  const proc = await readProcListeningPorts();
+  if (proc !== null) return proc;
+  if (process.platform !== "linux") return readNetstatListeningPorts();
+  return null;
+}
+var DEFAULT_EXCLUDED_PORTS = [2222, 5432, 6379, 9200];
+var DEFAULT_EPHEMERAL_PORT_MIN = 32768;
+var DEFAULT_INTERVAL_MS = 15e3;
+var DEFAULT_MAX_PORTS = 16;
+var CONFIRM_SCANS = 2;
+var PortDiscovery = class {
+  opts;
+  intervalMs;
+  maxPorts;
+  excluded;
+  ephemeralPortMin;
+  scan;
+  now;
+  log;
+  baseline = null;
+  tracked = /* @__PURE__ */ new Map();
+  timer = null;
+  ticking = false;
+  disabled = false;
+  /** Set when the confirmed set changed (or a report failed) — cleared only
+   *  after a successful report, so transient RPC failures retry next tick. */
+  reportPending = false;
+  lastReportedKey = "";
+  constructor(options) {
+    this.opts = options;
+    this.intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;
+    this.maxPorts = options.maxPorts ?? DEFAULT_MAX_PORTS;
+    this.excluded = new Set(options.excludedPorts ?? DEFAULT_EXCLUDED_PORTS);
+    this.ephemeralPortMin = options.ephemeralPortMin ?? DEFAULT_EPHEMERAL_PORT_MIN;
+    this.scan = options.scan ?? readListeningPorts;
+    this.now = options.now ?? (() => /* @__PURE__ */ new Date());
+    this.log = options.log ?? ((m) => process.stderr.write(`[conveyor-agent] ${m}
+`));
+  }
+  /** Take the baseline scan and start polling. Safe to call once. */
+  async start() {
+    if (this.timer || this.disabled) return;
+    const baseline = await this.scanSafe();
+    if (baseline === null) {
+      this.disabled = true;
+      this.log("Port discovery disabled: no listening-socket source available");
+      return;
+    }
+    this.baseline = baseline;
+    this.timer = setInterval(() => void this.tick(), this.intervalMs);
+    this.timer.unref?.();
+  }
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+  /** One poll cycle. Exposed for tests (deterministic, no timers needed). */
+  async tick() {
+    if (this.ticking || this.disabled || !this.baseline) return;
+    this.ticking = true;
+    try {
+      const current = await this.scanSafe();
+      if (current === null) return;
+      this.updateTracking(current);
+      if (this.reportPending) await this.flushReport();
+    } finally {
+      this.ticking = false;
+    }
+  }
+  async scanSafe() {
+    try {
+      return await this.scan();
+    } catch {
+      return null;
+    }
+  }
+  isCandidate(port) {
+    if (this.baseline?.has(port)) return false;
+    if (this.excluded.has(port)) return false;
+    if (port >= this.ephemeralPortMin) return false;
+    return true;
+  }
+  updateTracking(current) {
+    for (const port of current) {
+      if (!this.isCandidate(port)) continue;
+      const entry = this.tracked.get(port);
+      if (!entry) {
+        this.tracked.set(port, { seen: 1, missed: 0, confirmed: false, detectedAt: "" });
+        continue;
+      }
+      entry.seen += 1;
+      entry.missed = 0;
+      if (!entry.confirmed && entry.seen >= CONFIRM_SCANS) {
+        entry.confirmed = true;
+        entry.detectedAt = this.now().toISOString();
+      }
+    }
+    for (const [port, entry] of this.tracked) {
+      if (current.has(port)) continue;
+      entry.missed += 1;
+      entry.seen = 0;
+      if (entry.missed >= CONFIRM_SCANS || !entry.confirmed) this.tracked.delete(port);
+    }
+    const key = this.confirmedKey();
+    if (key !== this.lastReportedKey) this.reportPending = true;
+  }
+  confirmedPorts() {
+    const confirmed = [...this.tracked.entries()].filter(([, entry]) => entry.confirmed).sort(([a], [b]) => a - b).slice(0, this.maxPorts);
+    return confirmed.map(([port, entry]) => ({
+      port,
+      protocol: "tcp",
+      detectedAt: entry.detectedAt
+    }));
+  }
+  confirmedKey() {
+    return this.confirmedPorts().map(({ port }) => port).join(",");
+  }
+  async flushReport() {
+    const ports = this.confirmedPorts();
+    const key = ports.map(({ port }) => port).join(",");
+    try {
+      await this.opts.report(ports);
+      this.lastReportedKey = key;
+      this.reportPending = false;
+      this.log(`Discovered preview ports: [${key || "none"}]`);
+    } catch {
+    }
+  }
+};
+
 // src/runner/parent-pull-handler.ts
-import { execSync as execSync2 } from "child_process";
+import { execSync as execSync4 } from "child_process";
 function handlePullBranch(workDir, branch) {
   if (!branch) return;
   const current = getCurrentBranch(workDir);
@@ -7921,14 +8768,14 @@ function handlePullBranch(workDir, branch) {
     return;
   }
   try {
-    execSync2(`git fetch origin ${branch}`, { cwd: workDir, stdio: "ignore", timeout: 6e4 });
+    execSync4(`git fetch origin ${branch}`, { cwd: workDir, stdio: "ignore", timeout: 6e4 });
   } catch {
     process.stderr.write(`[conveyor-agent] pull_branch: fetch failed for ${branch}
 `);
     return;
   }
   try {
-    execSync2(`git pull --ff-only origin ${branch}`, {
+    execSync4(`git pull --ff-only origin ${branch}`, {
       cwd: workDir,
       stdio: "ignore",
       timeout: 6e4
@@ -7980,6 +8827,8 @@ var SessionRunner = class _SessionRunner {
   agentSpokeThisTurn = false;
   /** Guards overlapping runs of the periodic git flush. */
   periodicFlushInFlight = false;
+  /** Runtime preview-port poller (v3 dynamic port discovery). */
+  portDiscovery = null;
   constructor(config, callbacks) {
     this.config = config;
     this.callbacks = callbacks;
@@ -8036,7 +8885,6 @@ var SessionRunner = class _SessionRunner {
     this.wireConnectionCallbacks();
     this.lifecycle.startHeartbeat();
     this.lifecycle.startTokenRefresh();
-    this.lifecycle.startGitFlush();
     const { pendingMessages: serverMessages } = await this.connection.call("connectAgent", {
       sessionId: this.sessionId
     });
@@ -8045,6 +8893,11 @@ var SessionRunner = class _SessionRunner {
         this.pendingMessages.push({ content: msg.content, userId: msg.userId });
       }
     }
+    this.portDiscovery = new PortDiscovery({
+      report: (ports) => this.connection.reportDiscoveredPorts(ports)
+    });
+    void this.portDiscovery.start().catch(() => {
+    });
     const agentVersion = readAgentVersion();
     if (agentVersion) {
       this.connection.call("notifyAgentVersion", { sessionId: this.sessionId, agentVersion }).catch(() => {
@@ -8079,6 +8932,17 @@ var SessionRunner = class _SessionRunner {
       await this.shutdown("error");
       return;
     }
+    const gitState = await awaitGitReady({
+      onLog: (m) => process.stderr.write(`[conveyor-agent] ${m}
+`)
+    });
+    if (gitState === "failed" || gitState === "timeout") {
+      const message = gitState === "failed" ? "Workspace git preparation failed (see pod logs)" : "Workspace git preparation timed out (see pod logs)";
+      this.connection.sendEvent({ type: "error", message });
+      await this.callbacks.onEvent({ type: "error", message });
+      await this.shutdown("error");
+      return;
+    }
     if (process.env.CONVEYOR_GIT_READY !== "1") {
       if (this.fullContext?.githubBranch) {
         ensureOnTaskBranch(this.config.workspaceDir, this.fullContext.githubBranch);
@@ -8087,11 +8951,31 @@ var SessionRunner = class _SessionRunner {
         syncWithBaseBranch(this.config.workspaceDir, this.fullContext.baseBranch);
       }
     }
+    if (!this.stopped) {
+      this.lifecycle.startGitFlush();
+    }
     if (this.fullContext?.githubBranch) {
-      const restored = restoreWipSnapshot(this.config.workspaceDir, this.fullContext.githubBranch);
-      if (restored !== "none") {
-        process.stderr.write(`[conveyor-agent] WIP snapshot restore: ${restored}
+      const snapshotUrl = process.env.CONVEYOR_SNAPSHOT_URL;
+      if (snapshotUrl) {
+        const restore = await restoreOnBoot(
+          { snapshotUrl, gitPlan: { branch: this.fullContext.githubBranch } },
+          this.config.workspaceDir
+        );
+        if (restore.source !== "clean") {
+          process.stderr.write(
+            `[conveyor-agent] WorkPreservation restore: source=${restore.source}${restore.fileCount === void 0 ? "" : ` files=${restore.fileCount}`}
+`
+          );
+        }
+      } else {
+        const restored = restoreWipSnapshot(
+          this.config.workspaceDir,
+          this.fullContext.githubBranch
+        );
+        if (restored !== "none") {
+          process.stderr.write(`[conveyor-agent] WIP snapshot restore: ${restored}
 `);
+        }
       }
     }
     this.mode.applyServerMode(this.fullContext?.agentMode, this.fullContext?.isAuto);
@@ -8421,11 +9305,28 @@ var SessionRunner = class _SessionRunner {
 `
         );
       }
+      await this.uploadGcsSnapshotIfConfigured();
     } catch {
     } finally {
       this.periodicFlushInFlight = false;
     }
   }
+  /** PUT the WorkPreservation snapshot tar to the bundle's capability URL
+   *  when this pod is v3 (CONVEYOR_SNAPSHOT_UPLOAD_URL set). Never throws. */
+  async uploadGcsSnapshotIfConfigured() {
+    const uploadUrl = process.env.CONVEYOR_SNAPSHOT_UPLOAD_URL;
+    if (!uploadUrl) return;
+    try {
+      const gcs = await uploadSnapshotToGcs(this.config.workspaceDir, uploadUrl);
+      if (gcs.uploaded) {
+        process.stderr.write(
+          `[conveyor-agent] WorkPreservation GCS snapshot: files=${gcs.fileCount} bytes=${gcs.sizeBytes}
+`
+        );
+      }
+    } catch {
+    }
+  }
   /** Best-effort WIP commit + push on shutdown so in-flight work isn't lost
    *  when a claudespace pod is killed. Must be called BEFORE stop() so the
    *  connection is still alive for token refresh. Never throws. */
@@ -8450,6 +9351,7 @@ var SessionRunner = class _SessionRunner {
 `
         );
       }
+      await this.uploadGcsSnapshotIfConfigured();
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       process.stderr.write(`[conveyor-agent] Shutdown git flush failed: ${msg}
@@ -8459,6 +9361,7 @@ var SessionRunner = class _SessionRunner {
   stop() {
     this.stopped = true;
     this.queryBridge?.stop();
+    this.portDiscovery?.stop();
     this.lifecycle.destroy();
     this.connection.disconnect();
     if (this.inputResolver) {
@@ -8684,6 +9587,38 @@ var SessionRunner = class _SessionRunner {
     this.connection.onPullBranch(({ branch }) => {
       handlePullBranch(this.config.workspaceDir, branch);
     });
+    this.connection.onFinalizeSnapshot(() => void this.finalizeSnapshotNow());
+  }
+  /** Eager finalize snapshot triggered by the reconciler's sleep signal
+   *  (session:finalizeSnapshot). Runs pg_dump + a full capture and uploads it
+   *  NOW so the sleep confirms on this snapshot instead of waiting for the
+   *  ~2min periodic flush — and so sidecar DB state (which ONLY finalizeForSleep
+   *  captures via pg_dump) actually lands. Best-effort: on failure the
+   *  periodic/shutdown path stays the fallback. No-op on non-v3 pods. */
+  async finalizeSnapshotNow() {
+    const uploadUrl = process.env.CONVEYOR_SNAPSHOT_UPLOAD_URL;
+    if (!uploadUrl || this.stopped) return;
+    try {
+      await finalizeForSleep({
+        cwd: this.config.workspaceDir,
+        branch: this.fullContext?.githubBranch ?? "",
+        snapshotUploadUrl: uploadUrl,
+        refreshToken: async () => {
+          try {
+            const res = await this.connection.call("refreshGithubToken", {
+              sessionId: this.connection.sessionId
+            });
+            return res.token;
+          } catch {
+            return void 0;
+          }
+        }
+      });
+      process.stderr.write(
+        "[conveyor-agent] Finalize snapshot (pg_dump) uploaded on sleep signal\n"
+      );
+    } catch {
+    }
   }
   /** Proactively refresh the GitHub token before the 1-hour expiry. */
   async refreshGithubToken() {
@@ -8727,6 +9662,7 @@ var SessionRunner = class _SessionRunner {
     process.stderr.write(`[conveyor-agent] Shutdown: reason=${finalState}
 `);
     this.connection.sendEvent({ type: "shutdown", reason: finalState });
+    this.portDiscovery?.stop();
     this.lifecycle.destroy();
     try {
       await this.setState(finalState);
@@ -8771,13 +9707,13 @@ var SessionRunner = class _SessionRunner {
 };
 
 // src/setup/config.ts
-import { readFile as readFile4 } from "fs/promises";
+import { readFile as readFile5 } from "fs/promises";
 import { join as join8 } from "path";
 var DEVCONTAINER_PATH = ".devcontainer/conveyor/devcontainer.json";
 var DEVCONTAINER_PORT_DENY_LIST = /* @__PURE__ */ new Set([5432, 6379, 9200]);
 async function loadForwardPorts(workspaceDir) {
   try {
-    const raw = await readFile4(join8(workspaceDir, DEVCONTAINER_PATH), "utf-8");
+    const raw = await readFile5(join8(workspaceDir, DEVCONTAINER_PATH), "utf-8");
     const parsed = JSON.parse(raw);
     const ports = (parsed.forwardPorts ?? []).filter(
       (p) => typeof p === "number" && !DEVCONTAINER_PORT_DENY_LIST.has(p)
@@ -8821,7 +9757,7 @@ function loadConveyorConfig() {
 }
 
 // src/setup/commands.ts
-import { spawn, execSync as execSync3 } from "child_process";
+import { spawn, execSync as execSync5 } from "child_process";
 function runSetupCommand(cmd, cwd, onOutput) {
   return new Promise((resolve, reject) => {
     const child = spawn("sh", ["-c", cmd], {
@@ -8850,7 +9786,7 @@ function runSetupCommand(cmd, cwd, onOutput) {
 var AUTH_TOKEN_TIMEOUT_MS = 3e4;
 function runAuthTokenCommand(cmd, userEmail, cwd) {
   try {
-    const output = execSync3(`${cmd} ${JSON.stringify(userEmail)}`, {
+    const output = execSync5(`${cmd} ${JSON.stringify(userEmail)}`, {
       cwd,
       timeout: AUTH_TOKEN_TIMEOUT_MS,
       stdio: ["ignore", "pipe", "ignore"],
@@ -8880,10 +9816,10 @@ function runStartCommand(cmd, cwd, onOutput) {
 }
 
 // src/setup/codespace.ts
-import { execSync as execSync4 } from "child_process";
+import { execSync as execSync6 } from "child_process";
 function unshallowRepo(workspaceDir) {
   try {
-    execSync4("git fetch --unshallow", {
+    execSync6("git fetch --unshallow", {
       cwd: workspaceDir,
       timeout: 6e4,
       stdio: "ignore"
@@ -8896,6 +9832,8 @@ export {
   fetchBootstrap,
   applyBootstrapToEnv,
   AgentConnection,
+  DEFAULT_LIFECYCLE_CONFIG,
+  Lifecycle,
   createServiceLogger,
   hasUncommittedChanges,
   getCurrentBranch,
@@ -8905,6 +9843,13 @@ export {
   flushPendingChanges,
   pushToOrigin,
   PlanSync,
+  awaitGitReady,
+  uploadSnapshotToGcs,
+  captureSnapshot,
+  startPeriodic,
+  stop,
+  finalizeForSleep,
+  restoreOnBoot,
   SessionRunner,
   loadForwardPorts,
   buildSessionPreviewPorts,
@@ -8914,4 +9859,4 @@ export {
   runStartCommand,
   unshallowRepo
 };
-//# sourceMappingURL=chunk-34NA4BCK.js.map
+//# sourceMappingURL=chunk-QKRPJ7DB.js.map