@dylanpiercey/work 0.2.18 → 0.2.20

package/README.md

@@ -59,7 +59,12 @@ work-source                # status
 Everything the app's pages do has a `work` command too, so an agent — or a
 script — can use and set up work from a terminal: `work help` lists them.
 Inside a workspace, `work branches`, `work session`, `work topic`,
-`work review`, `work notify` and `work open`; to change things,
+`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 — 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,9 +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, sending it a prompt, closing it.
+// 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. */
@@ -16,27 +20,147 @@ function sessionId(ctx) {
   return id;
 }
 
-/** The workspace's sessions with their state, this pane's marked. */
+/** How long `wait` waits by default: inside an agent's own tool limit
+ * (ten minutes for most), so it ends saying who is still working rather
+ * than being killed. */
+const WAIT_S = 540;
+const POLL_MS = 1500;
+
+/** The workspace's sessions with their state, this pane's marked, each
+ * after the session that started it (as the sidebar lists them). */
 async function sessionsOf(ctx, wsId) {
   const me = process.env.WORK_SESSION_ID;
   const list = await ctx.api.get(`/api/workspaces/${wsId}/sessions`);
-  return list.map((s) => ({
+  const rows = list.map((s) => ({
     id: s.id,
     agent: s.agent,
     title: s.title || null,
     phase: s.state?.phase || (s.state?.alive ? "idle" : "off"),
+    parent: s.parent_id || null,
+    waitingOn: s.messages?.waitingOn ?? [],
+    queued: s.messages?.queued ?? 0,
     self: s.id === me,
   }));
+  const ids = new Set(rows.map((s) => s.id));
+  const out = [];
+  const walk = (s, depth) => {
+    if (out.some((o) => o.id === s.id)) return;
+    out.push({ ...s, depth });
+    for (const c of rows) if (c.parent === s.id) walk(c, depth + 1);
+  };
+  for (const s of rows) if (!s.parent || !ids.has(s.parent)) walk(s, 0);
+  for (const s of rows) walk(s, 0);
+  return out;
 }
 
 function sessionLine(ctx, s) {
-  return `${ctx.pad(s.id, 9)} ${ctx.pad(s.agent, 10)} ${ctx.pad(s.phase, 8)} ${s.title || ""}${s.self ? "  (this session)" : ""}`;
+  const notes = [
+    s.waitingOn.length && `waiting on ${s.waitingOn.join(", ")}`,
+    s.queued && `${s.queued} queued for it`,
+    s.self && "this session",
+  ].filter(Boolean);
+  return `${"  ".repeat(s.depth ?? 0)}${ctx.pad(s.id, 9)} ${ctx.pad(s.agent, 10)} ${ctx.pad(s.phase, 8)} ${s.title || ""}${notes.length ? `  (${notes.join("; ")})` : ""}`;
+}
+
+/** A flag's value, "-" (stdin) included, which ctx.flag takes for a
+ * flag of its own. */
+function valueOf(ctx, flag) {
+  const i = ctx.args.indexOf(flag);
+  if (i >= 0 && ctx.args[i + 1] === "-") return "-";
+  return ctx.flag(flag);
+}
+
+/** The text itself, or stdin's for "-": a heredoc carries a long prompt
+ * with quotes in it, which an argument mangles. */
+async function textOf(value) {
+  if (value !== "-") return value;
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8").replace(/\n$/, "");
+}
+
+/** What became of a message, for the sender. */
+function sentText(id, r) {
+  const lines = [
+    r.delivered
+      ? `sent to ${id}`
+      : `queued for ${id} (${r.queued}): typed in once it is at its prompt`,
+  ];
+  if (r.wantsReply)
+    lines.push(
+      `Its last message, as that turn ends, comes back to you as a prompt: end your turn to wait for it, or run \`work session wait ${id}\`.`,
+    );
+  return lines.join("\n");
+}
+
+function printReply(r) {
+  const head =
+    r.kind === "reply" ? `${r.label} replied:` : `${r.label}: ${r.text}`;
+  console.log(head);
+  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>/…).
@@ -44,14 +168,60 @@ 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>"] [--workspace <id|name>] [--force]
-  Start a session (the default agent unless --agent; "shell" for a
-  terminal), name it, and hand it a first prompt. Past ${SESSION_CAP} sessions
-  in the workspace it wants --force.
-work session send <id> "<text>"
-  Type text into a session and press Enter, as the review's Send does.
-work session kill <id> --yes
-  Close a session and the process in it.`,
+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 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,
+  or a draft someone is typing. From an agent's session it wants a 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>|<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",
@@ -59,6 +229,12 @@ work session kill <id> --yes
         "--prompt",
         "--workspace",
         "--session",
+        "--timeout",
+        "--topic",
+        "--repo",
+        "--count",
+        "--parallel",
+        "--phase",
       ]);
       switch (verb) {
         case undefined: {
@@ -68,6 +244,7 @@ work session kill <id> --yes
           if (!me) ctx.die(`no session ${id} in ${ws.name}`);
           const out = {
             ...me,
+            depth: undefined,
             workspace: {
               id: ws.id,
               name: ws.name,
@@ -77,7 +254,7 @@ work session kill <id> --yes
           };
           return ctx.out(out, (s) => {
             console.log(
-              `${s.id}  ${s.agent}  ${s.phase}${s.title ? `  "${s.title}"` : ""}`,
+              `${s.id}  ${s.agent}  ${s.phase}${s.title ? `  "${s.title}"` : ""}${s.waitingOn.length ? `  (waiting on ${s.waitingOn.join(", ")})` : ""}`,
             );
             console.log(
               `workspace ${s.workspace.name} (${s.workspace.id})  ${s.workspace.path}`,
@@ -104,59 +281,247 @@ 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 } : {},
+            {
+              ...(agent ? { agent } : {}),
+              ...(me ? { parent: me } : {}),
+              ...(at ? { dir: at.dirs[0] } : {}),
+              ...(ctx.has("--keep") ? { keep: true } : {}),
+            },
           );
           const title = ctx.flag("--title");
           if (title)
             await ctx.api.patch(`/api/sessions/${created.id}`, { title });
-          const prompt = ctx.flag("--prompt");
           // Sent, the session starts (detached) with it as its first
           // prompt; otherwise it starts when someone opens it.
-          if (prompt)
-            await ctx.api.post(`/api/sessions/${created.id}/send`, {
-              text: prompt,
-            });
+          const sent = prompt
+            ? await ctx.api.post(`/api/sessions/${created.id}/messages`, {
+                text: prompt,
+                ...(me ? { from: me } : {}),
+                reply: !ctx.has("--no-reply"),
+              })
+            : null;
           const out = {
             id: created.id,
             agent: created.agent,
             title: title || null,
             workspace: ws.id,
-            prompted: !!prompt,
+            parent: created.parent_id ?? null,
+            topic: topic ?? null,
+            prompted: !!sent?.delivered,
+            queued: sent?.queued ?? null,
+            wantsReply: !!sent?.wantsReply,
             href: `/w/${ws.id}?s=${created.id}`,
           };
-          return ctx.out(out, (s) =>
+          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}`);
+            if (s.wantsReply)
+              console.log(
+                `Its last message, as that turn ends, comes back to you as a prompt: end your turn to wait for it, or run \`work session wait ${s.id}\`.`,
+              );
+          });
+        }
+        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 = words.join(" ");
-          if (!id || !text) ctx.die('usage: work session send <id> "<text>"');
-          await ctx.api.post(`/api/sessions/${id}/send`, { text });
-          return ctx.out({ id, sent: true }, () =>
-            console.log(`sent to ${id}`),
-          );
+          const text = await textOf(words.join(" "));
+          if (!id || !text)
+            ctx.die('usage: work session send <id> "<text>"|- [--no-reply]');
+          const me = process.env.WORK_SESSION_ID;
+          const r = await ctx.api.post(`/api/sessions/${id}/messages`, {
+            text,
+            ...(me ? { from: me } : {}),
+            reply: !ctx.has("--no-reply"),
+          });
+          return ctx.out({ id, ...r }, (r) => console.log(sentText(id, r)));
+        }
+        case "wait": {
+          const me = sessionId(ctx);
+          const raw = ctx.flag("--timeout");
+          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 } : {}), any };
+          const replies = [];
+          let owing = [];
+          for (;;) {
+            const r = await ctx.api.post(`/api/sessions/${me}/replies`, body);
+            replies.push(...r.replies);
+            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)
+            console.log(JSON.stringify({ replies, owing }, null, 2));
+          else if (!replies.length && !owing.length)
+            console.log(
+              rest.length
+                ? `nothing owed by ${rest.join(", ")}: a reply already typed in is in your prompt`
+                : "no session owes this one a reply",
+            );
+          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(
+              "usage: work session kill <id> [--keep-children] --yes, or --done",
+            );
+          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${id === process.env.WORK_SESSION_ID ? " — this session, the one running this command" : ""}: pass --yes`,
+              `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`,
             );
-          await ctx.api.del(`/api/sessions/${id}`);
-          return ctx.out({ id, killed: true }, () =>
-            console.log(`closed ${id}`),
+          }
+          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: