@dylanpiercey/work 0.2.19 → 0.2.20

package/README.md

@@ -62,7 +62,9 @@ Inside a workspace, `work branches`, `work session`, `work topic`,
 `work review`, `work notify` and `work open`; agents start and message each
 other with `work session new|send|wait` — any vendor's, each in a tab of its
 own the user watches, its last message as a turn ends coming back to the
-one that asked as a prompt; to change things,
+one that asked as a prompt — and run groups of them with
+`work session fanout` and `work plan`, which the session list shows as a
+lead's team; to change things,
 `work workspace create`, `work repo add`, `work config get|set` (checked
 against what each setting takes; `work config schema` lists them),
 `work agent|skill|lsp|host` and `work gh login`; `work status` sums the

package/bin/cli/plan.mjs

@@ -0,0 +1,85 @@
+// `work plan`: the phases a lead agent's fan-outs fall under, and a line
+// of what it is doing as it goes (server/team.ts). It is what the team
+// view draws over the groups — the job as the lead sees it — and nothing
+// runs from it: the lead starts each phase's groups itself, with
+// `work session fanout --phase`.
+
+/** The session a command means: --session's, else this pane's own. */
+function sessionId(ctx) {
+  const id = ctx.flag("--session") || process.env.WORK_SESSION_ID;
+  if (!id)
+    ctx.die(
+      "a plan is a session's: run this in one (WORK_SESSION_ID is unset) or pass --session <id>",
+    );
+  return id;
+}
+
+/** `--phase "Title"` or `--phase "Title: what it does"`. */
+function phaseOf(text) {
+  const at = text.indexOf(":");
+  return at > 0
+    ? { title: text.slice(0, at).trim(), detail: text.slice(at + 1).trim() }
+    : { title: text.trim() };
+}
+
+export const commands = [
+  {
+    name: "plan",
+    summary: "a lead's phases and progress log, over its fan-outs",
+    help: `work plan [--json]
+  This session's plan: its phases, and the last lines it logged.
+work plan new "<name>" --phase "<title>[: what it does]" [--phase …]
+  Start a plan (ending this session's last): the phases its fan-outs fall
+  under, in order. \`work session fanout --phase <title>\` files a group
+  under one; the user sees each phase's members and how far they are.
+work plan log "<line>"
+  Say what you are doing, over the phases ("3 of 6 fixes pass;
+  reviewing them") — a narrator line, not a message to anyone.
+work plan done
+  End the plan.`,
+    async run(ctx) {
+      const [verb, ...rest] = ctx.parse(["--phase", "--session"]);
+      const me = sessionId(ctx);
+      switch (verb) {
+        case undefined: {
+          const plan = await ctx.api.get(`/api/sessions/${me}/plan`);
+          return ctx.out(plan, (p) => {
+            if (!p) return console.log('no plan: `work plan new "<name>"`');
+            console.log(`${p.name}${p.done ? " (done)" : ""}`);
+            for (const ph of p.phases)
+              console.log(`  ${ph.title}${ph.detail ? ` — ${ph.detail}` : ""}`);
+            for (const l of p.log) console.log(`  · ${l.text}`);
+          });
+        }
+        case "new": {
+          const name = rest.join(" ").trim();
+          if (!name)
+            ctx.die('usage: work plan new "<name>" --phase "<title>" […]');
+          const plan = await ctx.api.post(`/api/sessions/${me}/plan`, {
+            name,
+            phases: ctx.flags("--phase").map(phaseOf),
+          });
+          return ctx.out(plan, (p) =>
+            console.log(
+              `plan "${p.name}": ${p.phases.map((x) => x.title).join(" → ") || "no phases"}`,
+            ),
+          );
+        }
+        case "log": {
+          const line = rest.join(" ").trim();
+          if (!line) ctx.die('usage: work plan log "<line>"');
+          await ctx.api.patch(`/api/sessions/${me}/plan`, { log: line });
+          return ctx.out({ logged: line }, () =>
+            console.log(`logged: ${line}`),
+          );
+        }
+        case "done": {
+          await ctx.api.patch(`/api/sessions/${me}/plan`, { done: true });
+          return ctx.out({ done: true }, () => console.log("plan done"));
+        }
+        default:
+          ctx.die(`no \`work plan ${verb}\` (see: work help plan)`);
+      }
+    },
+  },
+];

package/bin/cli/session.mjs

@@ -1,10 +1,13 @@
 // `work session`: which session this is (an agent's own pane, by
 // WORK_SESSION_ID), its name in the session list, and the workspace's
-// other sessions — starting one, messaging it and waiting on its reply,
-// closing it (server/messages.ts).
+// other sessions — starting one or a fan-out of them, messaging one and
+// waiting on replies, closing them (server/messages.ts, server/team.ts).
+import path from "node:path";
+import { makeTopics, topicRepos } from "./topic.mjs";
 
-/** More sessions than this in one workspace is an agent starting them in
- * a loop, not a plan: past it, `new` wants --force. */
+/** More sessions than this running in one workspace is an agent starting
+ * them in a loop, not a plan: past it, `new` wants --force. A fan-out's
+ * members go through its pool instead. */
 const SESSION_CAP = 8;
 
 /** The session a command means: --session's, else this pane's own. */
@@ -97,10 +100,67 @@ function printReply(r) {
   if (r.kind === "reply") console.log(`${r.text}\n`);
 }
 
+/** Start folders for `count` sessions, a topic each (`<topic>`, or
+ * `<topic>-1`… for several) in the repos `--repo` names (else the cwd's):
+ * a member's worktree is its own, so their edits never meet. Relative
+ * to the workspace: a repo's worktree for one repo, the topic's folder
+ * for several. */
+async function topicDirs(ctx, topic, count) {
+  const { ws, picked } = await topicRepos(ctx);
+  const names =
+    count === 1
+      ? [topic]
+      : Array.from({ length: count }, (_, i) => `${topic}-${i + 1}`);
+  const made = makeTopics(ctx, ws, picked, names, {
+    install: ctx.has("--install"),
+  });
+  return {
+    names,
+    dirs: names.map((name) => {
+      const rows = made.filter((m) => m.topic === name);
+      const dir = rows.length === 1 ? rows[0].path : path.dirname(rows[0].path);
+      return path.relative(ws.path, dir);
+    }),
+    links: made.map((m) => m.link),
+  };
+}
+
+const STATUS_MARK = {
+  queued: "◌",
+  starting: "◔",
+  working: "⟳",
+  waiting: "⚠",
+  idle: "·",
+  done: "✓",
+  closed: "✕",
+};
+
+/** One group of `work session team`: its head, then a line a member. */
+function printGroup(ctx, g) {
+  const c = g.counts;
+  const left = c.queued + c.starting + c.working + c.waiting + c.idle;
+  const parts = [
+    `${c.done}/${g.members.length} done`,
+    c.working && `${c.working} working`,
+    c.waiting && `${c.waiting} waiting on the user`,
+    c.starting && `${c.starting} starting`,
+    c.queued && `${c.queued} queued`,
+    c.closed && `${c.closed} closed`,
+  ].filter(Boolean);
+  console.log(
+    `${g.phase ? `[${g.phase}] ` : ""}${g.id} "${g.title}"  ${parts.join(" · ")}  (${g.parallel} at a time, ${g.fanIn ? (left ? "replies held until all answer" : "replies sent as one") : "replies as each comes"})`,
+  );
+  for (const m of g.members)
+    console.log(
+      `  ${STATUS_MARK[m.status] ?? "?"} ${ctx.pad(m.status, 8)} ${ctx.pad(m.id, 9)} ${ctx.pad(m.session ?? "-", 9)} ${ctx.pad(m.agent, 8)} ${m.title}${m.line ? `  — ${m.line}` : ""}`,
+    );
+}
+
 export const commands = [
   {
     name: "session",
-    summary: "this session and the workspace's others: title, new, send, kill",
+    summary:
+      "this session and the workspace's others: new, fanout, send, wait, team, kill",
     help: `work session [--json]
   This session (WORK_SESSION_ID): its id, agent, name, state, and the
   workspace it is in (id, name, path) — what a link names (/w/<id>/…).
@@ -108,12 +168,40 @@ work session list [id|name] [--json]
   The workspace's sessions, this one marked.
 work session title "<name>" [--session <id>]
   Name a session in the session list (empty clears it).
-work session new [--agent <id>] [--title "<name>"] [--prompt "<text>"|-] [--no-reply] [--workspace <id|name>] [--force]
+work session new [--agent <id>] [--title "<name>"] [--prompt "<text>"|-] [--no-reply] [--keep] [--topic <name> [--repo <repo>…] [--install]] [--workspace <id|name>] [--force]
   Start a session (the default agent unless --agent, any vendor's; "shell"
-  for a terminal) in a tab of its own, where the user watches it, name it,
-  and hand it a first prompt ("-": read it from stdin). Started from
-  another session it is listed under that one, and the prompt is a
-  message from it (below). Past ${SESSION_CAP} sessions in the workspace it wants --force.
+  for a terminal) in a tab of its own, where the user can watch it, name
+  it, and hand it a first prompt ("-": read it from stdin). Started from
+  another session it is listed under that one, runs in its permission
+  mode (it is an agent's to drive: nobody waits on it to answer a prompt),
+  and the prompt is a message from it (below). --topic starts it in a
+  topic branch of its own (\`work topic new\`). It closes once it has
+  answered and is done with — when your job finishes, or after ten idle
+  minutes — unless --keep, it is on the user's screen, or they have typed
+  into it. Past ${SESSION_CAP} running sessions in the workspace it wants --force.
+work session fanout --agent <id> [--agent <id>…] [--count <n>] --prompt "<text>"|- [<item>…] [--title "<name>"] [--phase "<phase>"] [--parallel <n>] [--stream] [--close-done|--keep] [--topic <name> [--repo <repo>…] [--install]]
+  Start a group of sessions from this one: each --agent once (or --count
+  times), or once for each <item> with {} in the prompt replaced by it
+  ({i} is the member's number). They queue and start --parallel at a time
+  (4), however many there are. Their replies come back to you as one
+  prompt once every member has answered (--stream: each as it comes); end
+  your turn to wait, or \`work session wait <group>\`. A member's session
+  closes once done with, as \`new\`'s does (its result is kept);
+  --close-done closes it as soon as it answers, --keep never;
+  --topic gives each member a topic branch of its own (<name>-1, -2, …),
+  side by side in Review; --phase files the group under that phase of your
+  plan (\`work plan\`). For a quick sweep inside your own CLI, its own
+  subagents are cheaper: this is for other vendors, long work, or work the
+  user may want to watch.
+work session team [--json]
+  This session's plan and groups: each member (its id, then its
+  session's), its state and its last line (what it is doing, or its
+  result).
+work session retry <member>
+  Rerun a closed member in a fresh session: its group waits for it again.
+work session skip <member>
+  Stop a member: a queued one never starts, a running one's session
+  closes; either way its group no longer waits on it.
 work session send <id> "<text>"|- [--no-reply]
   Message an agent session: typed in, headed with who it is from, once
   it is at its prompt — never into a turn under way, a question it asks,
@@ -121,13 +209,19 @@ work session send <id> "<text>"|- [--no-reply]
   unless --no-reply: the recipient's last message as that turn ends,
   typed into this session as a prompt of its own. End your turn to wait
   for it. A file's path says more than its text pasted in.
-work session wait [<id>...] [--timeout <seconds>]
-  Wait for the replies owed to this session (by those sessions, else by
-  any), printing each as it comes; a reply printed here is not typed in
-  too. Exits 124 if some are still working after --timeout (${WAIT_S} s).
-work session kill <id> --yes
-  Close a session and the process in it (whoever waits on its reply is
-  told).`,
+work session wait [<id>|<group>...] [--any] [--timeout <seconds>]
+  Wait for the replies owed to this session (by those sessions or groups,
+  else by any), printing each as it comes; a reply printed here is not
+  typed in too. A group's come once all its members have answered, unless
+  --any: then whatever is in, as soon as anything is. Exits 124 if some
+  are still working after --timeout (${WAIT_S} s).
+work session kill <id> [--keep-children] --yes
+  Close a session and the process in it, and the sessions it started
+  with theirs, unless --keep-children (they then stand on their own).
+  Whoever waits on a reply from one is told.
+work session kill --done
+  Close now the sessions this one started that are done with (answered,
+  idle, not the user's): fan-out results stay in \`work session team\`.`,
     async run(ctx) {
       const [verb, ...rest] = ctx.parse([
         "--agent",
@@ -136,6 +230,11 @@ work session kill <id> --yes
         "--workspace",
         "--session",
         "--timeout",
+        "--topic",
+        "--repo",
+        "--count",
+        "--parallel",
+        "--phase",
       ]);
       switch (verb) {
         case undefined: {
@@ -182,17 +281,26 @@ work session kill <id> --yes
         }
         case "new": {
           const { ws } = await ctx.resolveWorkspace(ctx.flag("--workspace"));
-          const existing = await sessionsOf(ctx, ws.id);
-          if (existing.length >= SESSION_CAP && !ctx.has("--force"))
+          const running = (await sessionsOf(ctx, ws.id)).filter(
+            (s) => s.phase !== "off",
+          );
+          if (running.length >= SESSION_CAP && !ctx.has("--force"))
             ctx.die(
-              `${ws.name} already has ${existing.length} sessions: pass --force to start another`,
+              `${ws.name} already has ${running.length} sessions running: pass --force to start another (a group of them is \`work session fanout\`, which queues)`,
             );
           const agent = ctx.flag("--agent");
           const me = process.env.WORK_SESSION_ID;
           const prompt = await textOf(valueOf(ctx, "--prompt"));
+          const topic = ctx.flag("--topic");
+          const at = topic ? await topicDirs(ctx, topic, 1) : null;
           const created = await ctx.api.post(
             `/api/workspaces/${ws.id}/sessions`,
-            { ...(agent ? { agent } : {}), ...(me ? { parent: me } : {}) },
+            {
+              ...(agent ? { agent } : {}),
+              ...(me ? { parent: me } : {}),
+              ...(at ? { dir: at.dirs[0] } : {}),
+              ...(ctx.has("--keep") ? { keep: true } : {}),
+            },
           );
           const title = ctx.flag("--title");
           if (title)
@@ -212,6 +320,7 @@ work session kill <id> --yes
             title: title || null,
             workspace: ws.id,
             parent: created.parent_id ?? null,
+            topic: topic ?? null,
             prompted: !!sent?.delivered,
             queued: sent?.queued ?? null,
             wantsReply: !!sent?.wantsReply,
@@ -219,7 +328,7 @@ work session kill <id> --yes
           };
           return ctx.out(out, (s) => {
             console.log(
-              `started ${s.id} (${s.agent})${s.prompted ? " with its prompt" : ""}: [${s.title || s.agent}](${s.href})`,
+              `started ${s.id} (${s.agent})${s.prompted ? " with its prompt" : ""}${s.topic ? ` on topic ${s.topic}` : ""}: [${s.title || s.agent}](${s.href})`,
             );
             if (s.queued)
               console.log(`its prompt waits to be typed in: ${s.queued}`);
@@ -229,6 +338,94 @@ work session kill <id> --yes
               );
           });
         }
+        case "fanout": {
+          const me = sessionId(ctx);
+          const agents = ctx.flags("--agent");
+          if (!agents.length)
+            ctx.die(
+              'usage: work session fanout --agent <id> [--agent <id>…] --prompt "<text>"|- [<item>…] (see: work help session)',
+            );
+          const prompt = await textOf(valueOf(ctx, "--prompt"));
+          if (!prompt) ctx.die("a fan-out needs a --prompt");
+          // A "-" is --prompt's stdin, not an item.
+          const items = rest.filter((i) => i !== "-");
+          const count = ctx.has("--count") ? Number(ctx.flag("--count")) : 1;
+          if (!Number.isInteger(count) || count < 1)
+            ctx.die("--count is a whole number of members per agent");
+          if (items.length && ctx.has("--count"))
+            ctx.die("--count or items, not both: items already say how many");
+          const parallel = ctx.has("--parallel")
+            ? Number(ctx.flag("--parallel"))
+            : undefined;
+          if (
+            parallel !== undefined &&
+            (!Number.isInteger(parallel) || parallel < 1)
+          )
+            ctx.die("--parallel is a whole number of members at once");
+          // Members in the server's order: by agent, then by item or number.
+          const total = new Set(agents).size * (items.length || count);
+          const topic = ctx.flag("--topic");
+          const at = topic ? await topicDirs(ctx, topic, total) : null;
+          const g = await ctx.api.post(`/api/sessions/${me}/groups`, {
+            title: ctx.flag("--title") ?? "",
+            prompt,
+            agents,
+            ...(items.length ? { items } : { count }),
+            ...(parallel ? { parallel } : {}),
+            ...(ctx.has("--phase") ? { phase: ctx.flag("--phase") } : {}),
+            fanIn: !ctx.has("--stream"),
+            closeDone: ctx.has("--close-done"),
+            keep: ctx.has("--keep"),
+            ...(at ? { dirs: at.dirs } : {}),
+          });
+          return ctx.out({ ...g, topics: at?.names ?? null }, (g) => {
+            console.log(
+              `fanned out ${g.id} "${g.title}": ${g.members.length} ${g.members.length === 1 ? "member" : "members"}, ${g.parallel} at a time`,
+            );
+            for (const m of g.members)
+              console.log(
+                `  ${ctx.pad(m.id, 10)} ${ctx.pad(m.agent, 8)} ${m.title}`,
+              );
+            if (at) for (const l of at.links) console.log(`  review: ${l}`);
+            console.log(
+              g.fanIn
+                ? `Their replies come back to you as one prompt once every member has answered: end your turn to wait, or run \`work session wait ${g.id}\`. \`work session team\` shows how far they are.`
+                : `Each reply comes back to you as a prompt as it comes: end your turn to wait, or run \`work session wait ${g.id} --any\`.`,
+            );
+          });
+        }
+        case "team": {
+          const me = sessionId(ctx);
+          const t = await ctx.api.get(`/api/sessions/${me}/team`);
+          return ctx.out(t, (t) => {
+            if (!t.plan && !t.groups.length)
+              return console.log(
+                "no plan or groups: `work session fanout` starts one",
+              );
+            if (t.plan) {
+              console.log(
+                `plan "${t.plan.name}"${t.plan.done ? " (done)" : ""}: ${t.plan.phases.map((p) => p.title).join(" → ") || "no phases"}`,
+              );
+              for (const l of t.plan.log) console.log(`  · ${l.text}`);
+            }
+            for (const g of t.groups) printGroup(ctx, g);
+          });
+        }
+        case "retry":
+        case "skip": {
+          const [member] = rest;
+          if (!member) ctx.die(`usage: work session ${verb} <member>`);
+          await ctx.api.post(`/api/members/${member}/${verb}`);
+          return ctx.out(
+            { member, [verb === "retry" ? "retried" : "skipped"]: true },
+            () =>
+              console.log(
+                verb === "retry"
+                  ? `queued ${member} again`
+                  : `skipped ${member}`,
+              ),
+          );
+        }
         case "send": {
           const [id, ...words] = rest;
           const text = await textOf(words.join(" "));
@@ -248,8 +445,9 @@ work session kill <id> --yes
           const seconds = raw === undefined ? WAIT_S : Number(raw);
           if (!Number.isFinite(seconds) || seconds < 0)
             ctx.die("--timeout is a number of seconds");
+          const any = ctx.has("--any");
           const until = Date.now() + seconds * 1000;
-          const body = rest.length ? { from: rest } : {};
+          const body = { ...(rest.length ? { from: rest } : {}), any };
           const replies = [];
           let owing = [];
           for (;;) {
@@ -258,6 +456,7 @@ work session kill <id> --yes
             if (!ctx.json) r.replies.forEach(printReply);
             owing = r.owing;
             if (!owing.length || Date.now() >= until) break;
+            if (any && replies.length) break;
             await new Promise((res) => setTimeout(res, POLL_MS));
           }
           if (ctx.json)
@@ -268,24 +467,61 @@ work session kill <id> --yes
                 ? `nothing owed by ${rest.join(", ")}: a reply already typed in is in your prompt`
                 : "no session owes this one a reply",
             );
-          if (owing.length) {
+          if (owing.length && !(any && replies.length)) {
             ctx.warn(
               `still working: ${owing.map((o) => o.label).join(", ")} (wait again, or end your turn: the reply comes as a prompt)`,
             );
             process.exitCode = 124;
-          }
+          } else if (owing.length && !ctx.json)
+            console.log(
+              `still working: ${owing.map((o) => o.label).join(", ")}`,
+            );
           return;
         }
         case "kill": {
+          if (ctx.has("--done")) {
+            const me = sessionId(ctx);
+            const { closed } = await ctx.api.post(
+              `/api/sessions/${me}/close-done`,
+            );
+            return ctx.out({ closed }, () =>
+              console.log(
+                closed
+                  ? `closed ${closed} finished ${closed === 1 ? "session" : "sessions"}`
+                  : "none of the sessions this one started is done with",
+              ),
+            );
+          }
           const [id] = rest;
-          if (!id) ctx.die("usage: work session kill <id> --yes");
-          if (!ctx.yes)
+          if (!id)
             ctx.die(
-              `closing ${id} ends the process in it${id === process.env.WORK_SESSION_ID ? " — this session, the one running this command" : ""}: pass --yes`,
+              "usage: work session kill <id> [--keep-children] --yes, or --done",
             );
-          await ctx.api.del(`/api/sessions/${id}`);
-          return ctx.out({ id, killed: true }, () =>
-            console.log(`closed ${id}`),
+          const keep = ctx.has("--keep-children");
+          if (!ctx.yes) {
+            // Said before it happens: what else goes with it.
+            const { ws } = await ctx.resolveWorkspace(ctx.flag("--workspace"));
+            const list = await sessionsOf(ctx, ws.id);
+            const family = [id];
+            for (let i = 0; i < family.length; i++)
+              for (const s of list)
+                if (s.parent === family[i] && !family.includes(s.id))
+                  family.push(s.id);
+            const others = keep ? 0 : family.length - 1;
+            ctx.die(
+              `closing ${id} ends the process in it${others ? ` and in the ${others} ${others === 1 ? "session" : "sessions"} it started (${family.slice(1).join(", ")}; --keep-children keeps them)` : ""}${(keep ? [id] : family).includes(process.env.WORK_SESSION_ID) ? " — this session, the one running this command, among them" : ""}: pass --yes`,
+            );
+          }
+          const r = await ctx.api.del(
+            `/api/sessions/${id}${keep ? "?children=keep" : ""}`,
+          );
+          const closed = r?.closed ?? [id];
+          return ctx.out({ id, killed: true, closed }, () =>
+            console.log(
+              closed.length > 1
+                ? `closed ${id} and the sessions it started: ${closed.slice(1).join(", ")}`
+                : `closed ${id}`,
+            ),
           );
         }
         default:

package/bin/cli/topic.mjs

@@ -170,65 +170,69 @@ function fetch(ctx, repo) {
 
 // -- new ---------------------------------------------------------------------
 
-async function topicNew(ctx) {
-  const [name] = ctx.parse(["--repo", "--from"]);
-  if (!name)
-    ctx.die("usage: work topic new <name> [--repo <repo>…] [--from <ref>]");
-  if (!NAME.test(name) || name.includes(".."))
-    ctx.die(
-      `"${name}" is not a topic name: letters, digits, \`-\`, \`_\`, and \`.\` for a group (\`<group>.<topic>\`)`,
-    );
-  const { ws, repos } = await context(ctx, false);
-  const branch = `${ws.branch}-${name}`;
-  const from = ctx.has("--from") ? ctx.flag("--from") : null;
-  const picked = pickRepos(ctx, ws, repos);
-  for (const repo of picked) {
-    if (
-      !git(repo.dir, ["check-ref-format", "--branch", branch], {
-        allowFail: true,
-      }).ok
-    )
-      ctx.die(`${branch} is not a branch name git takes`);
-  }
-  // Every refusal before anything is made: half a topic is worse than none.
-  const plans = [];
-  for (const repo of picked) {
-    fetch(ctx, repo);
-    const dest = topicDir(ws, name, repo);
-    if (has(repo.dir, `refs/heads/${branch}`))
+/** Make the topics `names`, each a branch off its base and a worktree in
+ * every repo `picked`, and run each's install with `install`. Every
+ * refusal comes before anything is made: half a topic is worse than
+ * none, and half a fan-out's worse still. Returns a row per worktree. */
+export function makeTopics(
+  ctx,
+  ws,
+  picked,
+  names,
+  { from = null, install = false } = {},
+) {
+  for (const name of names)
+    if (!NAME.test(name) || name.includes(".."))
       ctx.die(
-        `${repo.worktree}: ${branch} already exists${worktreesOf(repo.dir).get(branch) ? ` (at ${worktreesOf(repo.dir).get(branch)})` : ""} — pick another name, or work in it`,
+        `"${name}" is not a topic name: letters, digits, \`-\`, \`_\`, and \`.\` for a group (\`<group>.<topic>\`)`,
       );
-    if (has(repo.dir, `refs/remotes/origin/${branch}`))
-      ctx.die(
-        `${repo.worktree}: ${branch} is already on origin — check it out there (git -C ${repo.dir} worktree add ${dest} ${branch}) rather than starting it again`,
-      );
-    if (fs.existsSync(dest)) ctx.die(`${dest} already exists`);
-    const start = from ?? `origin/${repo.base_branch}`;
-    if (!has(repo.dir, `${start}^{commit}`))
-      ctx.die(`${repo.worktree}: no ${start} to start from`);
-    plans.push({ repo, dest, start });
+  for (const repo of picked) fetch(ctx, repo);
+  const plans = [];
+  for (const name of names) {
+    const branch = `${ws.branch}-${name}`;
+    for (const repo of picked) {
+      if (
+        !git(repo.dir, ["check-ref-format", "--branch", branch], {
+          allowFail: true,
+        }).ok
+      )
+        ctx.die(`${branch} is not a branch name git takes`);
+      const dest = topicDir(ws, name, repo);
+      if (has(repo.dir, `refs/heads/${branch}`))
+        ctx.die(
+          `${repo.worktree}: ${branch} already exists${worktreesOf(repo.dir).get(branch) ? ` (at ${worktreesOf(repo.dir).get(branch)})` : ""} — pick another name, or work in it`,
+        );
+      if (has(repo.dir, `refs/remotes/origin/${branch}`))
+        ctx.die(
+          `${repo.worktree}: ${branch} is already on origin — check it out there (git -C ${repo.dir} worktree add ${dest} ${branch}) rather than starting it again`,
+        );
+      if (fs.existsSync(dest)) ctx.die(`${dest} already exists`);
+      const start = from ?? `origin/${repo.base_branch}`;
+      if (!has(repo.dir, `${start}^{commit}`))
+        ctx.die(`${repo.worktree}: no ${start} to start from`);
+      plans.push({ name, branch, repo, dest, start });
+    }
   }
   const made = [];
-  for (const { repo, dest, start } of plans) {
+  for (const { name, branch, repo, dest, start } of plans) {
     fs.mkdirSync(path.dirname(dest), { recursive: true });
     // --no-track: its upstream is set by the first push, to its own name on
     // origin, never to the base it was cut from.
     git(repo.dir, ["worktree", "add", "--no-track", "-b", branch, dest, start]);
-    const install = installFor(dest);
     const stacked = from && from !== `origin/${repo.base_branch}` ? from : null;
     made.push({
+      topic: name,
       repo: repo.worktree,
       branch,
       path: dest,
       base: repo.base_branch,
       from: start,
       stacked,
-      install,
+      install: installFor(dest),
       link: link(ws, repo, name),
     });
   }
-  if (ctx.has("--install")) {
+  if (install) {
     for (const m of made) {
       if (!m.install) continue;
       ctx.log(`${m.repo}: ${m.install}`);
@@ -242,6 +246,25 @@ async function topicNew(ctx) {
       if (!m.installed) ctx.warn(`${m.repo}: \`${m.install}\` failed`);
     }
   }
+  return made;
+}
+
+/** The workspace, its repos, and the ones a command names (`--repo`, else
+ * the one the cwd is in): what `makeTopics` takes. */
+export async function topicRepos(ctx) {
+  const { ws, repos } = await context(ctx, false);
+  return { ws, picked: pickRepos(ctx, ws, repos) };
+}
+
+async function topicNew(ctx) {
+  const [name] = ctx.parse(["--repo", "--from"]);
+  if (!name)
+    ctx.die("usage: work topic new <name> [--repo <repo>…] [--from <ref>]");
+  const { ws, picked } = await topicRepos(ctx);
+  const made = makeTopics(ctx, ws, picked, [name], {
+    from: ctx.has("--from") ? ctx.flag("--from") : null,
+    install: ctx.has("--install"),
+  }).map(({ topic: _, ...m }) => m);
   ctx.out(made, (rows) => {
     for (const m of rows) {
       console.log(`${m.repo}/ on ${m.branch}`);