@tablation/crew 0.83.0 → 0.85.0

package/dist/cli.js

@@ -34,6 +34,29 @@ function doctorBaseReport(r, base, health) {
   }
 }
 
+// src/periscopes.ts
+import { lookup } from "dns/promises";
+function periscopeRoutes(cfg) {
+  return cfg.routes.filter((r) => r.enabled && r.hostPeriscopes).map((r) => r.route);
+}
+function periscopeSummary(cfg) {
+  const routes = periscopeRoutes(cfg);
+  const limits = `max ${cfg.ship.maxPeriscopes}, idle ${cfg.ship.periscopeIdleMinutes} min`;
+  if (routes.length === 0) return `off (no enabled route sets hostPeriscopes: true; ${limits})`;
+  return `ON for ${routes.join(", ")} (host ${cfg.ship.previewHost ?? "NOT SET (ship.previewHost)"}, ${limits})`;
+}
+async function previewHostProblem(cfg, resolve6 = (h) => lookup(h)) {
+  if (periscopeRoutes(cfg).length === 0) return void 0;
+  const host = cfg.ship.previewHost;
+  if (!host) return "ship.previewHost is not set \u2014 a route hosts periscopes, so Passengers have no host to be sent to";
+  try {
+    await resolve6(host);
+  } catch {
+    return `ship.previewHost "${host}" does not resolve from this machine`;
+  }
+  return void 0;
+}
+
 // src/config.ts
 import { readFileSync as readFileSync8, existsSync as existsSync7 } from "fs";
 import { resolve, dirname as dirname3, isAbsolute, join as join9, basename as basename3 } from "path";
@@ -2034,6 +2057,8 @@ var ROLE_LABEL = {
 };
 var ConfigError = class extends Error {
 };
+var DEFAULT_MAX_PERISCOPES = 3;
+var DEFAULT_PERISCOPE_IDLE_MINUTES = 120;
 function parseCloneScheme(v) {
   if (v === void 0 || v === null || v === "") return void 0;
   if (v === "ssh" || v === "https") return v;
@@ -2065,7 +2090,10 @@ var SHIP_KEYS = /* @__PURE__ */ new Set([
   "relayHttpPort",
   "relayPublicDomain",
   "passengerImage",
-  "cloneScheme"
+  "cloneScheme",
+  "previewHost",
+  "maxPeriscopes",
+  "periscopeIdleMinutes"
 ]);
 var ROUTE_KEYS = /* @__PURE__ */ new Set([
   "route",
@@ -2088,6 +2116,7 @@ var ROUTE_KEYS = /* @__PURE__ */ new Set([
   "resolved",
   "promptSet",
   "hostPassengers",
+  "hostPeriscopes",
   "toolchain"
 ]);
 function parseWorktreeName(v, where, file) {
@@ -2399,6 +2428,14 @@ Create the first of those:
   if (!Number.isInteger(streamRetentionDays) || streamRetentionDays < 1) {
     missing.add(`ship.streamRetentionDays must be a positive integer (got "${shipRaw.streamRetentionDays}")`);
   }
+  const maxPeriscopes = shipRaw.maxPeriscopes === void 0 ? DEFAULT_MAX_PERISCOPES : Number(shipRaw.maxPeriscopes);
+  if (!Number.isInteger(maxPeriscopes) || maxPeriscopes < 1) {
+    missing.add(`ship.maxPeriscopes must be a positive integer (got "${shipRaw.maxPeriscopes}")`);
+  }
+  const periscopeIdleMinutes = shipRaw.periscopeIdleMinutes === void 0 ? DEFAULT_PERISCOPE_IDLE_MINUTES : Number(shipRaw.periscopeIdleMinutes);
+  if (!Number.isInteger(periscopeIdleMinutes) || periscopeIdleMinutes < 1) {
+    missing.add(`ship.periscopeIdleMinutes must be a positive integer (got "${shipRaw.periscopeIdleMinutes}")`);
+  }
   const eventsRotateBytes = shipRaw.eventsRotateBytes === void 0 ? DEFAULT_EVENTS_ROTATE_BYTES : Number(shipRaw.eventsRotateBytes);
   if (!Number.isInteger(eventsRotateBytes) || eventsRotateBytes < 1) {
     missing.add(`ship.eventsRotateBytes must be a positive integer (got "${shipRaw.eventsRotateBytes}")`);
@@ -2468,7 +2505,10 @@ Create the first of those:
       relayHttpPort: shipRaw.relayHttpPort !== void 0 ? Number(shipRaw.relayHttpPort) : 443,
       relayPublicDomain: shipRaw.relayPublicDomain ? String(shipRaw.relayPublicDomain) : void 0,
       passengerImage: shipRaw.passengerImage ? String(shipRaw.passengerImage) : void 0,
-      cloneScheme: parseCloneScheme(shipRaw.cloneScheme)
+      cloneScheme: parseCloneScheme(shipRaw.cloneScheme),
+      previewHost: shipRaw.previewHost ? String(shipRaw.previewHost).trim() || void 0 : void 0,
+      maxPeriscopes,
+      periscopeIdleMinutes
     },
     routes,
     crewHome,
@@ -2569,6 +2609,9 @@ function parseOneRoute(c, where, file, base, stateDir, raw, missing, crewHome, t
     missing.add(`${where}.toolchain "${toolchain}" is not defined in ship.toolchains (have: ${[...toolchainNames].join(", ")})`);
   }
   const route = missing.req(c?.route, `${where}.route`);
+  if (c?.hostPeriscopes === true && c?.hostPassengers !== true) {
+    missing.add(`${where} (route "${route}") sets hostPeriscopes: true without hostPassengers: true \u2014 a Passenger must be able to board before they can open a periscope`);
+  }
   const routeParts = route ? route.split("/") : [];
   const routeWellFormed = routeParts.length === 2 && routeParts.every(Boolean);
   if (route && !routeWellFormed) {
@@ -2643,7 +2686,8 @@ function parseOneRoute(c, where, file, base, stateDir, raw, missing, crewHome, t
     },
     release: parseReleaseOverride(c?.release, where, file),
     branch: parseBranchOverride(c?.branch, where, file),
-    hostPassengers: c?.hostPassengers === true
+    hostPassengers: c?.hostPassengers === true,
+    hostPeriscopes: c?.hostPeriscopes === true
   };
   const resolvedFile = routeWellFormed ? readResolvedFile(stateDir, route) : void 0;
   result.resolved = parseResolved(resolvedFile ?? c?.resolved, missing, where);
@@ -5562,7 +5606,7 @@ function validateContract(c) {
 }
 var EVENT_LOG_MISSING = "the Issues table has no event log \u2014 crew writes its audit trail there (CREW-1574). In the app, open the Issues table's Data & lifecycle tab and turn on Event log, then rerun.";
 var PERISCOPE_COLUMNS = [
-  "ticket_id",
+  "issue_id",
   "ship_id",
   "url",
   "host",
@@ -6835,6 +6879,32 @@ var Tracker = class {
     const have = await this.columnNames(modelId);
     return { present: true, modelId, missing: PERISCOPE_COLUMNS.filter((c) => !have.has(c)) };
   }
+  /**
+   * How many `live` Periscopes rows this ship holds (EPIC-077). Zero when the
+   * workspace has no Periscopes table or this ship has no Ships row yet (the
+   * row's `ship_id` could not name it), so the cap only ever counts rows it
+   * can attribute.
+   */
+  async livePeriscopeCount() {
+    const modelId = this.route.resolved?.periscopesModelId;
+    const { shipId } = await this.authorshipProbe();
+    if (!modelId || !shipId) return 0;
+    const rows = await this.client.records.list(modelId, {
+      filters: encodeFilters([
+        { columnName: "ship_id", operator: "EQ", value: shipId },
+        { columnName: "state", operator: "EQ", value: "live" }
+      ]),
+      limit: 200
+    });
+    return rows.length;
+  }
+  /** Records a Periscopes row for this ship (EPIC-077); `ship_id` is stamped here, never by the caller. */
+  async createPeriscope(fields) {
+    const modelId = this.route.resolved?.periscopesModelId;
+    if (!modelId) throw new Error("this workspace has no Periscopes table");
+    const { shipId } = await this.authorshipProbe();
+    return this.client.records.create(modelId, { ...fields, ...shipId ? { ship_id: shipId } : {} });
+  }
   /**
    * The authorship columns this workspace is missing, as `table.column` names
    * for `crew doctor` to report (CREW-1371). Empty on a fully updated install.
@@ -7762,7 +7832,7 @@ function skillMarkerNames(text) {
   }
   return names;
 }
-function expandSkillMarkers(text, lookup, opts = {}) {
+function expandSkillMarkers(text, lookup2, opts = {}) {
   const maxDepth = opts.maxDepth ?? MAX_INCLUDE_DEPTH;
   const maxBytes = opts.maxBytes ?? MAX_INCLUDED_BYTES;
   const warnings = [];
@@ -7778,7 +7848,7 @@ function expandSkillMarkers(text, lookup, opts = {}) {
       warnings.push(`skill include "${name}" left literal: nested deeper than ${maxDepth} levels`);
       return literal;
     }
-    const body = lookup(name);
+    const body = lookup2(name);
     if (body === void 0) throw new SkillIncludeError(`no skill named "${name}" for the include ${literal}`);
     const trimmed = body.replace(/^\n+/, "").replace(/\n+$/, "");
     const bytes = Buffer.byteLength(trimmed, "utf8");
@@ -9058,8 +9128,8 @@ function spawnAgent(plan, emit, hintMoved) {
     const meta = { pid: child.pid ?? null };
     obs.onClaim = () => writeRunMeta(id, startedAt, obs.liveTicket, meta);
     if (child.pid !== void 0) writeRunMeta(id, startedAt, obs.liveTicket, meta);
-    const tail = new FileTail(plan.streamPath);
-    const timer = setInterval(() => obs.feed(tail.poll()), TAIL_POLL_MS);
+    const tail2 = new FileTail(plan.streamPath);
+    const timer = setInterval(() => obs.feed(tail2.poll()), TAIL_POLL_MS);
     let spawnFailed = false;
     child.on("error", (err) => {
       spawnFailed = true;
@@ -9068,7 +9138,7 @@ function spawnAgent(plan, emit, hintMoved) {
     });
     child.on("close", async (code) => {
       clearInterval(timer);
-      obs.feed(tail.poll());
+      obs.feed(tail2.poll());
       obs.end();
       await endSink(eventsSink);
       if (spawnFailed) return;
@@ -9087,20 +9157,20 @@ async function reattachRun(streamPath, sc, emit, o = {}) {
   const id = { ...sc, streamPath };
   const eventsSink = openSink(sc.eventsPath);
   const obs = new RunObserver(id, adapter, eventsSink, emit.cycle);
-  const tail = new FileTail(streamPath);
+  const tail2 = new FileTail(streamPath);
   obs.muted = true;
-  obs.feed(tail.poll());
+  obs.feed(tail2.poll());
   obs.muted = false;
   const adopted = isAlive(sc);
   if (adopted) {
     o.onAdopted?.();
     const pollMs = o.pollMs ?? TAIL_POLL_MS;
     while (isAlive(sc)) {
-      obs.feed(tail.poll());
+      obs.feed(tail2.poll());
       await new Promise((r) => setTimeout(r, pollMs));
     }
   }
-  obs.feed(tail.poll());
+  obs.feed(tail2.poll());
   obs.end();
   await endSink(eventsSink);
   const interrupted = obs.sawResult ? void 0 : adopted ? "no-result" : "daemon-exit";
@@ -9648,7 +9718,9 @@ var VALUE_FLAGS = /* @__PURE__ */ new Set([
   "toolchain",
   "workspace",
   "workspace-id",
-  "write"
+  "write",
+  "topic",
+  "assignee"
 ]);
 function positionalArgs(argv2) {
   const out = [];
@@ -12988,7 +13060,7 @@ async function isolateAndRetry(o, name, output, merged, preMerge, decision, fres
       }
       if (culprits.length === 0 && truncated) {
         let lo = 2, hi = applied.length;
-        let tail = lastLines(output, HOOK_FAILURE_TAIL_LINES);
+        let tail2 = lastLines(output, HOOK_FAILURE_TAIL_LINES);
         while (lo < hi) {
           const mid = Math.floor((lo + hi) / 2);
           gitOk(o.cwd, ["reset", "--hard", preMerge]);
@@ -13003,12 +13075,12 @@ async function isolateAndRetry(o, name, output, merged, preMerge, decision, fres
           const r = clean ? await hook(o, name) : null;
           if (r && r.code !== 0) {
             hi = mid;
-            tail = lastLines(r.output, HOOK_FAILURE_TAIL_LINES);
+            tail2 = lastLines(r.output, HOOK_FAILURE_TAIL_LINES);
           } else lo = mid + 1;
         }
         const owner = applied[hi - 1];
         o.emit.warn(`${owner.branch} is the first branch whose prefix fails the ${name} hook (bisected over ${applied.length})`, { ticket: owner.ticket.issue_id });
-        culprits.push({ c: owner, how: "pair", sibling: applied[hi - 2], tail });
+        culprits.push({ c: owner, how: "pair", sibling: applied[hi - 2], tail: tail2 });
       }
     }
   }
@@ -16329,6 +16401,139 @@ function planEventsSweep(stateDir, retentionDays, now = Date.now()) {
 // src/cli.ts
 import { realpathSync as realpathSync3, readFileSync as readFileSync31, existsSync as existsSync35, mkdirSync as mkdirSync22, writeFileSync as writeFileSync23, rmSync as rmSync15, unlinkSync as unlinkSync5, copyFileSync as copyFileSync2, renameSync as renameSync3, statSync as statSync10, readdirSync as readdirSync16 } from "fs";
 import { createInterface } from "readline/promises";
+
+// src/periscope-cmd.ts
+var PeriscopeError = class extends Error {
+};
+var DEFAULT_MAX_PERISCOPES2 = 3;
+var DEFAULT_PERISCOPE_IDLE_MINUTES2 = 120;
+function parsePeriscopeUpArgs(positional2, flags) {
+  const rest = positional2.slice(2);
+  if (rest.length === 0 || rest.length > 2) {
+    throw new PeriscopeError("usage: crew periscope up [route] REPO [--topic TEXT] [--isolate] [--host HOST] [--assignee CREW_ROW_ID] [--json]");
+  }
+  const topic = flags.topic?.trim();
+  return {
+    ...rest.length === 2 ? { route: rest[0] } : {},
+    repo: rest[rest.length - 1],
+    ...topic ? { topic } : {},
+    isolate: flags.isolate,
+    ...flags.host ? { host: flags.host } : {},
+    ...flags.assignee ? { assignee: flags.assignee } : {},
+    json: flags.json
+  };
+}
+function parseEnvLines(output) {
+  const env = {};
+  for (const line of output.split("\n")) {
+    const m = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/.exec(line.trim());
+    if (m) env[m[1]] = m[2].replace(/^"(.*)"$/, "$1");
+  }
+  return env;
+}
+function previewUrlFrom(output) {
+  const last = output.split("\n").map((l) => l.trim()).filter(Boolean).pop();
+  return last && /^https?:\/\/\S+$/i.test(last) ? last : void 0;
+}
+function periscopeCaps(l) {
+  return {
+    max: l.maxPeriscopes ?? DEFAULT_MAX_PERISCOPES2,
+    idleMinutes: l.periscopeIdleMinutes ?? DEFAULT_PERISCOPE_IDLE_MINUTES2
+  };
+}
+var tail = (s, n = 20) => s.trimEnd().split("\n").slice(-n).join("\n");
+function progressComment(url, handoff) {
+  return [
+    `Periscope is up: ${url}`,
+    ...handoff?.trim() ? ["", handoff.trim()] : []
+  ].join("\n");
+}
+async function periscopePreflight(d, repo) {
+  if (!d.previewHook) {
+    throw new PeriscopeError(`${repo} declares no \`preview\` hook, so it cannot host a periscope \u2014 add one to its .crew.yaml (see the repository spec page, "hooks.preview")`);
+  }
+  if (!d.hasPeriscopesTable) {
+    throw new PeriscopeError("this workspace has no Periscopes table \u2014 update the Issues template and run `crew connect`");
+  }
+  const live = await d.liveCount();
+  if (live >= d.caps.max) {
+    throw new PeriscopeError(`this ship already hosts ${live} live periscope(s) (ship.maxPeriscopes is ${d.caps.max}) \u2014 discard one first`);
+  }
+}
+async function runPeriscopeUp(d, args) {
+  await periscopePreflight(d, args.repo);
+  const topic = args.topic ?? (await d.askTopic())?.trim();
+  if (!topic) throw new PeriscopeError("a topic is required: pass --topic TEXT");
+  const unsafe = d.baseProblem();
+  if (unsafe) throw new PeriscopeError(`DO NOT CUT A WORKTREE FROM THIS BASE \u2014 ${unsafe}`);
+  const draft = await d.fileDraft(`Periscope: ${topic}`);
+  d.say("filed", `filed draft ${draft.tag}`, { ticket: draft.tag, ticketRecordId: draft.id });
+  let wt;
+  const abandon = async (why) => {
+    if (wt) await d.teardown(wt.path, wt.branch).catch(() => {
+    });
+    await d.closeDraft(draft.id, `Periscope abandoned: ${why.split("\n")[0]}`).catch(() => {
+    });
+    throw new PeriscopeError(why);
+  };
+  try {
+    wt = d.cutWorktree(draft);
+  } catch (e) {
+    return abandon(e.message);
+  }
+  d.say("worktree", `cut ${wt.path} on ${wt.branch}`, { worktree: wt.path, branch: wt.branch });
+  const prepared = await d.prepare(wt.path);
+  if (prepared && prepared.code !== 0) {
+    return abandon(`setup failed (exit ${prepared.code})
+${tail(prepared.output)}`);
+  }
+  const env = { CREW_TICKET: draft.tag, CREW_BRANCH: wt.branch };
+  const ports = await d.runHook("ports", wt.path, env);
+  if (ports) Object.assign(env, parseEnvLines(ports.output));
+  if (args.isolate) {
+    const iso = await d.runHook("isolate", wt.path, env);
+    if (iso && iso.code !== 0) return abandon(`isolate failed (exit ${iso.code})
+${tail(iso.output)}`);
+    if (iso) Object.assign(env, parseEnvLines(iso.output));
+  }
+  const handoff = await d.runHook("handoff", wt.path, env);
+  if (handoff && handoff.code !== 0) return abandon(`handoff failed (exit ${handoff.code})
+${tail(handoff.output)}`);
+  const preview = await d.runHook("preview", wt.path, { ...env, CREW_PREVIEW_HOST: d.host });
+  if (!preview || preview.code !== 0) {
+    return abandon(`preview exited ${preview?.code ?? "without running"}
+${tail(preview?.output ?? "")}`);
+  }
+  const url = previewUrlFrom(preview.output);
+  if (!url) return abandon(`preview printed no URL as its last line
+${tail(preview.output)}`);
+  d.say("preview", `preview at ${url}`, { url });
+  const now = d.now();
+  let row;
+  try {
+    row = await d.createRow({
+      issue_id: draft.id,
+      url,
+      host: d.host,
+      worktree: wt.path,
+      branch: wt.branch,
+      state: "live",
+      isolated: args.isolate,
+      started_at: now.toISOString(),
+      last_activity_at: now.toISOString(),
+      expires_at: new Date(now.getTime() + d.caps.idleMinutes * 6e4).toISOString()
+    });
+  } catch (e) {
+    return abandon(`recording the Periscopes row failed: ${e.message}`);
+  }
+  d.say("recorded", "recorded the Periscopes row", { periscopeRecordId: row.id });
+  await d.comment(draft.id, progressComment(url, handoff?.output)).catch((e) => {
+    d.say("warning", `progress comment not posted: ${e.message}`);
+  });
+  return { ticket: draft.tag, ticketRecordId: draft.id, worktree: wt.path, branch: wt.branch, url, periscopeRecordId: row.id };
+}
+
+// src/cli.ts
 import { dirname as dirOf, resolve as resolvePath } from "path";
 
 // src/ssh-keys.ts
@@ -17789,6 +17994,8 @@ function usage(problem, requested = false) {
   crew reap [route]              kill orphaned servers, drop worktrees for closed tickets
   crew drop [route] NNN          remove a merged ticket's worktree and branch
   crew rotate-passenger-url [route]   force a Host Passengers tunnel to reconnect with a fresh public URL
+  crew periscope up [route] REPO --topic TEXT [--isolate] [--host H] [--assignee ID] [--dry-run] [--json]
+                                 file a draft ticket, cut and prepare its worktree, start the repo's preview hook and record a Periscopes row (alias: start)
   crew worktree [route] NNN      cut (or refresh) this run's worktree for a ticket from the remote; prints its path
   crew unassign [route] NNN      hand back a session's ticket \u2014 clears assignee, next cycle picks it up
   crew sync [route]              fast-forward the checkout and its worktrees from the remote
@@ -17881,6 +18088,7 @@ var KNOWN_COMMANDS = /* @__PURE__ */ new Set([
   "merge",
   "passengers",
   "pause",
+  "periscope",
   "poll",
   "ports",
   "projects",
@@ -18084,7 +18292,7 @@ if (command === "passenger-sync-daemon") {
   const DAEMON_SUBCOMMANDS = /* @__PURE__ */ new Set(["start", "stop", "status", "restart"]);
   const worktreeArgs = command === "worktree" ? splitWorktreeArgs(positional, cfg.routes.map((r) => r.route)) : void 0;
   const named = worktreeArgs ? worktreeArgs.route : command === "daemon" && DAEMON_SUBCOMMANDS.has(positional[1] ?? "") ? positional[2] : positional[1];
-  const fleetWide = command === "inbox" || command === "connect" || command === "disconnect" || command === "agents" || command === "skills" || command === "logbook" || command === "repos" || command === "ship" || command === "projects" || command === "whoami" || releaseFleetWide || command === "pause" || command === "resume" || command === "reload" || FLEET_CAPABLE.has(command) && !named && cfg.routes.length > 1 || worktreeArgs !== void 0 && !named && cfg.routes.length > 1;
+  const fleetWide = command === "inbox" || command === "connect" || command === "disconnect" || command === "agents" || command === "skills" || command === "logbook" || command === "repos" || command === "ship" || command === "projects" || command === "periscope" || command === "whoami" || releaseFleetWide || command === "pause" || command === "resume" || command === "reload" || FLEET_CAPABLE.has(command) && !named && cfg.routes.length > 1 || worktreeArgs !== void 0 && !named && cfg.routes.length > 1;
   let route;
   try {
     route = fleetWide ? cfg.routes[0] : findRoute(cfg, named);
@@ -20385,6 +20593,7 @@ Signed in as ${result.identity.email} \u2014 minted an API key in workspace "${r
         platform: cfg.ship.platform,
         machineId,
         hostPassengers: firstRun?.answers.hostPassengers ?? existingRoute?.hostPassengers === true,
+        hostPeriscopes: existingRoute?.hostPeriscopes === true,
         sshPublicKey,
         lastSyncedName: (r) => readSyncedName(resolvedPathFor(cfg.ship.stateDir, r))
       };
@@ -21164,7 +21373,7 @@ Signed in as ${result.identity.email} \u2014 minted an API key in workspace "${r
       const hitsWt = /* @__PURE__ */ new Map();
       for (const cand of candidatesWt) {
         const tr = new Tracker(cand, cfg.ship);
-        const hit = (await tr.openTickets()).find((t) => t[tr.contract.columns.key] === `ISSUE-${nWt}`);
+        const hit = (await tr.openTickets()).find((t) => t[tr.contract.columns.key] === `ISSUE-${nWt}`) ?? (await tr.ticketsByNumbers([nWt])).find((t) => t[tr.contract.columns.key] === `ISSUE-${nWt}` && t[tr.contract.columns.status] === tr.contract.statuses.draft);
         if (hit) hitsWt.set(cand.route, hit);
         lookedWt.push({
           route: cand.route,
@@ -21211,6 +21420,131 @@ Signed in as ${result.identity.email} \u2014 minted an API key in workspace "${r
       if (!planIsUsable(planWt)) process.exitCode = 1;
       break;
     }
+    case "periscope": {
+      const subP = positional[1];
+      if (subP !== "up" && subP !== "start") {
+        process.stderr.write("crew periscope up [route] REPO --topic TEXT [--isolate] [--host H] [--assignee ID] [--dry-run] [--json]\n");
+        process.exit(2);
+      }
+      const jsonP = flag("json");
+      const say = (event, message, data = {}) => process.stderr.write(jsonP ? `${JSON.stringify({ ...data, event, message })}
+` : `${message}
+`);
+      try {
+        const a = parsePeriscopeUpArgs(positional, { topic: value("topic"), host: value("host"), assignee: value("assignee"), isolate: flag("isolate"), json: jsonP });
+        const candidatesP = a.route ? [findRoute(cfg, a.route)] : cfg.routes.filter((r) => r.enabled);
+        const servedP = [];
+        for (const cand of candidatesP) {
+          const hit = (await resolvedRepos(cand)).find((r) => r.name === a.repo);
+          if (hit) servedP.push({ route: cand, repo: hit });
+        }
+        if (servedP.length !== 1) {
+          throw new PeriscopeError(servedP.length === 0 ? `no route serves a repository named "${a.repo}"` : `"${a.repo}" is served by more than one route (${servedP.map((x) => x.route.route).join(", ")}) \u2014 name the route`);
+        }
+        const { route: routeP, repo: repoP } = servedP[0];
+        if (!routeP.resolved) throw new PeriscopeError(`route ${routeP.route} is not connected \u2014 run \`crew connect\` first`);
+        const trackerP = new Tracker(routeP, cfg.ship);
+        const cP = trackerP.contract;
+        const periscopes = await trackerP.periscopesStatus();
+        const caps = periscopeCaps(cfg.ship);
+        const shellP = resolveShell(repoP.config.shell ?? cfg.ship.shell);
+        const pairId = a.assignee ?? routeP.resolved.seats.pair;
+        if (!pairId) throw new PeriscopeError(`route ${routeP.route} has no Pair seat \u2014 pass --assignee CREW_ROW_ID`);
+        const crewP = await trackerP.crewRows();
+        const operatorName = crewP.find((r) => r.id === routeP.resolved.operator)?.name ?? "Pair";
+        const memberId = routeP.resolved.seats.pair ?? routeP.resolved.operator;
+        const deps = {
+          previewHook: repoP.config.hooks.preview,
+          hasPeriscopesTable: periscopes.present,
+          liveCount: () => trackerP.livePeriscopeCount(),
+          caps,
+          baseProblem: () => {
+            const h = baseHealth(repoP);
+            return h.unsafe ? h.detail : void 0;
+          },
+          askTopic: async () => {
+            if (!process.stdin.isTTY || jsonP) return void 0;
+            const rl = createInterface({ input: process.stdin, output: process.stderr });
+            try {
+              return await rl.question("Periscope topic: ");
+            } finally {
+              rl.close();
+            }
+          },
+          fileDraft: async (title) => {
+            const t = await trackerP.fileTicket({
+              title,
+              description: `A periscope: a throwaway preview of ${a.repo} for a viewer, opened by \`crew periscope up\`.`,
+              report_type: "feature",
+              reporter_name: operatorName,
+              [cP.columns.status]: cP.statuses.draft,
+              [cP.columns.assignee]: pairId,
+              ...routeP.resolved.areaId ? { [cP.columns.slice]: routeP.resolved.areaId } : {},
+              ...repoP.id ? { [cP.columns.repo]: repoP.id } : {}
+            }, memberId);
+            return { id: t.id, tag: t.issue_tag ?? t.issue_id, issueId: t.issue_id, prefix: t.project_issue_prefix };
+          },
+          cutWorktree: (draft) => {
+            const plan = planRunWorktree(repoP.dir, repoP.config, { issue_id: draft.issueId, issue_tag: draft.tag, project_issue_prefix: draft.prefix }, void 0);
+            if (!planIsUsable(plan)) throw new PeriscopeError(`cannot use the worktree: ${describeRunWorktreePlan(plan)}`);
+            const path = applyRunWorktree(repoP.dir, repoP.config, plan);
+            if (!path) throw new PeriscopeError("the worktree could not be cut");
+            return { path, branch: plan.branch ?? "" };
+          },
+          prepare: async (path) => {
+            for (const f of repoP.config.worktrees.copy) {
+              const src = join38(repoP.dir, f);
+              if (!existsSync35(src)) continue;
+              mkdirSync22(dirOf(join38(path, f)), { recursive: true });
+              copyFileSync2(src, join38(path, f));
+            }
+            const setup = repoP.config.hooks.setup;
+            return setup ? runScript(setup, { cwd: path, shell: shellP, onLine: (l) => {
+              if (l.trim()) say("setup", l.trim());
+            } }) : null;
+          },
+          runHook: async (name, cwd, env) => {
+            const script = repoP.config.hooks[name];
+            return script ? runScript(script, { cwd, env, shell: shellP, timeoutMs: name === "preview" ? 18e4 : void 0 }) : null;
+          },
+          createRow: (fields) => trackerP.createPeriscope(fields),
+          comment: (ticketId, body) => trackerP.postComment(ticketId, body, memberId),
+          teardown: async (path, branch) => {
+            const n = Number(path.match(/(\d+)\/?$/)?.[1]);
+            if (Number.isFinite(n)) await killGently(pidsInWorktree(path, n));
+            gitOk(repoP.dir, ["worktree", "remove", "--force", path]);
+            gitOk(repoP.dir, ["branch", "-D", branch]);
+          },
+          closeDraft: async (ticketId, note) => {
+            const closed = cP.statuses.resolved.includes("closed_obsolete") ? "closed_obsolete" : cP.statuses.wontFix;
+            await trackerP.updateTicket(ticketId, { [cP.columns.status]: closed, [cP.columns.resolutionNote]: note });
+          },
+          now: () => /* @__PURE__ */ new Date(),
+          host: a.host ?? "localhost",
+          say
+        };
+        if (dryRun) {
+          await periscopePreflight(deps, a.repo);
+          say("dry-run", `would file "Periscope: ${a.topic ?? "<topic>"}" as ${cP.statuses.draft} for ${pairId}, cut a worktree for ${a.repo}, run setup${a.isolate ? ", isolate" : ""}, ports, handoff and preview on ${deps.host}, and record a Periscopes row (expires after ${caps.idleMinutes} minutes idle)`);
+          break;
+        }
+        const res = await runPeriscopeUp(deps, a);
+        if (jsonP) process.stdout.write(`${JSON.stringify({ event: "done", ...res })}
+`);
+        else process.stdout.write(`${res.ticket}
+${res.worktree}
+${res.url}
+`);
+      } catch (e) {
+        if (e instanceof PeriscopeError || e instanceof ConfigError) {
+          process.stderr.write(`crew periscope: ${e.message}
+`);
+          process.exit(1);
+        }
+        throw e;
+      }
+      break;
+    }
     case "unassign": {
       emit.enter("select");
       const rawUnassign = positional[2] ?? positional[1];
@@ -21848,6 +22182,7 @@ ${owed.map((l) => `  ${l}
         `ship:       ${cfg.ship.name} (${cfg.ship.platform})
 route:      ${route.route} -> ${route.dir}
 enabled:    ${route.enabled}
+periscopes: ${periscopeSummary(cfg)}
 crew:       ${state.isPaused() ? "paused" : "active"}
 release:    ${state.releaseSkipReason() ? "paused" : "active"}
 watermark:  ${state.watermark()}
@@ -21965,6 +22300,8 @@ watermark:  ${state.watermark()}
           }
         }
         for (const message of roleCapWarnings(cfg.ship)) problems.push({ severity: "note", kind: "role_cap_above_ship_cap", message });
+        const previewProblem2 = await previewHostProblem(cfg);
+        if (previewProblem2) problems.push({ severity: "blocker", kind: "preview_host", message: previewProblem2 });
         problems.push(...attentionProblems(openShipAttention(state), problems));
         if (problems.some((p) => p.severity === "blocker")) process.exitCode = 1;
         process.stdout.write(`${JSON.stringify({ offline: flag("offline"), pushAuth, tools: toolRows, problems, passed }, null, 2)}
@@ -21978,6 +22315,14 @@ routes:            ${cfg.routes.map((c) => c.route).join(", ")}
       );
       for (const w of roleCapWarnings(cfg.ship)) process.stdout.write(`role concurrency: WARN ${w}
 `);
+      process.stdout.write(`periscopes:        ${periscopeSummary(cfg)}
+`);
+      const previewProblem = await previewHostProblem(cfg);
+      if (previewProblem) {
+        process.stdout.write(`                   BLOCKER ${previewProblem}
+`);
+        process.exitCode = 1;
+      }
       try {
         const evFile = eventFileFor(cfg.ship.stateDir);
         const evSize = existsSync35(evFile) ? statSync10(evFile).size : 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tablation/crew",
-  "version": "0.83.0",
+  "version": "0.85.0",
   "description": "A standing team of headless agents that picks work off a Tablation board, does it on a machine you control, and reports back.",
   "type": "module",
   "license": "MIT",