@tablation/crew 0.84.0 → 0.86.0

package/dist/cli.js

@@ -5606,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",
@@ -6879,6 +6879,59 @@ 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 } : {} });
+  }
+  /**
+   * This ship's Periscopes rows (EPIC-077), newest first, with the ticket each
+   * belongs to. Empty when there is no Periscopes table or no Ships row yet.
+   */
+  async periscopeRows(states) {
+    const modelId = this.route.resolved?.periscopesModelId;
+    const { shipId } = await this.authorshipProbe();
+    if (!modelId || !shipId) return [];
+    const conds = [{ columnName: "ship_id", operator: "EQ", value: shipId }];
+    if (states?.length) conds.push({ columnName: "state", operator: "IN", value: states });
+    const rows = await this.client.records.list(modelId, { filters: encodeFilters(conds), limit: 200 });
+    const refId = (v) => typeof v === "string" ? v : v && typeof v === "object" && typeof v.id === "string" ? v.id : void 0;
+    const ids = [...new Set(rows.map((r) => refId(r.issue_id)).filter((x) => !!x))];
+    const tickets = new Map((await this.ticketsByIds(ids)).map((t) => [t.id, t]));
+    const out = [];
+    for (const row of rows) {
+      const t = tickets.get(refId(row.issue_id) ?? "");
+      if (t) out.push({ row, ticket: t });
+    }
+    return out.sort((a, b) => String(b.row.started_at ?? "").localeCompare(String(a.row.started_at ?? "")));
+  }
+  /** Updates one Periscopes row (EPIC-077). */
+  async updatePeriscope(id, patch2) {
+    const modelId = this.route.resolved?.periscopesModelId;
+    if (!modelId) throw new Error("this workspace has no Periscopes table");
+    await this.client.records.update(modelId, id, patch2);
+  }
   /**
    * The authorship columns this workspace is missing, as `table.column` names
    * for `crew doctor` to report (CREW-1371). Empty on a fully updated install.
@@ -9102,8 +9155,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;
@@ -9112,7 +9165,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;
@@ -9131,20 +9184,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";
@@ -9692,7 +9745,9 @@ var VALUE_FLAGS = /* @__PURE__ */ new Set([
   "toolchain",
   "workspace",
   "workspace-id",
-  "write"
+  "write",
+  "topic",
+  "assignee"
 ]);
 function positionalArgs(argv2) {
   const out = [];
@@ -13032,7 +13087,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]);
@@ -13047,12 +13102,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 });
       }
     }
   }
@@ -16373,6 +16428,242 @@ 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 };
+}
+function parsePeriscopeDownArgs(positional2, flags) {
+  const usage2 = "usage: crew periscope down [route] NNN --keep|--discard [--allow-empty] [--json]";
+  const rest = positional2.slice(2);
+  if (rest.length === 0 || rest.length > 2) throw new PeriscopeError(usage2);
+  if (flags.keep === flags.discard) throw new PeriscopeError(`pass exactly one of --keep or --discard
+${usage2}`);
+  const m = /^(?:[A-Za-z]+-)?(\d+)$/.exec(rest[rest.length - 1]);
+  if (!m) throw new PeriscopeError(`"${rest[rest.length - 1]}" is not a ticket number
+${usage2}`);
+  return {
+    ...rest.length === 2 ? { route: rest[0] } : {},
+    number: m[1],
+    mode: flags.keep ? "keep" : "discard",
+    allowEmpty: flags.allowEmpty,
+    json: flags.json
+  };
+}
+var PROTOTYPE_HEADING = "## Prototype";
+function prototypeSection(files) {
+  const added = files.reduce((n, f) => n + f.added, 0);
+  const removed = files.reduce((n, f) => n + f.removed, 0);
+  return [
+    PROTOTYPE_HEADING,
+    "",
+    "This branch began as a Periscope prototype and may be rewritten rather than treated as reviewed work.",
+    "",
+    ...files.length === 0 ? ["No files differ from the base."] : files.map((f) => `- \`${f.path}\` (+${f.added} \u2212${f.removed})`),
+    "",
+    `${files.length} file${files.length === 1 ? "" : "s"} changed, ${added} insertion${added === 1 ? "" : "s"}(+), ${removed} deletion${removed === 1 ? "" : "s"}(\u2212)`
+  ].join("\n");
+}
+async function runPeriscopeDown(d, args) {
+  const rows = await d.rowsForTicket(args.number);
+  if (rows.length === 0) throw new PeriscopeError(`no periscope for ticket ${args.number} on this ship`);
+  const row = rows.find((r) => r.state === "live");
+  if (!row) {
+    const done = rows[0];
+    d.say("unchanged", `${done.ticket} is already ${done.state}; nothing to do`);
+    return { ticket: done.ticket, mode: args.mode, outcome: "unchanged", state: done.state };
+  }
+  if (args.mode === "discard") {
+    const killed2 = await d.stopServer(row.worktree, row.number);
+    d.say("server", killed2 ? `stopped ${killed2} process(es)` : "no server was listening");
+    d.removeWorktree(row.worktree, row.branch, true);
+    d.say("worktree", `removed ${row.worktree} and branch ${row.branch}`);
+    await d.updateTicket(row.ticketRecordId, {
+      status: "discarded",
+      fillProjectAndRepo: false,
+      note: "The periscope was discarded; nothing was pushed."
+    });
+    d.say("ticket", `${row.ticket} closed as obsolete`);
+    await d.setRowState(row.id, "discarded");
+    d.say("row", "row is discarded");
+    return { ticket: row.ticket, mode: "discard", outcome: "done", state: "discarded" };
+  }
+  const dirty = d.hasChanges(row.worktree);
+  if (!dirty && !args.allowEmpty) {
+    throw new PeriscopeError(`${row.ticket} has nothing to commit; pass --allow-empty to keep the branch anyway, or --discard`);
+  }
+  if (dirty) {
+    d.commitAll(row.worktree, `${row.ticket} Periscope prototype`);
+    d.say("commit", `committed the worktree on ${row.branch}`);
+  }
+  const pushed = d.push(row.worktree, row.branch);
+  d.say("push", `pushed ${pushed.sha} to ${pushed.remote}/${row.branch}`, { sha: pushed.sha });
+  const t = await d.readTicket(row.ticketRecordId);
+  const section = prototypeSection(d.changedFiles(row.worktree));
+  const description = t.description.includes(PROTOTYPE_HEADING) ? t.description : `${t.description.trimEnd()}
+
+${section}`;
+  await d.updateTicket(row.ticketRecordId, {
+    description,
+    fillProjectAndRepo: !t.hasProject || !t.hasRepo,
+    status: "new"
+  });
+  d.say("ticket", `${row.ticket} is new and unassigned with a Prototype section`);
+  await d.postPushed(row.ticketRecordId, pushed.sha, pushed.remote, row.branch);
+  const killed = await d.stopServer(row.worktree, row.number);
+  d.say("server", killed ? `stopped ${killed} process(es)` : "no server was listening");
+  d.removeWorktree(row.worktree, row.branch, false);
+  d.say("worktree", `removed ${row.worktree}; ${row.branch} stays, pushed`);
+  await d.setRowState(row.id, "kept");
+  d.say("row", "row is kept");
+  return { ticket: row.ticket, mode: "keep", outcome: "done", state: "kept", sha: pushed.sha };
+}
+function periscopeListEntries(rows, now, isListening) {
+  return rows.filter((r) => r.state === "live").map((r) => {
+    const at = r.lastActivityAt ? new Date(r.lastActivityAt).getTime() : NaN;
+    return { ...r, idleMinutes: Number.isNaN(at) ? null : Math.max(0, Math.floor((now.getTime() - at) / 6e4)), listening: isListening(r) };
+  });
+}
+function formatPeriscopeList(entries) {
+  if (entries.length === 0) return "no live periscopes on this ship";
+  return entries.map((e) => [
+    e.ticket,
+    e.repo,
+    e.worktree,
+    e.url,
+    e.state,
+    e.idleMinutes === null ? "idle ?" : `idle ${e.idleMinutes} min`,
+    e.listening ? "listening" : "not listening"
+  ].join("  ")).join("\n");
+}
+
+// src/cli.ts
 import { dirname as dirOf, resolve as resolvePath } from "path";
 
 // src/ssh-keys.ts
@@ -17833,6 +18124,11 @@ 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 periscope down [route] NNN --keep|--discard [--allow-empty] [--json]
+                                 end a periscope: commit and push its branch (ticket back to new), or throw it away (alias: end)
+  crew periscope list [route] [--json]   the live periscopes on this ship, their idle minutes and whether each server is listening
   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
@@ -17925,6 +18221,7 @@ var KNOWN_COMMANDS = /* @__PURE__ */ new Set([
   "merge",
   "passengers",
   "pause",
+  "periscope",
   "poll",
   "ports",
   "projects",
@@ -18128,7 +18425,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);
@@ -21209,7 +21506,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,
@@ -21256,6 +21553,258 @@ 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" && subP !== "down" && subP !== "end" && subP !== "list") {
+        process.stderr.write("crew periscope up [route] REPO --topic TEXT [--isolate] [--host H] [--assignee ID] [--dry-run] [--json]\n");
+        process.stderr.write("crew periscope down [route] NNN --keep|--discard [--allow-empty] [--json]\n");
+        process.stderr.write("crew periscope list [route] [--json]\n");
+        process.exit(2);
+      }
+      const jsonP = flag("json");
+      const say = (event, message, data = {}) => process.stderr.write(jsonP ? `${JSON.stringify({ ...data, event, message })}
+` : `${message}
+`);
+      if (subP === "down" || subP === "end" || subP === "list") {
+        try {
+          const downArgs = subP === "list" ? void 0 : parsePeriscopeDownArgs(positional, { keep: flag("keep"), discard: flag("discard"), allowEmpty: flag("allow-empty"), json: jsonP });
+          const routeName = subP === "list" ? positional[2] : downArgs.route;
+          const routesP = (routeName ? [findRoute(cfg, routeName)] : cfg.routes.filter((r) => r.enabled)).filter((r) => r.resolved?.periscopesModelId);
+          if (routesP.length === 0) throw new PeriscopeError("no connected route has a Periscopes table");
+          const gather = async (rt) => {
+            const tr = new Tracker(rt, cfg.ship);
+            const repos = await resolvedRepos(rt);
+            return (await tr.periscopeRows()).map(({ row, ticket }) => {
+              const repo = repos.find((r) => r.id && r.id === ticket[tr.contract.columns.repo]) ?? (repos.length === 1 ? repos[0] : void 0);
+              const str = (v) => typeof v === "string" ? v : "";
+              return {
+                id: row.id,
+                ticketRecordId: ticket.id,
+                ticket: ticket.issue_tag ?? ticket.issue_id,
+                number: /(\d+)$/.exec(ticket.issue_id)?.[1] ?? "",
+                repo: repo?.name ?? "?",
+                state: str(row.state),
+                url: str(row.url),
+                worktree: str(row.worktree),
+                branch: str(row.branch),
+                lastActivityAt: str(row.last_activity_at) || null
+              };
+            });
+          };
+          if (subP === "list") {
+            const entries = periscopeListEntries(
+              (await Promise.all(routesP.map(gather))).flat(),
+              /* @__PURE__ */ new Date(),
+              (r) => pidsInWorktree(r.worktree, Number(r.number)).length > 0
+            );
+            process.stdout.write(jsonP ? `${JSON.stringify(entries)}
+` : `${formatPeriscopeList(entries)}
+`);
+            break;
+          }
+          const a = downArgs;
+          const hits = [];
+          for (const rt of routesP) {
+            const rows = (await gather(rt)).filter((r) => r.number === a.number);
+            if (rows.length) hits.push({ rt, rows });
+          }
+          if (hits.length !== 1) {
+            throw new PeriscopeError(hits.length === 0 ? `no periscope for ticket ${a.number} on this ship` : `ticket ${a.number} has periscopes on more than one route (${hits.map((h) => h.rt.route).join(", ")}) \u2014 name the route`);
+          }
+          const { rt: routeD, rows: rowsD } = hits[0];
+          const trD = new Tracker(routeD, cfg.ship);
+          const cD = trD.contract;
+          const reposD = await resolvedRepos(routeD);
+          const repoD = reposD.find((r) => r.name === rowsD[0].repo);
+          if (!repoD) throw new PeriscopeError(`cannot tell which repository ${rowsD[0].ticket} belongs to`);
+          const { remote, base } = repoD.config.branch;
+          const memberD = routeD.resolved.seats.pair ?? routeD.resolved.operator;
+          const closedD = cD.statuses.resolved.includes("closed_obsolete") ? "closed_obsolete" : cD.statuses.wontFix;
+          const depsD = {
+            rowsForTicket: async () => rowsD,
+            hasChanges: (wt) => status(wt).length > 0,
+            commitAll: (wt, msg) => {
+              git(wt, ["add", "-A"]);
+              git(wt, ["commit", "-m", msg]);
+            },
+            push: (wt, branch) => {
+              pushBranchUpstream(wt, remote, branch);
+              return { sha: headSha(wt), remote };
+            },
+            changedFiles: (wt) => {
+              const out = gitOk(wt, ["diff", "--numstat", `${remote}/${base}...HEAD`]) ?? "";
+              return out.split("\n").filter(Boolean).map((l) => {
+                const [add, rem, ...p] = l.split("	");
+                return { path: p.join("	"), added: Number(add) || 0, removed: Number(rem) || 0 };
+              });
+            },
+            readTicket: async (id) => {
+              const t = await trD.ticket(id);
+              return { description: String(t.description ?? ""), hasProject: !!t[cD.columns.slice], hasRepo: !!t[cD.columns.repo] };
+            },
+            updateTicket: async (id, p) => {
+              const patch2 = {};
+              if (p.status === "new") {
+                patch2[cD.columns.status] = "new";
+                patch2[cD.columns.assignee] = null;
+                if (p.description !== void 0) patch2.description = p.description;
+                if (p.fillProjectAndRepo) {
+                  if (routeD.resolved.areaId) patch2[cD.columns.slice] = routeD.resolved.areaId;
+                  if (repoD.id) patch2[cD.columns.repo] = repoD.id;
+                }
+              } else {
+                patch2[cD.columns.status] = closedD;
+                patch2[cD.columns.resolutionNote] = p.note;
+              }
+              await trD.updateTicket(id, patch2);
+            },
+            postPushed: (id, sha, rem, branch) => trD.postEvent(id, pushedEventBody(sha, rem, branch), memberD, "pushed"),
+            stopServer: async (wt, n) => {
+              const pids = pidsInWorktree(wt, Number(n));
+              if (pids.length) await killGently(pids);
+              return pids.length;
+            },
+            removeWorktree: (wt, branch, deleteBranch) => {
+              gitOk(repoD.dir, ["worktree", "remove", "--force", wt]);
+              if (deleteBranch) gitOk(repoD.dir, ["branch", "-D", branch]);
+            },
+            setRowState: (id, state2) => trD.updatePeriscope(id, { state: state2 }),
+            say
+          };
+          if (dryRun) {
+            say("dry-run", `would end the periscope for ${rowsD[0].ticket} (${a.mode})`);
+            break;
+          }
+          const res = await runPeriscopeDown(depsD, a);
+          if (jsonP) process.stdout.write(`${JSON.stringify({ event: "done", ...res })}
+`);
+          else process.stdout.write(`${res.ticket} ${res.state}
+`);
+        } catch (e) {
+          if (e instanceof PeriscopeError || e instanceof ConfigError) {
+            process.stderr.write(`crew periscope: ${e.message}
+`);
+            process.exit(1);
+          }
+          throw e;
+        }
+        break;
+      }
+      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];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tablation/crew",
-  "version": "0.84.0",
+  "version": "0.86.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",