@instafy/cli 0.4.1 → 0.5.1

package/dist/cli.js

@@ -1330,6 +1330,8 @@ var require_redaction = __commonJS({
       const opaqueCandidatePattern = /[A-Za-z0-9][A-Za-z0-9_\-+/=~]{18,}[A-Za-z0-9=]/g;
       const digitCodePattern = /(?<![\d.,][ \u00a0]?)(?:\d{6,8}|\d{3}[ \u00a0]\d{3}|\d{4}[ \u00a0]\d{4})(?![\d]|[.,]\d)/g;
       const codeWordPattern = /(?<![\p{L}])(?:codes?|kode|otp|passcode|pin|tan|2fa|mfa|(?:best(?:ä|ae)tigungs|sicherheits|verifizierungs|verifikations|zugangs|anmelde|freigabe|authentifizierungs|wiederherstellungs|einmal)code)(?![\p{L}])/iu;
+      const DIGIT_CODE_SOURCE = digitCodePattern.source;
+      const CODE_WORD_SOURCE = codeWordPattern.source;
       const NEARBY_CHARACTERS = 120;
       const CODE_NEARBY_CHARACTERS = 32;
       const HEX_NEARBY_CHARACTERS = 32;
@@ -1424,21 +1426,21 @@ var require_redaction = __commonJS({
             return TEXT_MASK;
           });
         }
-        text2 = text2.replace(digitCodePattern, (match, offset, whole) => {
-          const before = whole.slice(Math.max(0, offset - CODE_NEARBY_CHARACTERS), offset);
+        text2 = text2.replace(digitCodePattern, (match, offset, whole2) => {
+          const before = whole2.slice(Math.max(0, offset - CODE_NEARBY_CHARACTERS), offset);
           if (!codeWordPattern.test(before)) return match;
           masked += 1;
           matches += 1;
           return TEXT_MASK;
         });
         opaqueCandidatePattern.lastIndex = 0;
-        text2 = text2.replace(opaqueCandidatePattern, (match, offset, whole) => {
+        text2 = text2.replace(opaqueCandidatePattern, (match, offset, whole2) => {
           const hexLike = uuidPattern.test(match) || longHexPattern.test(match);
           if (!hexLike && !looksRandom3(match)) return match;
           if (!strict && !credentialContext) {
-            if (hexLike && identifierLabelPattern.test(whole.slice(Math.max(0, offset - 16), offset))) return match;
+            if (hexLike && identifierLabelPattern.test(whole2.slice(Math.max(0, offset - 16), offset))) return match;
             const window = hexLike ? HEX_NEARBY_CHARACTERS : NEARBY_CHARACTERS;
-            const nearby = whole.slice(Math.max(0, offset - window), offset) + " " + whole.slice(offset + match.length, offset + match.length + window);
+            const nearby = whole2.slice(Math.max(0, offset - window), offset) + " " + whole2.slice(offset + match.length, offset + match.length + window);
             if (!credentialProximityPattern.test(nearby)) return match;
           }
           count(match);
@@ -1461,8 +1463,8 @@ var require_redaction = __commonJS({
         return value.length >= 16 && (looksRandom3(value, 16) || uuidPattern.test(value) || /^[0-9a-f]{16,}$/i.test(value));
       }
       function redactPairs(value, onMask) {
-        return value.replace(/([^&#?=/]+)=([^&#]*)/g, (whole, key, rawValue) => {
-          if (!sensitiveUrlValue(key, rawValue)) return whole;
+        return value.replace(/([^&#?=/]+)=([^&#]*)/g, (whole2, key, rawValue) => {
+          if (!sensitiveUrlValue(key, rawValue)) return whole2;
           onMask(decodeComponent(rawValue));
           return `${key}=${URL_MASK}`;
         });
@@ -1556,6 +1558,9 @@ var require_redaction = __commonJS({
         CREDENTIAL_CONTEXT_SOURCE,
         PLACEHOLDER_SOURCE,
         MASKED_TEXT_SOURCE,
+        DIGIT_CODE_SOURCE,
+        CODE_WORD_SOURCE,
+        CODE_NEARBY_CHARACTERS,
         SECRET_SCREEN_MESSAGE,
         hasCredentialWord: hasCredentialWord2,
         looksRandom: looksRandom3,
@@ -1807,8 +1812,8 @@ var require_linkOnly = __commonJS({
         if (url.username || url.password || url.port || url.hash) return { error: "has user info, a port or a fragment" };
         if (url.hostname.includes(MARK) || !hostOnSite(hostOfUrl2(url), patterns)) return { error: "is not on the site's own hosts" };
         const placeholderIn = (text2) => {
-          const whole = new RegExp(`^${MARK}(\\d+)x$`).exec(text2);
-          if (whole) return { name: names[Number(whole[1])] };
+          const whole2 = new RegExp(`^${MARK}(\\d+)x$`).exec(text2);
+          if (whole2) return { name: names[Number(whole2[1])] };
           return text2.includes(MARK) ? void 0 : null;
         };
         const segments = [];
@@ -1965,8 +1970,8 @@ var require_linkOnly = __commonJS({
         for (const run of decoded(text2).split(HOST_BREAK)) {
           if (names.size > MAX_EMBEDDED_NAMES) break;
           if (!run) continue;
-          const whole = embeddedName(run);
-          if (whole) names.add(whole);
+          const whole2 = embeddedName(run);
+          if (whole2) names.add(whole2);
           for (const piece of run.split(NOT_NAME_CHARACTER)) {
             const name = piece && piece !== run ? embeddedName(piece) : null;
             if (name) names.add(name);
@@ -6795,7 +6800,9 @@ async function tailTunnelLogs(options) {
 
 // src/preview.ts
 import { spawn as spawn6 } from "node:child_process";
+import { createHash as createHash2 } from "node:crypto";
 import fs12 from "node:fs";
+import net5 from "node:net";
 import os7 from "node:os";
 import path13 from "node:path";
 import kleur8 from "kleur";
@@ -7110,6 +7117,7 @@ var MAX_HEADER_BYTES = 128 * 1024;
 
 // src/web-read.ts
 var redaction = __toESM(require_redaction(), 1);
+import { randomUUID as randomUUID2 } from "node:crypto";
 import dns2 from "node:dns";
 import http3 from "node:http";
 import https from "node:https";
@@ -8110,12 +8118,109 @@ function loadWebFixtures(folder) {
   };
 }
 
+// src/web-budget.ts
+var ResearchBudgetError = class extends Error {
+};
+function invalidResponse() {
+  throw new ResearchBudgetError("The controller returned an invalid research allowance. No further pages were loaded.");
+}
+function object(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function whole(value, min, max) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= min && value <= max;
+}
+function readBudget(value) {
+  if (!object(value) || value.scope !== "this task" || !whole(value.loadsPerTurn, 1, 200) || !whole(value.loadsPerHost, 1, value.loadsPerTurn) || !whole(value.loadsUsed, 0, value.loadsPerTurn) || value.loadsLeft !== value.loadsPerTurn - value.loadsUsed || value.hostSpacingSeconds !== 2 || !object(value.hosts) || Object.keys(value.hosts).length > 1200) invalidResponse();
+  for (const entry of Object.values(value.hosts)) {
+    if (!object(entry) || !whole(entry.loads, 0, value.loadsPerHost) || entry.lastAt !== void 0 && (typeof entry.lastAt !== "number" || !Number.isFinite(entry.lastAt))) invalidResponse();
+  }
+  return value;
+}
+function sharedResearchBudget(env, fetcher = globalThis.fetch) {
+  const enabled = env.INSTAFY_RESEARCH_SHARED?.trim();
+  const rawUrl = env.INSTAFY_RESEARCH_CONTROLLER_URL?.trim();
+  const token = env.INSTAFY_RESEARCH_ACCESS_TOKEN?.trim();
+  if (enabled === void 0 && rawUrl === void 0 && token === void 0) return null;
+  if (enabled !== "1" || !rawUrl || !token || /[\r\n]/.test(token)) {
+    throw new ResearchBudgetError("This task requires a shared research allowance, but its runtime binding is incomplete. No pages were loaded.");
+  }
+  let url;
+  try {
+    url = new URL(rawUrl);
+    if (!/^https?:$/.test(url.protocol) || url.username || url.password || url.search || url.hash || url.pathname !== "/") throw new Error();
+  } catch {
+    throw new ResearchBudgetError("The task's research controller binding is invalid. No pages were loaded.");
+  }
+  return new SharedResearchBudget(new URL("/agent/research-budget", url.origin), token, fetcher);
+}
+var SharedResearchBudget = class {
+  constructor(endpoint, token, fetcher) {
+    this.endpoint = endpoint;
+    this.token = token;
+    this.fetcher = fetcher;
+    this.current = null;
+  }
+  async request(body, remainingMs = 5e3) {
+    const deadline = Date.now() + Math.max(1, Math.min(5e3, body?.remainingMs ?? remainingMs));
+    for (let attempt2 = 0; attempt2 < 2; attempt2 += 1) {
+      const abort = new AbortController();
+      const timer = setTimeout(() => abort.abort(), Math.max(1, deadline - Date.now()));
+      try {
+        let response;
+        try {
+          response = await this.fetcher(this.endpoint.href, {
+            method: body ? "POST" : "GET",
+            headers: {
+              Authorization: `Bearer ${this.token}`,
+              Accept: "application/json",
+              ...body ? { "Content-Type": "application/json" } : {}
+            },
+            ...body ? { body: JSON.stringify(body) } : {},
+            redirect: "error",
+            signal: abort.signal
+          });
+        } catch {
+          if (attempt2 === 0 && !abort.signal.aborted && Date.now() < deadline) continue;
+          throw new ResearchBudgetError("The task's shared research allowance is unavailable. No further pages were loaded; do not switch to a local allowance.");
+        }
+        if (!response.ok) {
+          throw new ResearchBudgetError(`The controller refused the shared research allowance (HTTP ${response.status}). No further pages were loaded.`);
+        }
+        let value;
+        try {
+          value = await response.json();
+        } catch {
+          invalidResponse();
+        }
+        if (!object(value)) invalidResponse();
+        return value;
+      } finally {
+        clearTimeout(timer);
+      }
+    }
+    throw new ResearchBudgetError("The task's shared research allowance is unavailable.");
+  }
+  async status(remainingMs = 5e3) {
+    const response = await this.request(void 0, remainingMs);
+    this.current = readBudget(response.budget);
+    return this.current;
+  }
+  async reserve(loadId, requestId, host, remainingMs) {
+    const response = await this.request({ loadId, requestId, host, remainingMs: Math.max(0, Math.min(6e5, Math.trunc(remainingMs))) });
+    const budget = readBudget(response.budget);
+    if (typeof response.allowed !== "boolean" || !whole(response.waitMs, 0, 6e5) || (response.allowed ? response.code !== void 0 : !["turn_limit", "host_limit", "time_limit"].includes(String(response.code)))) invalidResponse();
+    this.current = budget;
+    return { allowed: response.allowed, ...response.code ? { code: response.code } : {}, waitMs: response.waitMs, budget };
+  }
+};
+
 // src/web-read.ts
 var ROBOTS_AGENTS = ["*", "instafy-agent", ...AI_AGENTS];
 var LIMITS = Object.freeze({
   urlsPerCall: 6,
-  loadsPerTurn: 12,
-  loadsPerHost: 4,
+  loadsPerTurn: 100,
+  loadsPerHost: 25,
   hostSpacingMs: 2e3,
   callMs: 6e4,
   pageTimeoutMs: 2e4,
@@ -8377,6 +8482,7 @@ var TELL = {
   http_error: "The site answered with an error. Use another source rather than retrying.",
   unreachable: "The site did not answer. Use another source rather than retrying.",
   timeout: "The site did not answer in time. Use another source rather than retrying.",
+  budget_unavailable: "Research stopped because its shared allowance could not be checked. Keep the evidence already collected; further fresh reads require controller approval.",
   needs_browser: "This page builds its text with JavaScript, so a plain read sees almost nothing. Use another source, or ask for a visible browser turn for this page.",
   no_reuse: `This site's terms bar reusing its content. Summarize it in your own words, cite "seen <date> on <host>" and link back; never copy its reviews, photos or price lists, and keep its content out of anything published or shared by public link (links only there).`
 };
@@ -8499,7 +8605,7 @@ async function readOne(rawUrl, options, ctx) {
     status: "skipped",
     code,
     message,
-    tell: TELL[code]
+    tell: ctx.sharedBudget?.current && code !== "time_limit" ? code === "turn_limit" ? `This task's shared allowance of ${ctx.sharedBudget.current.loadsPerTurn} page loads is used. Work with the evidence already collected, or ask the person.` : `This task has used its ${ctx.sharedBudget.current.loadsPerHost} page loads for this site. Use another source.` : TELL[code]
   });
   let sibling = wwwSibling(requestedUrl);
   const fail = (code, message, extra2 = {}) => ({
@@ -8531,15 +8637,24 @@ async function readOne(rawUrl, options, ctx) {
       return present(page, cached, true, options, ctx.guard);
     }
   }
-  if (earlier.loads >= LIMITS.loadsPerTurn) {
-    return skip("turn_limit", `this turn already loaded ${earlier.loads} pages (limit ${LIMITS.loadsPerTurn})`);
-  }
-  if (earlier.hostLoads >= LIMITS.loadsPerHost) {
-    return skip("host_limit", `this turn already read ${firstSite} ${earlier.hostLoads} times (limit ${LIMITS.loadsPerHost})`);
+  if (ctx.sharedBudget) {
+    if (ctx.deadline - ctx.now() < 1e3) return skip("time_limit", "this call reached its time limit before this URL");
+    const budget = await ctx.sharedBudget.status(ctx.deadline - ctx.now());
+    if (budget.loadsLeft === 0) return skip("turn_limit", `this task already loaded ${budget.loadsUsed} pages (limit ${budget.loadsPerTurn})`);
+    const used = budget.hosts[firstSite]?.loads ?? 0;
+    if (used >= budget.loadsPerHost) return skip("host_limit", `this task already read ${firstSite} ${used} times (limit ${budget.loadsPerHost})`);
+  } else {
+    if (earlier.loads >= LIMITS.loadsPerTurn) {
+      return skip("turn_limit", `this turn already loaded ${earlier.loads} pages (limit ${LIMITS.loadsPerTurn})`);
+    }
+    if (earlier.hostLoads >= LIMITS.loadsPerHost) {
+      return skip("host_limit", `this turn already read ${firstSite} ${earlier.hostLoads} times (limit ${LIMITS.loadsPerHost})`);
+    }
   }
   if (ctx.deadline - ctx.now() < 1e3) return skip("time_limit", "this call reached its time limit before this URL");
   const redirects = [];
   const chainSites = /* @__PURE__ */ new Set();
+  const loadId = randomUUID2();
   let current = new URL(requested);
   let response = null;
   for (let hop = 0; ; hop += 1) {
@@ -8564,7 +8679,21 @@ async function readOne(rawUrl, options, ctx) {
     const robots = await robotsVerdict(current, ctx);
     if ("failed" in robots) return fail(robots.failed, via + robots.message, hopExtra);
     if (robots.refused) return stop("robots", via + robots.refused, host2, hopExtra);
-    if (!chainSites.has(site)) {
+    if (ctx.sharedBudget) {
+      const remainingMs = ctx.deadline - ctx.now();
+      if (remainingMs < 1e3) return skip("time_limit", `${via}this call reached its time limit before reserving a load`, hopExtra);
+      const reservation = await ctx.sharedBudget.reserve(loadId, randomUUID2(), site, remainingMs - 1e3);
+      if (!reservation.allowed) {
+        const code = reservation.code;
+        const budget = reservation.budget;
+        const message = code === "turn_limit" ? `this task already loaded ${budget.loadsUsed} pages (limit ${budget.loadsPerTurn})` : code === "host_limit" ? `this task already read ${site} ${budget.hosts[site]?.loads ?? 0} times (limit ${budget.loadsPerHost})` : `no time left in this call for the next paced read of ${host2}`;
+        return skip(code, via + message, hopExtra);
+      }
+      if (reservation.waitMs + 1e3 > ctx.deadline - ctx.now()) {
+        return skip("time_limit", `${via}this call reached its time limit while reserving the next paced read`, hopExtra);
+      }
+      if (reservation.waitMs > 0) await ctx.sleep(reservation.waitMs);
+    } else if (!chainSites.has(site)) {
       const now = ctx.now();
       const reservation = await ctx.turn.update((state) => {
         if (hop === 0 && state.loads >= LIMITS.loadsPerTurn) {
@@ -8775,6 +8904,7 @@ async function webRead(options, deps = {}) {
     now,
     sleep: deps.sleep ?? realSleep,
     turn,
+    sharedBudget: sharedResearchBudget(env, deps.budgetFetch),
     cache: new Cache(cacheDir === null ? null : apart(cacheDir)),
     guard,
     viewer,
@@ -8782,32 +8912,38 @@ async function webRead(options, deps = {}) {
     robotsMemo: /* @__PURE__ */ new Map()
   };
   const pages = [];
-  for (const url of urls) {
-    const page = await readOne(url, { maxChars, links, fresh: Boolean(options.fresh), terms }, ctx);
+  let interruptedBudget = null;
+  for (const [index, url] of urls.entries()) {
+    let page;
+    try {
+      page = await readOne(url, { maxChars, links, fresh: Boolean(options.fresh), terms }, ctx);
+    } catch (error) {
+      if (!(error instanceof ResearchBudgetError) || !ctx.sharedBudget?.current || !pages.length) throw error;
+      interruptedBudget = ctx.sharedBudget.current;
+      pages.push(...urls.slice(index).map((remaining) => ({
+        ...basePage(remaining, new Date(now()).toISOString(), viewer),
+        code: "budget_unavailable",
+        message: error.message,
+        tell: TELL.budget_unavailable
+      })));
+      break;
+    }
     if (page.status === "failed" && unanswered(page.code, page)) {
       const key = unansweredKey(new URL(url));
-      await turn.update((state2) => {
-        (state2.unanswered ??= {})[key] = now();
+      await turn.update((state) => {
+        (state.unanswered ??= {})[key] = now();
       });
     }
     pages.push(page);
   }
-  const state = await turn.update((s) => ({ loads: s.loads, hosts: Object.fromEntries(Object.entries(s.hosts).map(([h, r]) => [h, r.loads])) }));
+  const budget = interruptedBudget ? lastKnownBudget(interruptedBudget, warnings) : ctx.sharedBudget ? await finalSharedBudget(ctx.sharedBudget, deadline - now(), warnings) : await localBudget(turn, scope.label);
   return {
     ok: true,
     viewer,
     userAgent: USER_AGENT,
     notice: NOTICE,
     pages,
-    budget: {
-      scope: scope.label,
-      loadsUsed: state.loads,
-      loadsLeft: Math.max(0, LIMITS.loadsPerTurn - state.loads),
-      loadsPerTurn: LIMITS.loadsPerTurn,
-      loadsPerHost: LIMITS.loadsPerHost,
-      hostSpacingSeconds: LIMITS.hostSpacingMs / 1e3,
-      hosts: state.hosts
-    },
+    budget,
     guards: {
       linkOnly: {
         sites: guard.list.sites.length,
@@ -8821,6 +8957,63 @@ async function webRead(options, deps = {}) {
     warnings
   };
 }
+function reportBudget(budget) {
+  return { ...budget, hosts: Object.fromEntries(Object.entries(budget.hosts).map(([host, value]) => [host, value.loads])) };
+}
+function lastKnownBudget(budget, warnings) {
+  warnings.push("The shared research allowance could not be refreshed. Budget counts are the last validated controller snapshot and may have changed; another fresh read still requires controller approval.");
+  return { ...reportBudget(budget), lastKnown: true };
+}
+async function finalSharedBudget(shared, remainingMs, warnings) {
+  try {
+    if (remainingMs <= 0) throw new ResearchBudgetError("The call deadline elapsed before the shared research allowance could be refreshed.");
+    return reportBudget(await shared.status(remainingMs));
+  } catch (error) {
+    if (!(error instanceof ResearchBudgetError) || !shared.current) throw error;
+    return lastKnownBudget(shared.current, warnings);
+  }
+}
+async function localBudget(turn, scope) {
+  return turn.update((state) => ({
+    scope,
+    loadsUsed: state.loads,
+    loadsLeft: Math.max(0, LIMITS.loadsPerTurn - state.loads),
+    loadsPerTurn: LIMITS.loadsPerTurn,
+    loadsPerHost: LIMITS.loadsPerHost,
+    hostSpacingSeconds: LIMITS.hostSpacingMs / 1e3,
+    hosts: Object.fromEntries(Object.entries(state.hosts).map(([host, value]) => [host, value.loads]))
+  }));
+}
+async function webBudget(deps = {}) {
+  const env = deps.env ?? process.env;
+  const cwd = deps.cwd ?? process.cwd();
+  const shared = sharedResearchBudget(env, deps.budgetFetch);
+  if (shared) return { budget: reportBudget(await shared.status()) };
+  const fixtureFolder = webFixturesFolder(env, cwd);
+  const fixtures = fixtureFolder ? loadWebFixtures(fixtureFolder) : null;
+  const dirs = webDirs("web-read", env, cwd);
+  const stateDir = deps.stateDir ?? dirs.stateDir;
+  const scope = turnScope(env);
+  const turn = new TurnStore(
+    fixtures ? path11.join(stateDir, "fixtures", sha256(fixtures.folder).slice(0, 16)) : stateDir,
+    scope,
+    deps.now ?? Date.now
+  );
+  return { budget: await localBudget(turn, scope.label) };
+}
+async function runWebBudgetCli(opts, io = { out: console.log, err: console.error }, deps = {}) {
+  try {
+    const report = await webBudget(deps);
+    const b = report.budget;
+    io.out(opts.json ? JSON.stringify(report, null, 1) : `${b.loadsLeft} page loads left in ${b.scope} (${b.loadsUsed} of ${b.loadsPerTurn} used; ${b.loadsPerHost} per site, ${b.hostSpacingSeconds} s apart).`);
+    return WEB_READ_EXIT_OK;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (opts.json) io.out(JSON.stringify({ ok: false, exitCode: WEB_READ_EXIT_INTERNAL, error: message }));
+    else io.err(message);
+    return WEB_READ_EXIT_INTERNAL;
+  }
+}
 function clamp(value, min, max) {
   return Math.min(max, Math.max(min, Math.trunc(value)));
 }
@@ -8848,13 +9041,13 @@ function formatWebRead(report) {
     }
     out.push("");
   }
-  out.push(`${report.budget.loadsUsed} of ${report.budget.loadsPerTurn} page loads used in ${report.budget.scope}.`);
+  out.push(`${report.budget.lastKnown ? "Last known controller count: " : ""}${report.budget.loadsUsed} of ${report.budget.loadsPerTurn} page loads used in ${report.budget.scope}.`);
   for (const warning of report.warnings) out.push(`warning: ${warning}`);
   out.push(report.notice);
   return out.join("\n");
 }
 async function runWebReadCli(urls, opts, io = { out: console.log, err: console.error }, deps = {}) {
-  const whole = (raw, name, min, max) => {
+  const whole2 = (raw, name, min, max) => {
     if (raw === void 0) return void 0;
     const n = Number(raw);
     if (!Number.isInteger(n) || n < min || n > max) throw new WebReadUsageError(`${name} must be a whole number from ${min} to ${max}.`);
@@ -8865,8 +9058,8 @@ async function runWebReadCli(urls, opts, io = { out: console.log, err: console.e
       {
         urls,
         find: opts.find,
-        maxChars: whole(opts.maxChars, "--max-chars", LIMITS.minChars, LIMITS.maxChars),
-        links: whole(opts.links, "--links", 0, LIMITS.maxLinks),
+        maxChars: whole2(opts.maxChars, "--max-chars", LIMITS.minChars, LIMITS.maxChars),
+        links: whole2(opts.links, "--links", 0, LIMITS.maxLinks),
         fresh: opts.fresh
       },
       deps
@@ -8876,7 +9069,7 @@ async function runWebReadCli(urls, opts, io = { out: console.log, err: console.e
   } catch (error) {
     const usage = error instanceof WebReadUsageError;
     const code = usage ? WEB_READ_EXIT_USAGE : WEB_READ_EXIT_INTERNAL;
-    const message = usage || error instanceof LinkOnlyListUnavailableError || error instanceof WebFixturesError ? error.message : `web read failed, nothing was read: ${error instanceof Error ? error.message : String(error)}`;
+    const message = usage || error instanceof LinkOnlyListUnavailableError || error instanceof WebFixturesError || error instanceof ResearchBudgetError ? error.message : `web read failed: ${error instanceof Error ? error.message : String(error)}`;
     if (opts.json) io.out(JSON.stringify({ ok: false, exitCode: code, error: message }));
     else io.err(message);
     return code;
@@ -8887,10 +9080,13 @@ function registerWebCommand(program2) {
     "Read public web pages as untrusted data with their source (robots.txt, link-only sites and stop rules enforced), search for links to read (Octo's turns only), and give the person links to link-only sites (guided mode)"
   );
   web.command("read").description(
-    `Read 1-6 public pages over plain HTTP and print their text, links and structured data with provenance (exit 2: nothing read, 64: bad options). Per turn: ${LIMITS.loadsPerTurn} loads, ${LIMITS.loadsPerHost} per site, ${LIMITS.hostSpacingMs / 1e3} s apart. Stopped URLs (login, CAPTCHA, paywall, 401/403/429, download, secret screen, robots.txt, link-only, private address) are never read another way.`
+    `Read 1-6 public pages over plain HTTP and print their text, links and structured data with provenance (exit 2: nothing read, 64: bad options). Uses the task's shared allowance; standalone: ${LIMITS.loadsPerTurn} loads, ${LIMITS.loadsPerHost} per site, ${LIMITS.hostSpacingMs / 1e3} s apart. Stopped URLs (login, CAPTCHA, paywall, 401/403/429, download, secret screen, robots.txt, link-only, private address) are never read another way.`
   ).argument("<url...>", "http(s) URLs to read").option("--find <terms>", 'Return only the passages that mention these words ("quoted phrases" kept whole)').option("--max-chars <n>", `Most characters of text per page (default ${LIMITS.defaultChars}, at most ${LIMITS.maxChars})`).option("--links <n>", `Most links per page (default ${LIMITS.defaultLinks}, at most ${LIMITS.maxLinks})`).option("--fresh", "Read again even if this workspace's cache has the page (never re-reads a stopped URL)").option("--json", "Output JSON").action(async (urls, opts) => {
     process.exitCode = await runWebReadCli(urls, opts);
   });
+  web.command("budget").description("Show this task's remaining shared page allowance without spending it (or the standalone session allowance)").option("--json", "Output JSON").action(async (opts) => {
+    process.exitCode = await runWebBudgetCli(opts);
+  });
   return web;
 }
 
@@ -9314,6 +9510,18 @@ async function readPageDescription(frame) {
   const raw = await frame.evaluate(() => document.querySelector('meta[name="description" i]')?.getAttribute("content") ?? null).catch(() => null);
   return cleanDescription(raw);
 }
+var READY_MARK_ATTRIBUTE = "data-instafy-ready";
+var READY_MARK_WAIT_MS = 3e4;
+async function waitForReadyMark(frame, timeoutMs) {
+  const mark = await frame.evaluate((name) => document.documentElement?.getAttribute(name) ?? null, READY_MARK_ATTRIBUTE).catch(() => null);
+  if (mark === null) return "none";
+  if (mark === "true") return "ready";
+  if (timeoutMs <= 0) return "late";
+  return frame.waitForFunction((name) => document.documentElement?.getAttribute(name) === "true", READY_MARK_ATTRIBUTE, {
+    timeout: timeoutMs,
+    polling: 100
+  }).then(() => "ready").catch(() => "late");
+}
 async function pageThumbnail(page, context) {
   const cdp = await context.newCDPSession(page);
   try {
@@ -9519,10 +9727,19 @@ async function checkViewport(browser, target, vp, siteOrigin, outDir, timeoutMs,
       (ours(u) ? errors : warnings).push(`HTTP ${s}: ${shortUrl(u)}`);
     });
     await page.goto(target.pageUrl, { waitUntil: "load", timeout: timeoutMs });
-    await page.waitForLoadState("networkidle", { timeout: Math.min(8e3, timeoutMs) }).catch(() => {
-      warnings.push("the network was still busy after 8 s (screenshot taken anyway)");
-    });
-    const frame = target.framed ? page.frames().find((f) => f !== page.mainFrame() && isSiteUrl(String(f.url()), siteOrigin)) : page.mainFrame();
+    const siteFrame = () => target.framed ? page.frames().find((f) => f !== page.mainFrame() && isSiteUrl(String(f.url()), siteOrigin)) : page.mainFrame();
+    const readiness = await waitForReadyMark(
+      siteFrame() ?? page.mainFrame(),
+      Math.max(0, Math.min(READY_MARK_WAIT_MS, timeoutMs) - (Date.now() - t0))
+    );
+    if (readiness === "none") {
+      await page.waitForLoadState("networkidle", { timeout: Math.min(8e3, timeoutMs) }).catch(() => {
+        warnings.push("the network was still busy after 8 s (screenshot taken anyway)");
+      });
+    } else if (readiness === "late") {
+      warnings.push(`the page still said it was drawing (${READY_MARK_ATTRIBUTE}) after ${Math.round((Date.now() - t0) / 1e3)} s; screenshot taken anyway`);
+    }
+    const frame = siteFrame();
     let framed = "ok";
     let snap = { text: 0, media: 0, elements: 0, title: "" };
     if (refused) framed = "refused";
@@ -9557,7 +9774,7 @@ async function checkViewport(browser, target, vp, siteOrigin, outDir, timeoutMs,
     let thumbnail;
     if (takeThumbnail) {
       const [firstUnstopped] = unstopped;
-      thumbnail = firstUnstopped ? { skipped: `a redirect led to ${firstUnstopped[0].slice(0, 200)} (${firstUnstopped[1]}), which a picture never shows` } : blank.blank ? { skipped: "the page looked blank" } : await pageThumbnail(page, context).then(async (shot) => "image" in shot ? { image: shot.image, description: await readPageDescription(page.mainFrame()) } : shot).catch((error) => ({ skipped: `the picture could not be taken: ${firstLine(error)}` }));
+      thumbnail = firstUnstopped ? { skipped: `a redirect led to ${firstUnstopped[0].slice(0, 200)} (${firstUnstopped[1]}), which a picture never shows` } : blank.blank ? { skipped: "the page looked blank" } : readiness === "late" ? { skipped: "the page never said it was ready, so the card keeps its picture" } : await pageThumbnail(page, context).then(async (shot) => "image" in shot ? { image: shot.image, description: await readPageDescription(page.mainFrame()) } : shot).catch((error) => ({ skipped: `the picture could not be taken: ${firstLine(error)}` }));
     }
     return {
       name: vp.name,
@@ -9599,7 +9816,9 @@ async function runSiteCheck(opts) {
   const port = parsePreviewPort(opts.port, env);
   const sitePath = parseCheckPath(opts.path);
   const timeoutMs = opts.timeoutMs ?? 3e4;
-  const viewports = VIEWPORTS.filter((v) => !opts.phone || v.name === "phone");
+  const viewports = VIEWPORTS.filter(
+    (v) => !opts.phone && !opts.desktop ? true : opts.phone && v.name === "phone" || opts.desktop && v.name === "desktop"
+  );
   let outDir = null;
   if (opts.outDir !== void 0) {
     outDir = path12.resolve(opts.outDir);
@@ -9713,12 +9932,14 @@ async function runPreviewCheckCli(opts, io = { out: console.log, err: console.er
     const port = parsePreviewPort(opts.port, env);
     const sitePath = parseCheckPath(opts.path);
     const wantsThumbnail = Boolean(io.uploadThumbnail && io.hasOpenPreview?.(port, sitePath));
+    const takenAt = Date.now();
     const result = await runSiteCheck({
       port,
       path: opts.path,
       thumbnail: wantsThumbnail,
       proxyServer: io.proxyServer,
       phone: opts.phone,
+      desktop: opts.desktop,
       framed: opts.framed,
       workspacePlaywright: opts.workspacePlaywright,
       outDir: opts.out,
@@ -9733,7 +9954,9 @@ async function runPreviewCheckCli(opts, io = { out: console.log, err: console.er
     }
     if (wantsThumbnail && result.thumbnail && io.uploadThumbnail) {
       const shot = result.thumbnail;
-      const outcome = "skipped" in shot ? { status: "skipped", reason: shot.skipped } : await io.uploadThumbnail({ port, path: sitePath, image: shot.image, description: shot.description }).catch((error) => ({ status: "failed", reason: firstLine(error) }));
+      if ("skipped" in shot) await io.pictureTried?.({ port, path: sitePath, takenAt }).catch(() => {
+      });
+      const outcome = "skipped" in shot ? { status: "skipped", reason: shot.skipped } : await io.uploadThumbnail({ port, path: sitePath, image: shot.image, description: shot.description, takenAt }).catch((error) => ({ status: "failed", reason: firstLine(error) }));
       if (outcome) {
         result.report.thumbnail = outcome.status;
         if (outcome.reason) result.report.thumbnailReason = outcome.reason;
@@ -9753,7 +9976,7 @@ async function runPreviewCheckCli(opts, io = { out: console.log, err: console.er
 function registerPreviewCheckCommand(preview, card = {}) {
   return preview.command("check").description(
     "Load a local site in a headless browser and report its title, errors, failed requests and a blank page; writes desktop and phone screenshots, and refreshes the picture on the card of a preview open on that port (exit 1: problems, 2: nothing answering, 3: port not allowed, 4: no browser, 64: bad options, 70: the check itself failed)"
-  ).option("--port <port>", "Local port the site listens on (1024-65535)").option("--path <path>", "Path to load (default /); a ?query and #hash are fine").option("--phone", "Only the phone size (390\xD7844); default: desktop 1280\xD7800 and phone").option("--framed", "Load the site inside a frame on another origin, and report a site that refuses to be framed").option("--workspace-playwright", "Also look for Playwright in this project's node_modules (runs the project's own copy)").option("--out <dir>", "Folder for desktop.png and phone.png (default: a new private folder under the temp folder each run; the report names it)").option("--timeout <ms>", "Page load timeout in ms (default 30000)").option("--wait <ms>", "Extra settle time after load in ms (default 600)").option("--json", "Output JSON").action(async (opts) => {
+  ).option("--port <port>", "Local port the site listens on (1024-65535)").option("--path <path>", "Path to load (default /); a ?query and #hash are fine").option("--phone", "Only the phone size (390\xD7844); default: desktop 1280\xD7800 and phone").option("--desktop", "Only the desktop size (1280\xD7800), the one the card's picture is taken from").option("--framed", "Load the site inside a frame on another origin, and report a site that refuses to be framed").option("--workspace-playwright", "Also look for Playwright in this project's node_modules (runs the project's own copy)").option("--out <dir>", "Folder for desktop.png and phone.png (default: a new private folder under the temp folder each run; the report names it)").option("--timeout <ms>", "Page load timeout in ms (default 30000)").option("--wait <ms>", "Extra settle time after load in ms (default 600)").option("--json", "Output JSON").action(async (opts) => {
     process.exitCode = await runPreviewCheckCli(opts, { out: console.log, err: console.error, ...card });
   });
 }
@@ -9767,6 +9990,8 @@ function thumbnailBudgetMs(env = process.env) {
 }
 var NETWORK_IDLE_MS = 6e3;
 var SETTLE_MS = 1e3;
+var READY_SETTLE_MS = 300;
+var SHOT_RESERVE_MS = 3e3;
 var MAX_THUMBNAIL_FILE_BYTES = 512 * 1024;
 var MAX_HTML_BYTES = 512 * 1024;
 var MIN_SIDE = 64;
@@ -9923,7 +10148,8 @@ function errorLine(error) {
 async function captureSiteThumbnail(options) {
   const env = options.env ?? process.env;
   const budget = options.budgetMs ?? thumbnailBudgetMs(env);
-  const deadline = Date.now() + budget;
+  const began = Date.now();
+  let deadline = began + budget;
   const host = options.host === "::1" ? "[::1]" : "127.0.0.1";
   const siteOrigin = `http://${host}:${options.port}`;
   const left = () => Math.max(0, deadline - Date.now());
@@ -9985,9 +10211,18 @@ async function captureSiteThumbnail(options) {
     if (response && response.status() >= 400) {
       return { ok: false, status: "skipped", reason: `the page answered HTTP ${response.status()}` };
     }
-    await page.waitForLoadState("networkidle", { timeout: Math.max(1, Math.min(NETWORK_IDLE_MS, left())) }).catch(() => {
-    });
-    await page.waitForTimeout(Math.min(SETTLE_MS, left()));
+    const mark = await waitForReadyMark(page.mainFrame(), 0);
+    if (mark === "none") {
+      await page.waitForLoadState("networkidle", { timeout: Math.max(1, Math.min(NETWORK_IDLE_MS, left())) }).catch(() => {
+      });
+      await page.waitForTimeout(Math.min(SETTLE_MS, left()));
+    } else {
+      deadline = Math.max(deadline, began + (options.readyWaitMs ?? READY_MARK_WAIT_MS));
+      if (mark === "late" && await waitForReadyMark(page.mainFrame(), Math.max(0, left() - SHOT_RESERVE_MS)) !== "ready") {
+        return { ok: false, status: "skipped", reason: `the page still said it was drawing after ${Math.round((Date.now() - began) / 1e3)} s` };
+      }
+      await page.waitForTimeout(Math.min(READY_SETTLE_MS, left()));
+    }
     const description = await readPageDescription(page.mainFrame());
     const shot = await pageThumbnail(page, context);
     if ("skipped" in shot) return { ok: false, status: "skipped", reason: shot.skipped };
@@ -10002,7 +10237,16 @@ async function captureSiteThumbnail(options) {
     };
   })();
   const outOfTime = new Promise((resolve) => {
-    timer = setTimeout(() => resolve({ ok: false, status: "failed", reason: `the picture took longer than ${Math.round(budget / 1e3)} s` }), budget);
+    const arm = () => {
+      timer = setTimeout(() => {
+        if (Date.now() < deadline) {
+          arm();
+          return;
+        }
+        resolve({ ok: false, status: "failed", reason: `the picture took longer than ${Math.round((deadline - began) / 1e3)} s` });
+      }, Math.max(0, deadline - Date.now()));
+    };
+    arm();
   });
   try {
     return await Promise.race([work.catch((error) => ({ ok: false, status: "failed", reason: errorLine(error) })), outOfTime]);
@@ -10026,6 +10270,12 @@ var MAX_PATH_LENGTH2 = 512;
 var THUMBNAIL_UPLOAD_TIMEOUT_MS = 15e3;
 var STATE_LOCK_WAIT_MS = 12e4;
 var STATE_LOCK_STALE_MS = 10 * 6e4;
+var PORT_PLACEHOLDER = "{port}";
+var PORT_TAKEN_HINT = "Run it with --start and without --port, so this site gets a free port of its own, or pass --replace to show this site on that port instead.";
+var PICKED_PORT_TAKEN_HINT = "Pass --replace if this site replaces that one (this same site under a new title, for example); otherwise give this site a title of its own.";
+var AUTO_PORT_FIRST = 2e4;
+var AUTO_PORT_COUNT = 1e4;
+var AUTO_PORT_TRIES = 64;
 function instafyDir() {
   return path13.join(os7.homedir(), ".instafy");
 }
@@ -10156,10 +10406,10 @@ function lockHolderIsGone(lockFile) {
     return false;
   }
 }
-async function withStateLock(fn) {
+async function withStateLock(fn, waitMs = STATE_LOCK_WAIT_MS) {
   const lockFile = previewStateLockFile();
   fs12.mkdirSync(instafyDir(), { recursive: true });
-  const deadline = Date.now() + STATE_LOCK_WAIT_MS;
+  const deadline = Date.now() + waitMs;
   for (; ; ) {
     try {
       const fd = fs12.openSync(lockFile, "wx", 384);
@@ -10249,6 +10499,12 @@ async function controllerRequest(params) {
         PREVIEW_EXIT_PORT_NOT_ALLOWED
       );
     }
+    if (response.status === 409 && code === "port_in_use") {
+      throw new PreviewCommandError(
+        `${extractControllerErrorMessage(text2) ?? "Another site's preview holds this port."} ${params.portTakenHint ?? PORT_TAKEN_HINT}`,
+        PREVIEW_EXIT_PORT_NOT_ALLOWED
+      );
+    }
     const message = extractControllerErrorMessage(text2) ?? response.statusText;
     throw new Error(`Preview request failed (${response.status}): ${message}`);
   }
@@ -10457,12 +10713,12 @@ function listeningSocketInodes(procRoot, port) {
       continue;
     }
     for (const line of text2.split("\n").slice(1)) {
-      const fields = line.trim().split(/\s+/);
-      if (fields.length < 10) continue;
-      const local = fields[1] ?? "";
+      const fields2 = line.trim().split(/\s+/);
+      if (fields2.length < 10) continue;
+      const local = fields2[1] ?? "";
       const portHex = local.slice(local.lastIndexOf(":") + 1);
-      if (fields[3] === "0A" && Number.parseInt(portHex, 16) === port && fields[9] !== "0") {
-        inodes.add(fields[9]);
+      if (fields2[3] === "0A" && Number.parseInt(portHex, 16) === port && fields2[9] !== "0") {
+        inodes.add(fields2[9]);
       }
     }
   }
@@ -10638,8 +10894,159 @@ async function startPreviewSite(params) {
     await new Promise((resolve) => setTimeout(resolve, START_POLL_MS));
   }
 }
+function withPort(argv, port) {
+  return argv.map((arg) => arg.split(PORT_PLACEHOLDER).join(String(port)));
+}
+function sameArgv(a, b) {
+  return a.length === b.length && a.every((arg, index) => arg === b[index]);
+}
+function sameStart(a, b) {
+  return Boolean(a && Array.isArray(a.argv) && a.cwd === b.cwd && sameArgv(a.argv, b.argv));
+}
+function preferredSitePort(start) {
+  const digest2 = createHash2("sha256").update(`${start.cwd}\0${start.argv.join("\0")}`).digest();
+  return AUTO_PORT_FIRST + digest2.readUInt32BE(0) % AUTO_PORT_COUNT;
+}
+async function portIsFree(port) {
+  for (const host of ["127.0.0.1", "0.0.0.0", "::1", "::"]) {
+    const result = await new Promise((resolve) => {
+      const server = net5.createServer();
+      server.once(
+        "error",
+        (error) => resolve(error.code === "EADDRNOTAVAIL" || error.code === "EAFNOSUPPORT" ? "absent" : "taken")
+      );
+      server.listen({ port, host, ...host === "::" ? { ipv6Only: false } : {} }, () => server.close(() => resolve("free")));
+    });
+    if (result === "taken") return false;
+  }
+  return true;
+}
+function startedSiteRuns(entry) {
+  return Boolean(entry.startedPid && entry.startedPid > 0 && entry.startedCommand) && readProcessCommandLine(entry.startedPid) === entry.startedCommand;
+}
+async function siteOnPort(params) {
+  const { port, start, root, projectId: projectId2, previews, procRoot } = params;
+  if (await portIsFree(port)) return "none";
+  if (previews.some(
+    (entry) => entry.projectId === projectId2 && entry.localPort === port && sameStart(entry.start, start) && startedSiteRuns(entry)
+  )) {
+    return "same";
+  }
+  const listening = detectListeningProcess(port, procRoot);
+  if (listening && workspaceRelativeDir(root, listening.cwd) === start.cwd && sameArgv(listening.argv, withPort(start.argv, port))) {
+    return "same";
+  }
+  return "other";
+}
+function portTakenError(port, previews, projectId2) {
+  const holder = previews.find((entry) => entry.projectId === projectId2 && entry.localPort === port && entry.title);
+  const what = holder ? `Port ${port} already shows '${holder.title}'.` : `Port ${port} is in use by another server.`;
+  return new PreviewCommandError(`${what} Leave out --port: --start picks a free port for this site.`, PREVIEW_EXIT_PORT_NOT_ALLOWED);
+}
+async function startOrFindSite(params) {
+  const { explicitPort, start, root, projectId: projectId2, title, sitePath, procRoot, log } = params;
+  const { previews } = readStateFile2();
+  const onPort = (port) => siteOnPort({ port, start, root, projectId: projectId2, previews, procRoot });
+  const launch = async (port) => {
+    const serve = { argv: withPort(start.argv, port), cwd: start.cwd };
+    const started = await startPreviewSite({ port, sitePath, serve, root, timeoutMs: params.timeoutMs });
+    log(`Started the site on port ${port} (pid ${started.pid}); log: ${displayPath(started.logFile)}`);
+    return { port, start, started: { ...started, command: readProcessCommandLine(started.pid) } };
+  };
+  if (explicitPort !== null) {
+    const found = await onPort(explicitPort);
+    if (found === "same") return { port: explicitPort, start, started: null };
+    if (found === "other") throw portTakenError(explicitPort, previews, projectId2);
+    return launch(explicitPort);
+  }
+  const tried = /* @__PURE__ */ new Set();
+  const known = previews.find((entry) => entry.projectId === projectId2 && sameStart(entry.start, start));
+  if (known) {
+    tried.add(known.localPort);
+    const found = await onPort(known.localPort);
+    if (found === "same") return { port: known.localPort, start, started: null };
+    if (found === "none") return launch(known.localPort);
+  }
+  const reserved = reservedPreviewPorts();
+  const held = new Set(
+    previews.filter((entry) => entry.projectId !== projectId2 || !sameStart(entry.start, start)).map((entry) => entry.localPort)
+  );
+  for (const [port, holder] of await params.openPorts()) {
+    if (holder !== title) held.add(port);
+  }
+  const first = preferredSitePort(start);
+  for (let index = 0; index < AUTO_PORT_TRIES; index += 1) {
+    const port = AUTO_PORT_FIRST + (first - AUTO_PORT_FIRST + index) % AUTO_PORT_COUNT;
+    if (tried.has(port) || reserved.has(port) || held.has(port)) continue;
+    tried.add(port);
+    const found = await onPort(port);
+    if (found === "same") return { port, start, started: null };
+    if (found === "none") return launch(port);
+  }
+  throw new PreviewCommandError(
+    `No free port was found for the site: ${tried.size} ports from ${first} are taken. Stop a site this space no longer needs (instafy preview close <previewId>), then retry.`,
+    PREVIEW_EXIT_NOT_LISTENING
+  );
+}
+async function stopSite(pid, command) {
+  if (!pid || pid <= 0 || !command) return false;
+  const ours = () => readProcessCommandLine(pid) === command;
+  if (!ours()) return false;
+  const signal = (name) => {
+    try {
+      process.kill(-pid, name);
+    } catch {
+      try {
+        process.kill(pid, name);
+      } catch {
+      }
+    }
+  };
+  signal("SIGTERM");
+  if (!await waitForProcessExit(pid, 4e3) && ours()) signal("SIGKILL");
+  return true;
+}
+function siteRecordFor(site, previews, port, projectId2) {
+  if (site?.started) {
+    return { start: site.start, startedPid: site.started.pid, ...site.started.command ? { startedCommand: site.started.command } : {} };
+  }
+  const earlier = previews.find(
+    (entry) => entry.projectId === projectId2 && entry.localPort === port && (!site || sameStart(entry.start, site.start)) && startedSiteRuns(entry)
+  );
+  if (earlier) return { start: earlier.start, startedPid: earlier.startedPid, startedCommand: earlier.startedCommand };
+  return site ? { start: site.start } : {};
+}
+async function openPreviewPorts(params) {
+  const ports = /* @__PURE__ */ new Map();
+  let rows = [];
+  try {
+    const listed = await controllerRequest({
+      controllerUrl: params.controllerUrl,
+      auth: params.auth,
+      method: "GET",
+      route: previewsRoute(params.projectId),
+      retryCommand: "instafy preview list",
+      notFoundMeansUnavailable: true,
+      timeoutMs: 1e4
+    });
+    rows = Array.isArray(listed.body) ? listed.body : [];
+  } catch (error) {
+    if (error instanceof PreviewCommandError && error.exitCode === PREVIEW_EXIT_UNAVAILABLE) throw error;
+    return ports;
+  }
+  const runtimeId = readEnv("RUNTIME_ID");
+  for (const raw of rows) {
+    if (!raw || typeof raw !== "object") continue;
+    const record2 = raw;
+    const onRuntime = stringField(record2, "runtimeId");
+    if (runtimeId && onRuntime && onRuntime !== runtimeId) continue;
+    const port = numberField(record2, "port");
+    if (port) ports.set(port, stringField(record2, "title") ?? "");
+  }
+  return ports;
+}
 async function createAndStartClient(params) {
-  const { opts, port, title, sitePath, projectId: projectId2, retryCommand, auth, controllerUrl, serverUrl, log, serve } = params;
+  const { opts, port, title, sitePath, projectId: projectId2, retryCommand, auth, controllerUrl, serverUrl, log, serve, site, portPicked } = params;
   const conversationId = opts.conversationId?.trim() || void 0;
   const created = await controllerRequest({
     controllerUrl,
@@ -10655,10 +11062,12 @@ async function createAndStartClient(params) {
       title,
       ...opts.summary ? { summary: opts.summary } : {},
       metadata: { source: "instafy-cli" },
-      ...serve ? { serve } : {}
+      ...serve ? { serve } : {},
+      ...opts.replace ? { replace: true } : {}
     },
     retryCommand,
-    notFoundMeansUnavailable: true
+    notFoundMeansUnavailable: true,
+    ...portPicked ? { portTakenHint: PICKED_PORT_TAKEN_HINT } : {}
   });
   const grant = created.body && !Array.isArray(created.body) ? created.body : {};
   const previewId = stringField(grant, "previewId");
@@ -10672,6 +11081,7 @@ async function createAndStartClient(params) {
   const studioOrigin = parseStudioOrigin(grant["studioOrigin"]);
   const state = readStateFile2();
   const current = state.previews.find((preview) => preview.previewId === previewId) ?? null;
+  const siteRecord = siteRecordFor(site, state.previews, port, projectId2);
   let pid = null;
   let binary = current?.binary;
   try {
@@ -10735,47 +11145,88 @@ ${started.logTail}` : "";
     startedAt: current?.pid === pid ? current.startedAt : (/* @__PURE__ */ new Date()).toISOString(),
     ...binary ? { binary } : {},
     ...hostSuffix ? { hostSuffix } : {},
-    ...studioOrigin ? { studioOrigin } : {}
+    ...studioOrigin ? { studioOrigin } : {},
+    ...siteRecord,
+    ...serve ? { siteDir: serve.cwd } : {},
+    // The same preview opened again keeps its picture until a new one is uploaded.
+    ...current?.pictureAt ? { pictureAt: current.pictureAt } : {},
+    ...opts.thumbnail === false ? { noThumbnail: true } : {}
   };
   upsertPreviewState(entry);
   return { grant, previewId, entry, current };
 }
 async function previewOpen(opts) {
-  const port = parsePreviewPort(opts.port);
+  const explicitPort = opts.port === void 0 || String(opts.port).trim() === "" ? null : parsePreviewPort(opts.port);
   const title = parsePreviewTitle(opts.title);
   const sitePath = parsePreviewPath(opts.path);
   const summary = parsePreviewSummary(opts.summary);
-  if (opts.serveCmd?.trim()) parseExplicitServeCommand(opts.serveCmd);
+  const serveArgv = opts.serveCmd?.trim() ? parseExplicitServeCommand(opts.serveCmd) : null;
+  if (opts.start && !serveArgv) {
+    throw new PreviewCommandError('--start needs --serve-cmd "<command>" to start the site.', PREVIEW_EXIT_NOT_LISTENING);
+  }
+  if (explicitPort === null) {
+    if (!opts.start) {
+      throw new Error(`A port is required: --port <port>. Or start the site with --start and --serve-cmd, which picks a free port.`);
+    }
+    if (!serveArgv.some((arg) => arg.includes(PORT_PLACEHOLDER))) {
+      throw new Error(
+        `--serve-cmd needs ${PORT_PLACEHOLDER} where the site's port goes, e.g. --serve-cmd "python3 -m http.server ${PORT_PLACEHOLDER} --bind 127.0.0.1": --start picks the port.`
+      );
+    }
+  }
   const projectId2 = resolveProject({ project: opts.project });
-  const retryCommand = `instafy preview open --port ${port} --title ${shellQuote2(title)}`;
+  const retryCommand = `instafy preview open${explicitPort === null ? "" : ` --port ${explicitPort}`} --title ${shellQuote2(title)}`;
   const { auth, controllerUrl } = resolveAuth(opts, retryCommand);
   const serverUrl = cleanUrl(controllerUrl);
   const log = (message) => console.error(kleur8.cyan(message));
-  const explicitServe = opts.start && opts.serveCmd?.trim() ? resolvePreviewServe({ port, serveCmd: opts.serveCmd, projectId: projectId2, cwd: opts.cwd }).serve : null;
-  let probe = await probeLocalSite(port, sitePath, void 0, RATHOLE_LOCAL_HOSTS);
-  let started = null;
-  if (!probe.listening && opts.start && probe.status === null && !probe.timedOut) {
-    const ipv6 = await probeLocalSite(port, sitePath, void 0, ["::1"]);
-    if (ipv6.status === null && !ipv6.timedOut) {
-      if (!explicitServe) {
-        throw new PreviewCommandError(
-          `Nothing answers on 127.0.0.1:${port}, and --start needs --serve-cmd "<command>" to start the site.`,
-          PREVIEW_EXIT_NOT_LISTENING
-        );
+  const start = opts.start ? resolvePreviewServe({ port: explicitPort ?? 0, serveCmd: opts.serveCmd, projectId: projectId2, cwd: opts.cwd }).serve : null;
+  const { grant, previewId, entry, port, site, serve, restartNote } = await withStateLock(async () => {
+    const site2 = start ? await startOrFindSite({
+      explicitPort,
+      start,
+      root: resolveWorkspaceRoot(process.env, projectId2),
+      projectId: projectId2,
+      title,
+      sitePath,
+      timeoutMs: opts.startTimeoutMs,
+      procRoot: opts.procRoot,
+      openPorts: () => openPreviewPorts({ controllerUrl, auth, projectId: projectId2 }),
+      log
+    }) : null;
+    const port2 = site2?.port ?? explicitPort;
+    try {
+      const probe = await probeLocalSite(port2, sitePath, void 0, RATHOLE_LOCAL_HOSTS);
+      if (!probe.listening) {
+        throw await notListeningError(port2, sitePath, probe);
       }
-      const root = resolveWorkspaceRoot(process.env, projectId2);
-      started = await startPreviewSite({ port, sitePath, serve: explicitServe, root, timeoutMs: opts.startTimeoutMs });
-      log(`Started the site (pid ${started.pid}); log: ${displayPath(started.logFile)}`);
-      probe = await probeLocalSite(port, sitePath, void 0, RATHOLE_LOCAL_HOSTS);
+      const { serve: serve2, note } = resolvePreviewServe({
+        port: port2,
+        serveCmd: opts.serveCmd?.split(PORT_PLACEHOLDER).join(String(port2)),
+        projectId: projectId2,
+        cwd: opts.cwd,
+        procRoot: opts.procRoot
+      });
+      const created = await createAndStartClient({
+        opts: { ...opts, summary },
+        port: port2,
+        title,
+        sitePath,
+        projectId: projectId2,
+        retryCommand,
+        auth,
+        controllerUrl,
+        serverUrl,
+        log,
+        serve: serve2,
+        site: site2,
+        portPicked: explicitPort === null
+      });
+      return { ...created, port: port2, site: site2, serve: serve2, restartNote: note };
+    } catch (error) {
+      if (site2?.started) await stopSite(site2.started.pid, site2.started.command ?? readProcessCommandLine(site2.started.pid));
+      throw error;
     }
-  }
-  if (!probe.listening) {
-    throw await notListeningError(port, sitePath, probe);
-  }
-  const { serve, note: restartNote } = resolvePreviewServe({ port, serveCmd: opts.serveCmd, projectId: projectId2, cwd: opts.cwd });
-  const { grant, previewId, entry } = await withStateLock(
-    () => createAndStartClient({ opts: { ...opts, summary }, port, title, sitePath, projectId: projectId2, retryCommand, auth, controllerUrl, serverUrl, log, serve })
-  );
+  });
   let ready;
   try {
     ready = await controllerRequest({
@@ -10805,8 +11256,10 @@ async function previewOpen(opts) {
     thumbnail = { status: "skipped", reason: "the site is not live through the preview yet" };
   } else {
     if (!opts.thumbnailFile) log("Taking a picture of the site for its card\u2026");
+    const takenAt = Date.now();
     const attempt2 = opts.thumbnailFile ? readThumbnailFile(opts.thumbnailFile) : await captureSiteThumbnail({ port, path: sitePath, host: "127.0.0.1" });
     thumbnail = "thumbnail" in attempt2 ? await uploadPreviewThumbnail({ controllerUrl, auth, projectId: projectId2, previewId, thumbnail: attempt2.thumbnail, retryCommand }) : { status: attempt2.status, reason: attempt2.reason };
+    if (thumbnail.status === "uploaded" || !opts.thumbnailFile) await recordPictured(previewId, takenAt);
   }
   return {
     previewId,
@@ -10819,7 +11272,7 @@ async function previewOpen(opts) {
     viewerHostSuffix: parseViewerHostSuffix(grant["viewerHostSuffix"]) ?? null,
     restartable,
     ...restartable ? {} : { restartNote: restartNote ?? "the server did not record a start command" },
-    ...opts.start ? { startedPid: started?.pid ?? null, logFile: started?.logFile ?? null } : {},
+    ...opts.start ? { startedPid: site?.started?.pid ?? null, logFile: site?.started?.logFile ?? null } : {},
     thumbnail: thumbnail.status,
     ...thumbnail.reason ? { thumbnailReason: thumbnail.reason } : {}
   };
@@ -10850,12 +11303,30 @@ async function uploadPreviewThumbnail(params) {
     return { status: "failed", reason: message.slice(0, 300) };
   }
 }
+var PICTURE_RECORD_LOCK_WAIT_MS = 5e3;
+async function recordPictured(previewId, takenAt) {
+  try {
+    await withStateLock(async () => {
+      const state = readStateFile2();
+      const entry = state.previews.find((preview) => preview.previewId === previewId);
+      if (!entry || (entry.pictureAt ?? 0) >= takenAt) return;
+      entry.pictureAt = takenAt;
+      writeStateFile2(state);
+    }, PICTURE_RECORD_LOCK_WAIT_MS);
+  } catch {
+  }
+}
 function openPreviewFor(port, sitePath) {
-  return readStateFile2().previews.find((entry) => entry.localPort === port && entry.path === sitePath && entry.pid > 0) ?? null;
+  const entry = readStateFile2().previews.find((preview) => preview.localPort === port && preview.path === sitePath && preview.pid > 0);
+  return entry && !entry.noThumbnail ? entry : null;
 }
 function hasOpenPreviewFor(port, sitePath) {
   return openPreviewFor(port, sitePath) !== null;
 }
+async function recordCheckPictureTried(input3) {
+  const entry = openPreviewFor(input3.port, input3.path);
+  if (entry) await recordPictured(entry.previewId, input3.takenAt);
+}
 async function uploadCheckThumbnail(input3) {
   const entry = openPreviewFor(input3.port, input3.path);
   if (!entry) return null;
@@ -10870,9 +11341,13 @@ async function uploadCheckThumbnail(input3) {
   if (cleanUrl(controllerUrl) !== cleanUrl(entry.controllerUrl)) {
     return { status: "skipped", reason: "the preview was opened on another server" };
   }
+  const takenAt = input3.takenAt ?? Date.now();
   const facts = sniffImage(input3.image);
-  if (!facts) return { status: "skipped", reason: "the picture is not a JPEG" };
-  return uploadPreviewThumbnail({
+  if (!facts) {
+    await recordPictured(entry.previewId, takenAt);
+    return { status: "skipped", reason: "the picture is not a JPEG" };
+  }
+  const outcome = await uploadPreviewThumbnail({
     controllerUrl,
     auth,
     projectId: entry.projectId,
@@ -10880,6 +11355,8 @@ async function uploadCheckThumbnail(input3) {
     thumbnail: { image: input3.image, ...facts, source: "capture", description: input3.description },
     retryCommand
   });
+  await recordPictured(entry.previewId, takenAt);
+  return outcome;
 }
 function toPreviewSummary(raw) {
   if (!raw || typeof raw !== "object") return null;
@@ -10914,9 +11391,13 @@ async function previewClose(opts) {
   if (!previewId) {
     throw new Error("Preview id is required. Use `instafy preview list` to find it.");
   }
+  let siteStopped = false;
   const entry = await withStateLock(async () => {
     const removed = removePreviewState(previewId);
-    if (removed) await stopClient(removed);
+    if (removed) {
+      await stopClient(removed);
+      siteStopped = await stopSite(removed.startedPid, removed.startedCommand);
+    }
     return removed;
   });
   const projectId2 = entry?.projectId ?? resolveProject({ project: opts.project });
@@ -10927,11 +11408,14 @@ async function previewClose(opts) {
     );
     await closePreviewOnServer(controllerUrl, auth, projectId2, previewId);
   } catch (error) {
-    if (entry) await withStateLock(async () => upsertPreviewState({ ...entry, pid: -1 }));
+    if (entry) {
+      const { startedPid: _pid, startedCommand: _command, ...rest } = entry;
+      await withStateLock(async () => upsertPreviewState({ ...siteStopped ? rest : entry, pid: -1 }));
+    }
     throw error;
   }
   removeWorkdir(previewId);
-  return { ok: true, previewId };
+  return { ok: true, previewId, siteStopped };
 }
 function printPreviewOpen(result, json) {
   if (json) {
@@ -10939,7 +11423,7 @@ function printPreviewOpen(result, json) {
     return;
   }
   const label = result.status === "live" ? kleur8.green("Ready to preview") : result.status === "not_responding" ? kleur8.yellow("Not responding yet") : kleur8.yellow("Preview opened (the server did not report whether the site answers)");
-  console.log(`${label}: ${result.title} (port ${result.port}). Open it from the card in the conversation.`);
+  console.log(`${label}: ${result.title} (port ${result.port}). Its card is in the conversation.`);
   if (result.thumbnail === "uploaded") {
     console.log(kleur8.gray("The card shows a picture of the site; `instafy preview check` takes a new one after a change."));
   } else {
@@ -10948,7 +11432,7 @@ function printPreviewOpen(result, json) {
   if (result.startedPid) {
     console.log(kleur8.gray(`Started the site in the background (pid ${result.startedPid}); log: ${displayPath(result.logFile ?? "")}`));
   } else if (result.startedPid === null) {
-    console.log(kleur8.gray("The site was already running; nothing was started."));
+    console.log(kleur8.gray("This site was already running on its port; nothing was started."));
   }
   if (result.restartable) {
     console.log(kleur8.gray("Open starts the site again when the process that started it exits, or the space sleeps."));
@@ -11115,7 +11599,7 @@ init_config();
 
 // src/git-wrapper.ts
 import { spawnSync as spawnSync5 } from "node:child_process";
-import { randomUUID as randomUUID2 } from "node:crypto";
+import { randomUUID as randomUUID3 } from "node:crypto";
 import fs13 from "node:fs";
 import path14 from "node:path";
 import kleur10 from "kleur";
@@ -11329,10 +11813,10 @@ function hideEmbeddedGitDirs(context, pathSpecs) {
   fs13.mkdirSync(stagingBase, { recursive: true });
   const renames = [];
   for (const candidate of candidates) {
-    let hidden = path14.join(stagingBase, randomUUID2());
+    let hidden = path14.join(stagingBase, randomUUID3());
     for (let attempt2 = 0; attempt2 < 8; attempt2 += 1) {
       if (!pathExists(hidden)) break;
-      hidden = path14.join(stagingBase, randomUUID2());
+      hidden = path14.join(stagingBase, randomUUID3());
     }
     fs13.renameSync(candidate, hidden);
     renames.push({ original: candidate, hidden });
@@ -11888,19 +12372,324 @@ function notSavedSentences(report, options) {
       sentences.push(report.recoveryRef ? `Not saved: ${trimmed} (kept at ${report.recoveryRef})` : `Not saved: ${trimmed}`);
     }
   }
-  return sentences;
-}
-function saveReportJson(report, notSaved) {
-  return {
-    rev: report.rev,
-    baseRev: report.baseRev,
-    gitSyncStatus: report.gitSyncStatus,
-    recoveryRef: report.recoveryRef,
-    conflictedPaths: report.conflictedPaths,
-    rejectedPaths: report.rejectedPaths,
-    unpushedRefs: report.unpushedRefs,
-    notSaved
-  };
+  return sentences;
+}
+function saveReportJson(report, notSaved) {
+  return {
+    rev: report.rev,
+    baseRev: report.baseRev,
+    gitSyncStatus: report.gitSyncStatus,
+    recoveryRef: report.recoveryRef,
+    conflictedPaths: report.conflictedPaths,
+    rejectedPaths: report.rejectedPaths,
+    unpushedRefs: report.unpushedRefs,
+    notSaved
+  };
+}
+
+// src/api.ts
+init_config();
+init_errors();
+init_controller_fetch();
+import fs14 from "node:fs";
+function normalizeUrl5(raw) {
+  const value = (raw ?? "").trim();
+  if (!value) return "http://127.0.0.1:8788";
+  return value.replace(/\/$/, "");
+}
+function normalizeToken6(raw) {
+  if (!raw) return null;
+  const trimmed = raw.trim();
+  return trimmed.length ? trimmed : null;
+}
+function resolveBearerTokenWithSource(options) {
+  const cwd = process.cwd();
+  const profile = resolveActiveProfileName({ cwd });
+  const stored = resolveConfiguredAccessToken({ profile, cwd });
+  const explicit = normalizeToken6(options.accessToken);
+  if (explicit) {
+    return { token: explicit, source: "explicit", profile, runtimeControllerUrl: null };
+  }
+  const runtimeCredential = resolveRuntimeControllerCredential();
+  if (runtimeCredential) {
+    return {
+      token: runtimeCredential.token,
+      source: "env",
+      profile: null,
+      runtimeControllerUrl: runtimeCredential.controllerUrl
+    };
+  }
+  const envKeys = [
+    "INSTAFY_ACCESS_TOKEN",
+    "SUPABASE_ACCESS_TOKEN"
+  ];
+  for (const key of envKeys) {
+    const value = normalizeToken6(process.env[key]);
+    if (value) {
+      return { token: value, source: "env", profile, runtimeControllerUrl: null };
+    }
+  }
+  if (stored) {
+    return { token: stored, source: "config", profile, runtimeControllerUrl: null };
+  }
+  return { token: null, source: "none", profile, runtimeControllerUrl: null };
+}
+function parseKeyValue(raw) {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    throw new Error("Key/value pair cannot be empty");
+  }
+  const equals = trimmed.indexOf("=");
+  if (equals === -1) {
+    return { key: trimmed, value: "" };
+  }
+  const key = trimmed.slice(0, equals).trim();
+  const value = trimmed.slice(equals + 1).trim();
+  if (!key) {
+    throw new Error(`Invalid pair "${raw}" (missing key)`);
+  }
+  return { key, value };
+}
+function parseHeader(raw) {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    throw new Error("Header cannot be empty");
+  }
+  const colon = trimmed.indexOf(":");
+  if (colon !== -1) {
+    const key = trimmed.slice(0, colon).trim();
+    const value = trimmed.slice(colon + 1).trim();
+    if (!key) {
+      throw new Error(`Invalid header "${raw}" (missing name)`);
+    }
+    return { key, value };
+  }
+  return parseKeyValue(trimmed);
+}
+function parseJsonBody(options) {
+  if (options.jsonFile) {
+    const raw = fs14.readFileSync(options.jsonFile, "utf8");
+    const parsed = JSON.parse(raw);
+    return JSON.stringify(parsed);
+  }
+  if (options.json) {
+    const parsed = JSON.parse(options.json);
+    return JSON.stringify(parsed);
+  }
+  return void 0;
+}
+function buildRequestUrl(options, runtimeControllerUrl) {
+  const selectedControllerUrl = options.controllerUrl ?? runtimeControllerUrl;
+  const base = new URL(
+    `${normalizeUrl5(resolveControllerUrl({ controllerUrl: selectedControllerUrl ?? null }))}/`
+  );
+  if (base.protocol !== "http:" && base.protocol !== "https:") {
+    throw new Error("The configured controller URL must use http or https.");
+  }
+  if (base.username || base.password) {
+    throw new Error("The configured controller URL must not contain embedded credentials.");
+  }
+  if (runtimeControllerUrl) {
+    resolveRuntimeBoundControllerUrl(
+      { controllerUrl: runtimeControllerUrl },
+      base.toString()
+    );
+  }
+  const rawPath = options.path.trim();
+  if (!rawPath) {
+    throw new Error("Path is required");
+  }
+  const isAbsoluteReference = /^[a-z][a-z\d+.-]*:/i.test(rawPath) || rawPath.startsWith("//");
+  const url = new URL(
+    isAbsoluteReference ? rawPath : rawPath.startsWith("/") ? rawPath : `/${rawPath}`,
+    base
+  );
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error("Controller API URLs must use http or https.");
+  }
+  if (url.username || url.password) {
+    throw new Error("Controller API URLs must not contain embedded credentials.");
+  }
+  const crossOrigin = url.origin !== base.origin;
+  if (crossOrigin && !options.allowCrossOrigin) {
+    throw new Error(
+      "Refusing a cross-origin controller API request. Set --server-url to that origin and use a relative path, or pass --allow-cross-origin only when you explicitly intend to send credentials and request data there."
+    );
+  }
+  for (const pair of options.query ?? []) {
+    const { key, value } = parseKeyValue(pair);
+    url.searchParams.set(key, value);
+  }
+  return { url, crossOrigin };
+}
+function maybePrettyPrintJson(text2, pretty) {
+  if (!pretty) return text2;
+  if (!text2.trim()) return text2;
+  try {
+    return JSON.stringify(JSON.parse(text2), null, 2);
+  } catch {
+    return text2;
+  }
+}
+async function executeControllerApiRequest(options, bodyOverride) {
+  const resolved = resolveBearerTokenWithSource(options);
+  const { url, crossOrigin } = buildRequestUrl(options, resolved.runtimeControllerUrl);
+  const bearer = resolved.token;
+  if (crossOrigin && (!bearer || resolved.source !== "explicit")) {
+    throw new Error(
+      "Cross-origin controller API requests require --allow-cross-origin and an explicit --access-token."
+    );
+  }
+  const headers = new Headers();
+  headers.set("accept", "application/json");
+  for (const header of options.headers ?? []) {
+    const { key, value } = parseHeader(header);
+    headers.set(key, value);
+  }
+  const body = bodyOverride ?? parseJsonBody(options);
+  if (body !== void 0 && !headers.has("content-type")) {
+    headers.set("content-type", "application/json");
+  }
+  const init = {
+    method: options.method,
+    headers,
+    body,
+    redirect: "error"
+  };
+  const response = bearer ? (await fetchWithControllerAuth({
+    url: url.toString(),
+    init,
+    accessToken: bearer,
+    tokenSource: resolved.source,
+    profile: resolved.profile,
+    cwd: process.cwd()
+  })).response : await fetch(url, init);
+  const responseText = await response.text().catch(() => "");
+  const contentType = response.headers.get("content-type") ?? "";
+  const isJson = contentType.includes("application/json") || contentType.includes("+json");
+  if (!response.ok) {
+    if (response.status === 401 || response.status === 403) {
+      throw formatAuthRejectedError({
+        status: response.status,
+        responseBody: responseText,
+        retryCommand: "instafy login",
+        advancedHint: "pass --access-token, or set INSTAFY_ACCESS_TOKEN / SUPABASE_ACCESS_TOKEN"
+      });
+    }
+    const formattedBody = isJson ? maybePrettyPrintJson(responseText, true) : responseText;
+    const prefix = `Request failed (${response.status} ${response.statusText})`;
+    const suffix = formattedBody.trim() ? `: ${formattedBody}` : "";
+    throw new Error(`${prefix}${suffix}`);
+  }
+  return { response, responseText, isJson };
+}
+async function requestControllerApiJson(options) {
+  const body = options.jsonBody === void 0 ? void 0 : JSON.stringify(options.jsonBody);
+  const { responseText, isJson } = await executeControllerApiRequest(
+    {
+      method: options.method,
+      path: options.path,
+      controllerUrl: options.controllerUrl,
+      accessToken: options.accessToken,
+      serviceToken: options.serviceToken,
+      query: options.query,
+      headers: options.headers,
+      allowCrossOrigin: options.allowCrossOrigin
+    },
+    body
+  );
+  if (!isJson) {
+    throw new Error("Expected JSON response from controller API");
+  }
+  return JSON.parse(responseText);
+}
+async function requestControllerApi(options) {
+  const { responseText, isJson } = await executeControllerApiRequest(options);
+  const pretty = options.pretty !== false;
+  const formattedBody = isJson ? maybePrettyPrintJson(responseText, pretty) : responseText;
+  if (formattedBody) console.log(formattedBody);
+}
+
+// src/research-settings.ts
+init_project_manifest();
+var fields = [
+  { key: "maxPageLoads", label: "Fresh pages per task" },
+  { key: "maxPageLoadsPerSite", label: "Fresh pages per site per task" }
+];
+function integer(raw, label) {
+  if (!/^[1-9]\d*$/.test(raw.trim()) || !Number.isSafeInteger(Number(raw))) {
+    throw new Error(`${label} must be a positive whole number.`);
+  }
+  return Number(raw);
+}
+async function researchSettings(options) {
+  const patch = {};
+  for (const field of fields) {
+    if (options[field.key] !== void 0) patch[field.key] = integer(options[field.key], field.label);
+  }
+  if (options.interactive) {
+    if (options.json || Object.keys(patch).length) throw new Error("Use --interactive without --json or setting flags.");
+    if (!process.stdin.isTTY || !process.stdout.isTTY || process.env.CI === "true") {
+      throw new Error("--interactive requires a terminal. Use --max-page-loads and --max-page-loads-per-site instead.");
+    }
+  }
+  const project = [options.project, process.env.SPACE_ID, process.env.INSTAFY_SPACE_ID, process.env.PROJECT_ID, process.env.INSTAFY_PROJECT_ID].map((value) => value?.trim()).find(Boolean) ?? findProjectManifest(process.cwd()).manifest?.spaceId;
+  if (!project) throw new Error("No space configured. Pass --space, set SPACE_ID, or run `instafy space init`.");
+  const request = {
+    path: `/projects/${encodeURIComponent(project)}/research-settings`,
+    controllerUrl: options.controllerUrl,
+    accessToken: options.accessToken
+  };
+  let settings = await requestControllerApiJson({ ...request, method: "GET" });
+  if ((options.interactive || Object.keys(patch).length) && !settings.canManage) {
+    throw new Error("Only space managers can change research settings.");
+  }
+  for (const field of fields) {
+    if (!settings.limits?.[field.key] || !Number.isInteger(settings[field.key])) {
+      throw new Error("This controller does not support research settings. Update it before changing the budget.");
+    }
+  }
+  if (options.interactive) {
+    const { isCancel, text: text2 } = await import("@clack/prompts");
+    console.log("The parent and its helpers share one budget. Changes apply to new tasks; running tasks retain their allowance.");
+    for (const field of fields) {
+      const bounds = settings.limits[field.key];
+      const entered = await text2({
+        message: `${field.label} (${bounds.min}\u2013${bounds.max}; default ${bounds.default})`,
+        defaultValue: String(settings[field.key]),
+        placeholder: String(settings[field.key]),
+        validate(raw) {
+          try {
+            const value2 = integer(raw || String(settings[field.key]), field.label);
+            if (value2 < bounds.min || value2 > bounds.max) return `Enter a whole number from ${bounds.min} to ${bounds.max}.`;
+            if (field.key === "maxPageLoadsPerSite" && value2 > (patch.maxPageLoads ?? settings.maxPageLoads)) return "The per-site limit cannot exceed the task limit.";
+          } catch (error) {
+            return error.message;
+          }
+        }
+      });
+      if (isCancel(entered)) throw new Error("Cancelled. No settings were changed.");
+      const value = integer(String(entered), field.label);
+      if (value !== settings[field.key]) patch[field.key] = value;
+    }
+  }
+  for (const field of fields) {
+    const value = patch[field.key];
+    const bounds = settings.limits[field.key];
+    if (value !== void 0 && (value < bounds.min || value > bounds.max)) throw new Error(`${field.label} must be between ${bounds.min} and ${bounds.max}.`);
+  }
+  if ((patch.maxPageLoadsPerSite ?? settings.maxPageLoadsPerSite) > (patch.maxPageLoads ?? settings.maxPageLoads)) {
+    throw new Error("The per-site limit cannot exceed the task limit.");
+  }
+  if (Object.keys(patch).length) settings = await requestControllerApiJson({ ...request, method: "PATCH", jsonBody: patch });
+  if (options.json) {
+    console.log(JSON.stringify(settings, null, 2));
+    return;
+  }
+  console.log(`Research budget for space ${project}`);
+  for (const field of fields) console.log(`${field.label}: ${settings[field.key]}`);
+  console.log("Shared by the parent and all helpers, including continued worker jobs. Cached reads are free. Changes apply to new tasks.");
+  if (!settings.canManage) console.log("Read-only: only space managers can change this budget.");
 }
 
 // src/web-link.ts
@@ -11971,9 +12760,9 @@ function registerWebLinkCommand(web) {
 // src/web-search.ts
 var redaction2 = __toESM(require_redaction(), 1);
 import dns3 from "node:dns";
-import fs14 from "node:fs";
+import fs15 from "node:fs";
 import https2 from "node:https";
-import net5 from "node:net";
+import net6 from "node:net";
 import path15 from "node:path";
 import zlib2 from "node:zlib";
 
@@ -12180,7 +12969,7 @@ function compileProvider(id, raw) {
   if (url.protocol !== "https:") return `${id}: request.url must be https`;
   if (url.username || url.password || url.port && url.port !== "443" || url.hash) return `${id}: request.url must be a plain https address`;
   const host = langInHost ? url.hostname.toLowerCase().replace(/^xx\./, "") : url.hostname.toLowerCase();
-  if (net5.isIP(host.replace(/^\[|\]$/g, "")) || isLocalHostName(host)) return `${id}: request.url must name a public host`;
+  if (net6.isIP(host.replace(/^\[|\]$/g, "")) || isLocalHostName(host)) return `${id}: request.url must name a public host`;
   const never = NEVER_HOSTS.find((entry) => host === entry.host || host.endsWith(`.${entry.host}`));
   if (never) return `${id}: ${never.host} is never used (${never.why})`;
   if (/[{}]/.test(decodeURIComponent(url.href))) return `${id}: request.url may not hold placeholders`;
@@ -12303,9 +13092,9 @@ function compileProvider(id, raw) {
 }
 function resultLink(value) {
   if (typeof value === "string" && value.startsWith("https://")) {
-    const fields = [...value.matchAll(/\{([\w-]+(?:\.[\w-]+)*)\}/g)];
+    const fields2 = [...value.matchAll(/\{([\w-]+(?:\.[\w-]+)*)\}/g)];
     const rest = value.replace(/\{([\w-]+(?:\.[\w-]+)*)\}/g, "");
-    if (!fields.length || /[{}]/.test(rest)) return void 0;
+    if (!fields2.length || /[{}]/.test(rest)) return void 0;
     try {
       new URL(value.replace(/\{[^}]*\}/g, "x"));
     } catch {
@@ -12363,8 +13152,8 @@ function loadSearchProviders(bundled = BUNDLED_SEARCH_PROVIDERS, copies = []) {
   return { providers, chains, off: [...off].filter((id) => id in bundled.providers).sort(), keyEnvs: [...keyEnvs], warnings };
 }
 function fill(template, vars) {
-  const whole = /^\{([a-z]+)\}$/.exec(template);
-  if (whole && whole[1] === "count") return vars.count;
+  const whole2 = /^\{([a-z]+)\}$/.exec(template);
+  if (whole2 && whole2[1] === "count") return vars.count;
   let missing = false;
   const out = template.replace(/\{\{|\}\}|\{([a-z]+)(?::([a-z]+))?\}/g, (match, name, encoder) => {
     if (!name) return match[0];
@@ -12453,7 +13242,7 @@ function sendOnce(request, target, timeoutMs) {
         port: target.port,
         method: request.method,
         path: `${request.url.pathname}${request.url.search}`,
-        servername: net5.isIP(hostname) ? void 0 : hostname,
+        servername: net6.isIP(hostname) ? void 0 : hostname,
         agent: false,
         maxHeaderSize: 64 * 1024,
         headers: { Host: request.url.host, ...request.headers, ...payload ? { "Content-Length": String(payload.length) } : {} }
@@ -12503,8 +13292,8 @@ function at(value, field) {
   }
   return current;
 }
-function firstText(item, fields) {
-  for (const field of fields) {
+function firstText(item, fields2) {
+  for (const field of fields2) {
     const value = at(item, field);
     if (typeof value === "string" && value.trim()) return value;
   }
@@ -12520,10 +13309,10 @@ function withoutTags(text2) {
   return out;
 }
 function cleanText(raw, max) {
-  const text2 = withoutTags(raw).replace(/&(#x[0-9a-f]{1,6}|#\d{1,7}|[a-z]{2,6}|#39);/gi, (whole, name) => {
+  const text2 = withoutTags(raw).replace(/&(#x[0-9a-f]{1,6}|#\d{1,7}|[a-z]{2,6}|#39);/gi, (whole2, name) => {
     if (ENTITIES2[name.toLowerCase()]) return ENTITIES2[name.toLowerCase()];
     const code = name[0] === "#" ? name[1]?.toLowerCase() === "x" ? parseInt(name.slice(2), 16) : parseInt(name.slice(1), 10) : NaN;
-    return Number.isFinite(code) && code > 31 && code < 1114112 ? String.fromCodePoint(code) : whole;
+    return Number.isFinite(code) && code > 31 && code < 1114112 ? String.fromCodePoint(code) : whole2;
   }).replace(/</g, "\u2039").replace(/[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u202a-\u202e\u2066-\u2069\ufeff]/g, " ").replace(/\s+/g, " ").trim();
   const redacted = redaction2.redactText(text2).text;
   return redacted.length > max ? `${redacted.slice(0, max - 1)}\u2026` : redacted;
@@ -12540,7 +13329,7 @@ function resultAddress(raw) {
   if (url.username || url.password) return null;
   if (url.port && url.port !== "80" && url.port !== "443") return null;
   const host = url.hostname.replace(/^\[|\]$/g, "");
-  if (net5.isIP(host) ? isPrivateAddress(host) : isLocalHostName(host)) return null;
+  if (net6.isIP(host) ? isPrivateAddress(host) : isLocalHostName(host)) return null;
   url.hash = "";
   return url;
 }
@@ -12692,10 +13481,10 @@ var SearchState = class {
   /** Removes turn and day files older than two days. */
   prune() {
     try {
-      for (const name of fs14.readdirSync(this.dir)) {
+      for (const name of fs15.readdirSync(this.dir)) {
         if (!/^(?:search-turn|day)-[\w-]+\.json$/.test(name)) continue;
         const file = path15.join(this.dir, name);
-        if (Date.now() - fs14.statSync(file).mtimeMs > 2 * 864e5) fs14.rmSync(file, { force: true });
+        if (Date.now() - fs15.statSync(file).mtimeMs > 2 * 864e5) fs15.rmSync(file, { force: true });
       }
     } catch {
     }
@@ -12710,7 +13499,7 @@ function liveTurn(env, now) {
 }
 function keyless(chain) {
   const find = chain === DEFAULT_CHAIN ? 'find official sites with `instafy web search "<name>" --chain reference-search` (no key) and read them' : "read the official sites you know of";
-  return `Go on without it: ${find}, and the pages of publishers you know cover this, with \`instafy web read\`. Then answer or build the page with what you read, each missing fact marked unknown with why. The person may send more pages with Send page to Octo.`;
+  return `Go on without it: ${find}, and for reviews a reviewer's home page and the pages it links, with \`instafy web read\`. Then answer or build the page with what you read, each missing fact marked unknown with why. The person may send more pages with Send page to Octo.`;
 }
 function tellFor(status, chain) {
   switch (status) {
@@ -13043,229 +13832,6 @@ function registerWebSearchCommand(web) {
   return web;
 }
 
-// src/api.ts
-init_config();
-init_errors();
-init_controller_fetch();
-import fs15 from "node:fs";
-function normalizeUrl5(raw) {
-  const value = (raw ?? "").trim();
-  if (!value) return "http://127.0.0.1:8788";
-  return value.replace(/\/$/, "");
-}
-function normalizeToken6(raw) {
-  if (!raw) return null;
-  const trimmed = raw.trim();
-  return trimmed.length ? trimmed : null;
-}
-function resolveBearerTokenWithSource(options) {
-  const cwd = process.cwd();
-  const profile = resolveActiveProfileName({ cwd });
-  const stored = resolveConfiguredAccessToken({ profile, cwd });
-  const explicit = normalizeToken6(options.accessToken);
-  if (explicit) {
-    return { token: explicit, source: "explicit", profile, runtimeControllerUrl: null };
-  }
-  const runtimeCredential = resolveRuntimeControllerCredential();
-  if (runtimeCredential) {
-    return {
-      token: runtimeCredential.token,
-      source: "env",
-      profile: null,
-      runtimeControllerUrl: runtimeCredential.controllerUrl
-    };
-  }
-  const envKeys = [
-    "INSTAFY_ACCESS_TOKEN",
-    "SUPABASE_ACCESS_TOKEN"
-  ];
-  for (const key of envKeys) {
-    const value = normalizeToken6(process.env[key]);
-    if (value) {
-      return { token: value, source: "env", profile, runtimeControllerUrl: null };
-    }
-  }
-  if (stored) {
-    return { token: stored, source: "config", profile, runtimeControllerUrl: null };
-  }
-  return { token: null, source: "none", profile, runtimeControllerUrl: null };
-}
-function parseKeyValue(raw) {
-  const trimmed = raw.trim();
-  if (!trimmed) {
-    throw new Error("Key/value pair cannot be empty");
-  }
-  const equals = trimmed.indexOf("=");
-  if (equals === -1) {
-    return { key: trimmed, value: "" };
-  }
-  const key = trimmed.slice(0, equals).trim();
-  const value = trimmed.slice(equals + 1).trim();
-  if (!key) {
-    throw new Error(`Invalid pair "${raw}" (missing key)`);
-  }
-  return { key, value };
-}
-function parseHeader(raw) {
-  const trimmed = raw.trim();
-  if (!trimmed) {
-    throw new Error("Header cannot be empty");
-  }
-  const colon = trimmed.indexOf(":");
-  if (colon !== -1) {
-    const key = trimmed.slice(0, colon).trim();
-    const value = trimmed.slice(colon + 1).trim();
-    if (!key) {
-      throw new Error(`Invalid header "${raw}" (missing name)`);
-    }
-    return { key, value };
-  }
-  return parseKeyValue(trimmed);
-}
-function parseJsonBody(options) {
-  if (options.jsonFile) {
-    const raw = fs15.readFileSync(options.jsonFile, "utf8");
-    const parsed = JSON.parse(raw);
-    return JSON.stringify(parsed);
-  }
-  if (options.json) {
-    const parsed = JSON.parse(options.json);
-    return JSON.stringify(parsed);
-  }
-  return void 0;
-}
-function buildRequestUrl(options, runtimeControllerUrl) {
-  const selectedControllerUrl = options.controllerUrl ?? runtimeControllerUrl;
-  const base = new URL(
-    `${normalizeUrl5(resolveControllerUrl({ controllerUrl: selectedControllerUrl ?? null }))}/`
-  );
-  if (base.protocol !== "http:" && base.protocol !== "https:") {
-    throw new Error("The configured controller URL must use http or https.");
-  }
-  if (base.username || base.password) {
-    throw new Error("The configured controller URL must not contain embedded credentials.");
-  }
-  if (runtimeControllerUrl) {
-    resolveRuntimeBoundControllerUrl(
-      { controllerUrl: runtimeControllerUrl },
-      base.toString()
-    );
-  }
-  const rawPath = options.path.trim();
-  if (!rawPath) {
-    throw new Error("Path is required");
-  }
-  const isAbsoluteReference = /^[a-z][a-z\d+.-]*:/i.test(rawPath) || rawPath.startsWith("//");
-  const url = new URL(
-    isAbsoluteReference ? rawPath : rawPath.startsWith("/") ? rawPath : `/${rawPath}`,
-    base
-  );
-  if (url.protocol !== "http:" && url.protocol !== "https:") {
-    throw new Error("Controller API URLs must use http or https.");
-  }
-  if (url.username || url.password) {
-    throw new Error("Controller API URLs must not contain embedded credentials.");
-  }
-  const crossOrigin = url.origin !== base.origin;
-  if (crossOrigin && !options.allowCrossOrigin) {
-    throw new Error(
-      "Refusing a cross-origin controller API request. Set --server-url to that origin and use a relative path, or pass --allow-cross-origin only when you explicitly intend to send credentials and request data there."
-    );
-  }
-  for (const pair of options.query ?? []) {
-    const { key, value } = parseKeyValue(pair);
-    url.searchParams.set(key, value);
-  }
-  return { url, crossOrigin };
-}
-function maybePrettyPrintJson(text2, pretty) {
-  if (!pretty) return text2;
-  if (!text2.trim()) return text2;
-  try {
-    return JSON.stringify(JSON.parse(text2), null, 2);
-  } catch {
-    return text2;
-  }
-}
-async function executeControllerApiRequest(options, bodyOverride) {
-  const resolved = resolveBearerTokenWithSource(options);
-  const { url, crossOrigin } = buildRequestUrl(options, resolved.runtimeControllerUrl);
-  const bearer = resolved.token;
-  if (crossOrigin && (!bearer || resolved.source !== "explicit")) {
-    throw new Error(
-      "Cross-origin controller API requests require --allow-cross-origin and an explicit --access-token."
-    );
-  }
-  const headers = new Headers();
-  headers.set("accept", "application/json");
-  for (const header of options.headers ?? []) {
-    const { key, value } = parseHeader(header);
-    headers.set(key, value);
-  }
-  const body = bodyOverride ?? parseJsonBody(options);
-  if (body !== void 0 && !headers.has("content-type")) {
-    headers.set("content-type", "application/json");
-  }
-  const init = {
-    method: options.method,
-    headers,
-    body,
-    redirect: "error"
-  };
-  const response = bearer ? (await fetchWithControllerAuth({
-    url: url.toString(),
-    init,
-    accessToken: bearer,
-    tokenSource: resolved.source,
-    profile: resolved.profile,
-    cwd: process.cwd()
-  })).response : await fetch(url, init);
-  const responseText = await response.text().catch(() => "");
-  const contentType = response.headers.get("content-type") ?? "";
-  const isJson = contentType.includes("application/json") || contentType.includes("+json");
-  if (!response.ok) {
-    if (response.status === 401 || response.status === 403) {
-      throw formatAuthRejectedError({
-        status: response.status,
-        responseBody: responseText,
-        retryCommand: "instafy login",
-        advancedHint: "pass --access-token, or set INSTAFY_ACCESS_TOKEN / SUPABASE_ACCESS_TOKEN"
-      });
-    }
-    const formattedBody = isJson ? maybePrettyPrintJson(responseText, true) : responseText;
-    const prefix = `Request failed (${response.status} ${response.statusText})`;
-    const suffix = formattedBody.trim() ? `: ${formattedBody}` : "";
-    throw new Error(`${prefix}${suffix}`);
-  }
-  return { response, responseText, isJson };
-}
-async function requestControllerApiJson(options) {
-  const body = options.jsonBody === void 0 ? void 0 : JSON.stringify(options.jsonBody);
-  const { responseText, isJson } = await executeControllerApiRequest(
-    {
-      method: options.method,
-      path: options.path,
-      controllerUrl: options.controllerUrl,
-      accessToken: options.accessToken,
-      serviceToken: options.serviceToken,
-      query: options.query,
-      headers: options.headers,
-      allowCrossOrigin: options.allowCrossOrigin
-    },
-    body
-  );
-  if (!isJson) {
-    throw new Error("Expected JSON response from controller API");
-  }
-  return JSON.parse(responseText);
-}
-async function requestControllerApi(options) {
-  const { responseText, isJson } = await executeControllerApiRequest(options);
-  const pretty = options.pretty !== false;
-  const formattedBody = isJson ? maybePrettyPrintJson(responseText, pretty) : responseText;
-  if (formattedBody) console.log(formattedBody);
-}
-
 // src/conversations.ts
 init_project_manifest();
 import kleur11 from "kleur";
@@ -14816,10 +15382,10 @@ function projectId(explicit) {
   if (!value?.trim()) throw new Error("No space configured. Pass --space, set SPACE_ID, or run `instafy space init`.");
   return uuid(value, "Space ID");
 }
-function object(value, fields, label) {
+function object2(value, fields2, label) {
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object.`);
   const record2 = value;
-  if (Object.keys(record2).some((key) => !fields.includes(key))) throw new Error(`${label} contains an unsupported field.`);
+  if (Object.keys(record2).some((key) => !fields2.includes(key))) throw new Error(`${label} contains an unsupported field.`);
   return record2;
 }
 function text(value, label, max) {
@@ -14874,7 +15440,7 @@ async function readProposal(file) {
   } catch {
     throw new Error("Recommendation file must contain valid JSON.");
   }
-  const input3 = object(parsed, ["key", "title", "reason", "prompt", "message", "evidence"], "Recommendation");
+  const input3 = object2(parsed, ["key", "title", "reason", "prompt", "message", "evidence"], "Recommendation");
   const key = text(input3.key, "Recommendation key", 120);
   if (!/^[a-z0-9][a-z0-9_-]{0,119}$/.test(key)) throw new Error("Recommendation key must be a lowercase slug using letters, digits, hyphens or underscores.");
   if (!Array.isArray(input3.evidence) || input3.evidence.length < 1 || input3.evidence.length > 8) {
@@ -14887,7 +15453,7 @@ async function readProposal(file) {
     prompt: text(input3.prompt, "Recommendation prompt", 4e3),
     ...input3.message === void 0 ? {} : { message: text(input3.message, "Recommendation message", 4e3) },
     evidence: input3.evidence.map((value) => {
-      const entry = object(value, ["conversationId", "messageId"], "Evidence");
+      const entry = object2(value, ["conversationId", "messageId"], "Evidence");
       return {
         conversationId: uuid(entry.conversationId, "Evidence conversationId"),
         ...entry.messageId === void 0 ? {} : { messageId: uuid(entry.messageId, "Evidence messageId") }
@@ -16440,7 +17006,7 @@ async function diagnosticsRunResult(options) {
 
 // src/support.ts
 import fs19 from "node:fs";
-import { randomUUID as randomUUID3 } from "node:crypto";
+import { randomUUID as randomUUID4 } from "node:crypto";
 import path20 from "node:path";
 init_project_manifest();
 var MAX_SUMMARY_CHARS = 500;
@@ -16733,7 +17299,7 @@ async function supportReport(options) {
     printJson3(preview);
     return;
   }
-  const clientRequestId = cleanText4(options.clientRequestId) ?? randomUUID3();
+  const clientRequestId = cleanText4(options.clientRequestId) ?? randomUUID4();
   if (!UUID2.test(clientRequestId)) {
     throw new Error("--client-request-id must be a UUID.");
   }
@@ -16948,7 +17514,7 @@ async function supportReply(options) {
       `A follow-up must be at most ${MAX_MESSAGE_CHARS} characters and ${MAX_MESSAGE_BYTES} bytes.`
     );
   }
-  const clientRequestId = cleanText4(options.clientRequestId) ?? randomUUID3();
+  const clientRequestId = cleanText4(options.clientRequestId) ?? randomUUID4();
   if (!UUID2.test(clientRequestId)) {
     throw new Error("--client-request-id must be a UUID.");
   }
@@ -18391,20 +18957,48 @@ function exitWithPreviewError(error) {
 }
 var previewCommand = program.command("preview").description("Look at sites running in this space, and show them in Studio as a private preview card");
 failWithGroupHelp(previewCommand);
-registerPreviewCheckCommand(previewCommand, { hasOpenPreview: hasOpenPreviewFor, uploadThumbnail: uploadCheckThumbnail });
-failWithGroupHelp(registerWebSearchCommand(registerWebLinkCommand(registerWebCommand(program))));
+registerPreviewCheckCommand(previewCommand, {
+  hasOpenPreview: hasOpenPreviewFor,
+  uploadThumbnail: uploadCheckThumbnail,
+  pictureTried: recordCheckPictureTried
+});
+var webCommand = registerWebSearchCommand(registerWebLinkCommand(registerWebCommand(program)));
+failWithGroupHelp(webCommand);
+var webSettingsCommand = webCommand.command("settings").description("Inspect or change the space's shared research budget for new tasks");
+addSpaceOption(webSettingsCommand, "Space UUID (defaults to .instafy/space.json or SPACE_ID)");
+addServerUrlOptions(webSettingsCommand);
+addAccessTokenOptions(webSettingsCommand, "Instafy access token");
+webSettingsCommand.option("--max-page-loads <n>", "Fresh pages allowed across the parent and all helpers").option("--max-page-loads-per-site <n>", "Fresh pages allowed from one site across the task").option("--interactive", "Interactively edit the shared research budget").option("--json", "Output JSON (noninteractive)").action(async (opts) => {
+  try {
+    await researchSettings({
+      project: resolveSpaceIdOption(opts),
+      controllerUrl: opts.serverUrl,
+      accessToken: opts.accessToken,
+      maxPageLoads: opts.maxPageLoads,
+      maxPageLoadsPerSite: opts.maxPageLoadsPerSite,
+      interactive: opts.interactive,
+      json: opts.json
+    });
+  } catch (error) {
+    console.error(kleur20.red(String(error)));
+    process.exit(1);
+  }
+});
 var previewOpenCommand = previewCommand.command("open").description(
-  "Open a private preview of a local port (exit 2: nothing listening, 3: port not allowed, 5: previews not available)"
-).requiredOption("--port <port>", "Local port the site listens on (1024-65535)").requiredOption("--title <title>", "Card title (at most 120 characters)").option("--path <path>", "Path the preview opens at (default /)").option("--summary <text>", `One line of facts under the card's title, e.g. "Trip \xB7 3 days \xB7 14 places" (at most 80 characters); default: the page's own meta description`).option("--thumbnail <file>", "Use this picture on the card (JPEG, PNG or WebP, at most 512 KiB and 2000\xD72000) instead of taking one").option("--no-thumbnail", "Put no picture of the site on the card");
+  "Open a private preview of a local port (exit 2: nothing listening, 3: port not allowed or another site's, 5: previews not available)"
+).option("--port <port>", "Local port the site listens on (1024-65535); with --start, leave it out and a free one is picked").requiredOption("--title <title>", "Card title (at most 120 characters)").option("--path <path>", "Path the preview opens at (default /)").option("--summary <text>", `One line of facts under the card's title, e.g. "Trip \xB7 3 days \xB7 14 places" (at most 80 characters); default: the page's own meta description`).option("--thumbnail <file>", "Use this picture on the card (JPEG, PNG or WebP, at most 512 KiB and 2000\xD72000) instead of taking one").option("--no-thumbnail", "Put no picture of the site on the card");
 addSpaceOption(previewOpenCommand, "Space UUID (defaults to .instafy/space.json or SPACE_ID)");
 addServerUrlOptions(previewOpenCommand);
 addAccessTokenOptions(previewOpenCommand, "Instafy access token (defaults to the job token, then the saved `instafy login` token)");
 previewOpenCommand.option("--conversation <id>", "Conversation for the card (only needed without a job token)").option("--rathole-bin <path>", "Path to rathole binary (or set RATHOLE_BIN)").option(
   "--serve-cmd <command>",
-  "How to start the site again when the process that started it exits, or the space sleeps, run from the current directory (one command, no shell); default: read from the process listening on the port"
+  "How to start the site, and to start it again when the process that started it exits or the space sleeps, run from the current directory (one command, no shell); {port} in it is the site's port; default: read from the process listening on the port"
 ).option(
   "--start",
-  "Start --serve-cmd in the background, in its own session, without Instafy credentials, logging to .instafy/agent/logs, and wait for the port (nothing is started when the port already answers)"
+  "Start --serve-cmd in the background, in its own session, without Instafy credentials, logging to .instafy/agent/logs, and wait for the port. Without --port it picks a free port (this same site's earlier one, when it has one) and puts it in {port}. A port where this same site already runs is used as it is; one where another site runs is refused"
+).option(
+  "--replace",
+  "Show this site on the port even when the port's open preview shows another site (another title or folder); without it that open is refused"
 ).option("--json", "Output JSON").action(async (opts) => {
   try {
     const result = await previewOpen({
@@ -18418,6 +19012,7 @@ previewOpenCommand.option("--conversation <id>", "Conversation for the card (onl
       ratholeBin: opts.ratholeBin,
       serveCmd: opts.serveCmd,
       start: Boolean(opts.start),
+      replace: Boolean(opts.replace),
       summary: opts.summary,
       thumbnail: opts.thumbnail !== false,
       thumbnailFile: typeof opts.thumbnail === "string" ? opts.thumbnail : void 0
@@ -18443,7 +19038,7 @@ previewListCommand.option("--json", "Output JSON").action(async (opts) => {
     exitWithPreviewError(error);
   }
 });
-var previewCloseCommand = previewCommand.command("close").description("Close a preview: stop its local client and revoke it").argument("<previewId>", "Preview ID (from `instafy preview list`)");
+var previewCloseCommand = previewCommand.command("close").description("Close a preview: stop its local client and the site `open --start` started for it, and revoke it").argument("<previewId>", "Preview ID (from `instafy preview list`)");
 addSpaceOption(previewCloseCommand, "Space UUID (defaults to .instafy/space.json or SPACE_ID)");
 addServerUrlOptions(previewCloseCommand);
 addAccessTokenOptions(previewCloseCommand, "Instafy access token (defaults to the job token, then the saved `instafy login` token)");
@@ -18459,7 +19054,7 @@ previewCloseCommand.option("--json", "Output JSON").action(async (previewId, opt
       console.log(JSON.stringify(result, null, 2));
       return;
     }
-    console.log(kleur20.green(`Preview closed: ${result.previewId}`));
+    console.log(kleur20.green(`Preview closed: ${result.previewId}${result.siteStopped ? "; its site was stopped" : ""}`));
   } catch (error) {
     exitWithPreviewError(error);
   }