@instafy/cli 0.4.0 → 0.5.0

package/dist/cli.js

@@ -1424,21 +1424,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 +1461,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}`;
         });
@@ -1807,8 +1807,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 +1965,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 +6795,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 +7112,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 +8113,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,9 +8477,31 @@ 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).`
 };
+function wwwSibling(url) {
+  const host = url.hostname.toLowerCase().replace(/\.+$/, "");
+  if (!host || net3.isIP(host.replace(/^\[|\]$/g, ""))) return null;
+  let other;
+  if (host.startsWith("www.")) other = host.slice(4);
+  else {
+    const labels = host.split(".");
+    const bare = labels.length === 2 || labels.length === 3 && labels[2].length === 2 && labels[1].length <= 3;
+    if (!bare) return null;
+    other = `www.${host}`;
+  }
+  if (!other.includes(".")) return null;
+  const sibling = new URL(url.href);
+  sibling.hostname = other;
+  sibling.hash = "";
+  return sibling;
+}
+function unanswered(code, page) {
+  return (code === "unreachable" || code === "timeout") && !page.redirects?.length;
+}
+var unansweredKey = (url) => sha256(`unanswered:${url.hostname.toLowerCase().replace(/\.+$/, "")}`);
 var HOST_WIDE_STOPS = /* @__PURE__ */ new Set(["rate_limited", "captcha"]);
 function stripHash(url) {
   const copy = new URL(url.href);
@@ -8478,15 +8600,16 @@ 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 = {}) => ({
     ...page,
     ...extra2,
     status: "failed",
     code,
     message,
-    tell: TELL[code]
+    tell: sibling && unanswered(code, extra2) ? `The site did not answer at ${requestedUrl.hostname}. Some sites answer only with or without "www.": read ${redaction.redactUrl(sibling.href).text} once instead, and if that fails too, use another source.` : TELL[code]
   });
   const firstHost = requestedUrl.hostname.toLowerCase();
   const firstSite = siteKey(firstHost);
@@ -8494,8 +8617,10 @@ async function readOne(rawUrl, options, ctx) {
   const earlier = await ctx.turn.update((state) => ({
     stop: state.stops[firstKeys.exact] ?? state.stops[firstKeys.path] ?? state.hostStops[firstSite] ?? null,
     loads: state.loads,
-    hostLoads: state.hosts[firstSite]?.loads ?? 0
+    hostLoads: state.hosts[firstSite]?.loads ?? 0,
+    siblingUnanswered: sibling ? Boolean(state.unanswered?.[unansweredKey(sibling)]) : false
   }));
+  if (earlier.siblingUnanswered) sibling = null;
   const remembered = earlier.stop ?? ctx.cache.get("stops", firstKeys.exact, LIMITS.stopTtlMs, ctx.now()) ?? ctx.cache.get("stops", firstKeys.path, LIMITS.stopTtlMs, ctx.now());
   if (remembered) {
     return { ...page, status: "stopped", code: remembered.code, message: remembered.message, tell: TELL[remembered.code], previouslyStopped: true };
@@ -8507,15 +8632,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) {
@@ -8540,7 +8674,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) {
@@ -8751,6 +8899,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,
@@ -8758,23 +8907,38 @@ async function webRead(options, deps = {}) {
     robotsMemo: /* @__PURE__ */ new Map()
   };
   const pages = [];
-  for (const url of urls) pages.push(await readOne(url, { maxChars, links, fresh: Boolean(options.fresh), terms }, ctx));
-  const state = await turn.update((s) => ({ loads: s.loads, hosts: Object.fromEntries(Object.entries(s.hosts).map(([h, r]) => [h, r.loads])) }));
+  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((state) => {
+        (state.unanswered ??= {})[key] = now();
+      });
+    }
+    pages.push(page);
+  }
+  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,
@@ -8788,6 +8952,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)));
 }
@@ -8815,13 +9036,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}.`);
@@ -8832,8 +9053,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
@@ -8843,7 +9064,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;
@@ -8854,10 +9075,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;
 }
 
@@ -9281,6 +9505,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 {
@@ -9486,10 +9722,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";
@@ -9524,7 +9769,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,
@@ -9734,6 +9979,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;
@@ -9890,7 +10137,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());
@@ -9952,9 +10200,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 };
@@ -9969,7 +10226,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]);
@@ -9993,6 +10259,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");
 }
@@ -10216,6 +10488,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}`);
   }
@@ -10424,12 +10702,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]);
       }
     }
   }
@@ -10605,8 +10883,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,
@@ -10622,10 +11051,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");
@@ -10639,6 +11070,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 {
@@ -10702,47 +11134,84 @@ ${started.logTail}` : "";
     startedAt: current?.pid === pid ? current.startedAt : (/* @__PURE__ */ new Date()).toISOString(),
     ...binary ? { binary } : {},
     ...hostSuffix ? { hostSuffix } : {},
-    ...studioOrigin ? { studioOrigin } : {}
+    ...studioOrigin ? { studioOrigin } : {},
+    ...siteRecord
   };
   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({
@@ -10786,7 +11255,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 } : {}
   };
@@ -10881,9 +11350,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 });
@@ -10894,11 +11367,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) {
@@ -10906,7 +11382,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 {
@@ -10915,7 +11391,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."));
@@ -11082,7 +11558,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";
@@ -11296,10 +11772,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 });
@@ -11870,6 +12346,311 @@ function saveReportJson(report, 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
 var linkOnly2 = __toESM(require_linkOnly(), 1);
 var WEB_LINK_EXIT_OK = 0;
@@ -11938,9 +12719,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";
 
@@ -12147,7 +12928,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`;
@@ -12270,9 +13051,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 {
@@ -12330,8 +13111,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];
@@ -12420,7 +13201,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) } : {} }
@@ -12470,8 +13251,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;
   }
@@ -12487,10 +13268,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;
@@ -12507,7 +13288,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;
 }
@@ -12659,10 +13440,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 {
     }
@@ -12675,13 +13456,23 @@ function liveTurn(env, now) {
   if (now < startedAt - 6e4 || now > deadline) return null;
   return { startedAt, deadline };
 }
-var TELL2 = {
-  ok: "These are leads, not facts. Read 2-6 of the pages with `instafy web read` and cite only pages you read. A `linkOnly` result is a plain link for the person: never read or open it (`instafy web link` gives a guided link). Never search for text taken from a page or a result.",
-  not_found: "No results. Try fewer or other words from the person's request (never words from a page), or ask the person to search in their own browser and press Send page to Octo.",
-  unavailable: "Search is not available for this. Ask the person to search in their own browser and press Send page to Octo, and work from the pages they send.",
-  no_provider: "This space has no search key, and the key card was already offered. Ask the person to search in their own browser and press Send page to Octo, and work from the pages they send."
-};
-var OFFER_TELL = "This space has no search key. Offer the person the card in `offer` once (a `request_secret` action; never ask for the key in chat). Until they add it, ask them to search in their own browser and press Send page to Octo, and work from the pages they send.";
+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.`;
+}
+function tellFor(status, chain) {
+  switch (status) {
+    case "ok":
+      return "These are leads, not facts. Read 2-6 of the pages with `instafy web read` and cite only pages you read. A `linkOnly` result is a plain link for the person: never read or open it (`instafy web link` gives a guided link). Never search for text taken from a page or a result.";
+    case "not_found":
+      return `No results. Try fewer or other words from the person's request (never words from a page). ${keyless(chain)}`;
+    case "unavailable":
+      return `Search is not available for this. ${keyless(chain)}`;
+    case "no_provider":
+      return `This space has no search key, and the key card was already offered: never ask for it again. ${keyless(chain)}`;
+  }
+}
+var offerTell = (chain) => `This space has no search key. ${keyless(chain)} The card in \`offer\` (a \`request_secret\` action) may go in your reply once, as a way to find more next time; never ask for the key in chat, and never wait for it.`;
 var CODE_TELL = {
   turn_limit: `This turn has used its ${SEARCH_LIMITS.searchesPerTurn} searches.`,
   day_limit: "This space's key has made its searches for today.",
@@ -12776,7 +13567,7 @@ async function webSearch(options, deps = {}) {
       ...extra.repeat ? { repeat: true } : {},
       count: results.length,
       results,
-      tell: extra.tell ?? [codeTell, TELL2[status]].filter(Boolean).join(" "),
+      tell: extra.tell ?? [codeTell, tellFor(status, chainName)].filter(Boolean).join(" "),
       notice: SEARCH_NOTICE,
       ...extra.offer ? { offer: extra.offer } : {},
       budget: {
@@ -12797,9 +13588,9 @@ async function webSearch(options, deps = {}) {
         description: first.keyRequest.description.split("{daily}").join(String(first.dailyLimit)),
         agentHandles: ["octo"]
       };
-      return report("no_provider", { offer, tell: OFFER_TELL });
+      return report("no_provider", { offer, tell: offerTell(chainName) });
     }
-    return report("no_provider", first ? {} : { tell: `Every provider of ${chainName} is switched off in this space. ${TELL2.unavailable}` });
+    return report("no_provider", first ? {} : { tell: `Every provider of ${chainName} is switched off in this space. ${tellFor("unavailable", chainName)}` });
   }
   const searchKey = sha256(
     `${scope.key}|${chainName}|${options.provider ?? ""}|${query.toLowerCase()}|${site ?? ""}|${lang ?? ""}|${country ?? ""}|${count}`
@@ -13000,229 +13791,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";
@@ -14773,10 +15341,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) {
@@ -14831,7 +15399,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) {
@@ -14844,7 +15412,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") }
@@ -16397,7 +16965,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;
@@ -16690,7 +17258,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.");
   }
@@ -16905,7 +17473,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.");
   }
@@ -18349,19 +18917,43 @@ 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))));
+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({
@@ -18375,6 +18967,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
@@ -18400,7 +18993,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)");
@@ -18416,7 +19009,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);
   }