borgmcp 3.9.0 → 3.11.0

package/src/parse-quickstart-args.ts

@@ -0,0 +1,54 @@
+import { NEW_CUBE_TEMPLATE_PRESENTATIONS } from 'borgmcp-shared/templates';
+
+export interface QuickstartRoleRequest {
+  slug: string;
+  count: number;
+}
+
+export interface QuickstartArgs {
+  template?: string;
+  roles: QuickstartRoleRequest[];
+  yes: boolean;
+}
+
+export type ParseQuickstartResult =
+  | { ok: true; args: QuickstartArgs }
+  | { ok: false; error: string };
+
+const templates = new Set<string>(NEW_CUBE_TEMPLATE_PRESENTATIONS.map(({ name }) => name));
+
+function parseRole(value: string): QuickstartRoleRequest | null {
+  const match = /^([a-z0-9]+(?:-[a-z0-9]+)*)(?::([1-9]\d*))?$/.exec(value);
+  if (!match) return null;
+  const count = match[2] === undefined ? 1 : Number(match[2]);
+  return Number.isSafeInteger(count) ? { slug: match[1], count } : null;
+}
+
+export function parseQuickstartArgs(rawArgs: readonly string[]): ParseQuickstartResult {
+  const args: QuickstartArgs = { roles: [], yes: false };
+  for (let i = 0; i < rawArgs.length; i += 1) {
+    const arg = rawArgs[i];
+    if (arg === '--yes' || arg === '-y') {
+      args.yes = true;
+      continue;
+    }
+    if (arg === '--template') {
+      const value = rawArgs[++i];
+      if (!value) return { ok: false, error: '--template requires software-dev, starter, or local-model' };
+      if (!templates.has(value)) return { ok: false, error: `unknown template '${value}'; choose software-dev, starter, or local-model` };
+      if (args.template !== undefined) return { ok: false, error: '--template was provided more than once' };
+      args.template = value;
+      continue;
+    }
+    if (arg === '--role') {
+      const value = rawArgs[++i];
+      if (!value) return { ok: false, error: '--role requires <slug>[:<count>]' };
+      const role = parseRole(value);
+      if (!role) return { ok: false, error: `invalid role '${value}'; use <slug>[:<positive-count>]` };
+      args.roles.push(role);
+      continue;
+    }
+    return { ok: false, error: `unknown option: ${arg}. Supported: --template, --role, --yes/-y` };
+  }
+  return { ok: true, args };
+}

package/src/quickstart-cmd.ts

@@ -0,0 +1,396 @@
+import {
+  NEW_CUBE_TEMPLATE_PRESENTATIONS,
+  getTemplate,
+  type TemplateRole,
+} from 'borgmcp-shared/templates';
+import type { AssimilateDeps, PreparedAssimilation } from './assimilate-cmd.js';
+import { runAssimilate } from './assimilate-cmd.js';
+import { buildDefaultAssimilateDeps } from './assimilate-deps.js';
+import type { ActiveCube } from './cubes.js';
+import { readAllProjectIdentities } from './cubes.js';
+import { buildDefaultLaunchAllDeps, type LaunchAllDeps } from './launch-all-deps.js';
+import { LAUNCH_ALL_NO_DISPATCH_EXIT_CODE, runLaunchAll } from './launch-all-cmd.js';
+import type { QuickstartArgs } from './parse-quickstart-args.js';
+import { roleSlug, type Role } from './role-resolver.js';
+import { DEFAULT_LOCAL_SERVER_ORIGIN } from './server-handshake.js';
+
+interface PlannedRole {
+  name: string;
+  slug: string;
+  isHumanSeat: boolean;
+}
+
+interface ExistingPlan {
+  cubeId: string;
+  cubeName: string;
+  template: string;
+  roles: PlannedRole[];
+}
+
+export interface QuickstartDeps {
+  buildAssimilateDeps: () => AssimilateDeps;
+  buildLaunchAllDeps: () => LaunchAllDeps;
+  readAllProjectIdentities: () => Promise<Array<{ projectPath: string; cube: ActiveCube }>>;
+  isTTY: () => boolean;
+  prompt: (message: string) => Promise<string>;
+  stdout: (text: string) => void;
+  stderr: (text: string) => void;
+  runAssimilate?: typeof runAssimilate;
+  runLaunchAll?: typeof runLaunchAll;
+}
+
+export function buildDefaultQuickstartDeps(): QuickstartDeps {
+  const io = buildDefaultAssimilateDeps();
+  return {
+    buildAssimilateDeps: buildDefaultAssimilateDeps,
+    buildLaunchAllDeps: buildDefaultLaunchAllDeps,
+    readAllProjectIdentities,
+    isTTY: io.isTTY,
+    prompt: io.prompt,
+    stdout: io.stdout,
+    stderr: io.stderr,
+  };
+}
+
+function plannedTemplateRoles(templateName: string): PlannedRole[] {
+  const template = getTemplate(templateName);
+  if (!template) return [];
+  return template.roles.map((role: TemplateRole) => ({
+    name: role.name,
+    slug: roleSlug(role.name),
+    isHumanSeat: role.is_human_seat === true,
+  }));
+}
+
+function plannedServerRoles(roles: readonly Role[]): PlannedRole[] {
+  return roles.map((role) => ({
+    name: role.name,
+    slug: roleSlug(role.name),
+    isHumanSeat: role.is_human_seat,
+  }));
+}
+
+function templatePresentation(name: string): { label: string; short_description: string } {
+  const found = NEW_CUBE_TEMPLATE_PRESENTATIONS.find((candidate) => candidate.name === name);
+  return found ?? { label: name, short_description: '' };
+}
+
+function renderTemplateMenu(): string {
+  const rows = NEW_CUBE_TEMPLATE_PRESENTATIONS.flatMap((presentation, index) => {
+    const words = presentation.short_description.split(/\s+/);
+    const lines: string[] = [];
+    for (const word of words) {
+      const last = lines.at(-1);
+      if (!last || `${last} ${word}`.length > 42) lines.push(word);
+      else lines[lines.length - 1] = `${last} ${word}`;
+    }
+    return lines.map((line, lineIndex) => lineIndex === 0
+      ? `            ${index + 1}) ${presentation.label.padEnd(22)}${line}`
+      : `                                     ${line}`);
+  });
+  rows[0] = `Template    ${rows[0].trimStart()}`;
+  return `${rows.join('\n')}\n`;
+}
+
+async function selectTemplate(args: QuickstartArgs, deps: QuickstartDeps): Promise<string | null> {
+  if (args.template) return args.template;
+  if (!deps.isTTY()) return NEW_CUBE_TEMPLATE_PRESENTATIONS[0].name;
+  deps.stdout(renderTemplateMenu());
+  while (true) {
+    let answer: string;
+    try {
+      answer = (await deps.prompt('Choose [1]: ')).trim();
+    } catch {
+      deps.stderr('\nborg quickstart: cancelled before anything was created.\n');
+      return null;
+    }
+    const index = answer === '' ? 0 : /^\d+$/.test(answer) ? Number(answer) - 1 : -1;
+    const selected = NEW_CUBE_TEMPLATE_PRESENTATIONS[index];
+    if (selected) return selected.name;
+    deps.stdout(`Choose 1-${NEW_CUBE_TEMPLATE_PRESENTATIONS.length}.\n`);
+  }
+}
+
+function aggregateRequestedRoles(args: QuickstartArgs, available: readonly PlannedRole[]): PlannedRole[] | string {
+  if (args.roles.length === 0) return [...available];
+  const bySlug = new Map(available.map((role) => [role.slug, role]));
+  const requested: PlannedRole[] = [];
+  for (const request of args.roles) {
+    const role = bySlug.get(request.slug);
+    if (!role) return `no role '${request.slug}' exists in this cube; available: ${available.map((item) => item.slug).join(', ')}`;
+    for (let i = 0; i < request.count; i += 1) requested.push(role);
+  }
+  return requested;
+}
+
+function renderRoleList(label: string, roles: readonly PlannedRole[]): string {
+  const prefix = label.padEnd(12);
+  const continuation = ' '.repeat(12);
+  const lines: string[] = [];
+  for (let index = 0; index < roles.length; index += 1) {
+    const token = `${roles[index].slug}${index === roles.length - 1 ? '' : ','}`;
+    const candidate = lines.length === 0 ? token : `${lines.at(-1)} ${token}`;
+    if (lines.length === 0 || candidate.length <= 64) {
+      if (lines.length === 0) lines.push(token);
+      else lines[lines.length - 1] = candidate;
+    } else {
+      lines.push(token);
+    }
+  }
+  return lines.map((line, index) => `${index === 0 ? prefix : continuation}${line}`).join('\n');
+}
+
+function affirmative(value: string): boolean {
+  const answer = value.trim().toLowerCase();
+  return answer === '' || answer === 'y' || answer === 'yes';
+}
+
+export async function runQuickstart(args: QuickstartArgs, deps: QuickstartDeps): Promise<number> {
+  const assimilate = deps.buildAssimilateDeps();
+  let context;
+  try {
+    context = await assimilate.resolveRepositoryContext(assimilate.cwd());
+  } catch {
+    context = null;
+  }
+  if (!context) {
+    deps.stderr('borg quickstart: run this command inside a non-bare Git repository.\n');
+    return 1;
+  }
+
+  let serverOrigin: string | null = null;
+  try {
+    serverOrigin = await assimilate.detectLocalServer();
+  } catch {
+    serverOrigin = null;
+  }
+  if (!serverOrigin) {
+    deps.stderr(
+      `borg quickstart: no Borg server is running at ${DEFAULT_LOCAL_SERVER_ORIGIN}.\n` +
+      'Start it in another terminal and leave it open:\n' +
+      '  borg server start\n' +
+      'Then run `borg quickstart` again.\n',
+    );
+    return 1;
+  }
+
+  let connection;
+  try {
+    connection = await assimilate.connectServer(serverOrigin);
+  } catch (error) {
+    deps.stderr(`borg quickstart: could not use the Borg server at ${serverOrigin}: ${error instanceof Error ? error.message : String(error)}\n`);
+    return 1;
+  }
+
+  let existing: ExistingPlan | null = null;
+  try {
+    const repository = await assimilate.getRepositoryIdentity(context);
+    const saved = await assimilate.getRepositoryAssociation(connection.trustIdentity, repository);
+    if (saved) {
+      const cube = await assimilate.getCube(serverOrigin, connection.token, saved.cubeId, connection.trustIdentity);
+      existing = { cubeId: cube.id, cubeName: cube.name, template: saved.template, roles: plannedServerRoles(cube.roles) };
+    } else {
+      const resolved = await assimilate.resolveRepositoryCube(
+        serverOrigin,
+        connection.token,
+        { repository, workingRepoName: context.derivedName },
+        connection.trustIdentity,
+      );
+      if (resolved.result === 'resolved') {
+        const cube = await assimilate.getCube(serverOrigin, connection.token, resolved.cube_id, connection.trustIdentity);
+        existing = { cubeId: cube.id, cubeName: cube.name, template: resolved.template, roles: plannedServerRoles(cube.roles) };
+      }
+    }
+  } catch (error) {
+    deps.stderr(`borg quickstart: could not inspect this repository's cube: ${error instanceof Error ? error.message : String(error)}\n`);
+    return 1;
+  }
+
+  deps.stdout(`Repository  ${context.derivedName}${context.publicRepository ? ` (origin: ${context.publicRepository.value})` : ''}\n`);
+  const template = existing?.template ?? await selectTemplate(args, deps);
+  if (!template) return 130;
+  const availableRoles = existing?.roles ?? plannedTemplateRoles(template);
+  const humanSeatRole = availableRoles.find((role) => role.isHumanSeat);
+  const requested = aggregateRequestedRoles(args, availableRoles);
+  if (typeof requested === 'string') {
+    deps.stderr(`borg quickstart: ${requested}.\n`);
+    return 1;
+  }
+
+  // Resolve any multi-CLI choice before the whole-plan confirmation. Every
+  // assimilate call then receives the explicit choice and cannot prompt after
+  // the operator has approved the plan.
+  let selectedCli;
+  try {
+    selectedCli = await assimilate.resolveCli(undefined);
+  } catch (error) {
+    deps.stderr(`borg quickstart: ${error instanceof Error ? error.message : String(error)}\n`);
+    return 1;
+  }
+
+  let identities: Array<{ projectPath: string; cube: ActiveCube }> = [];
+  try {
+    identities = existing ? await deps.readAllProjectIdentities() : [];
+  } catch (error) {
+    deps.stderr(`borg quickstart: could not read the local drone registry: ${error instanceof Error ? error.message : String(error)}\n`);
+    return 1;
+  }
+  const existingByRole = new Map<string, Array<{ projectPath: string; cube: ActiveCube }>>();
+  for (const identity of identities) {
+    if (identity.cube.cubeId !== existing?.cubeId || !identity.cube.roleName) continue;
+    const slug = roleSlug(identity.cube.roleName);
+    const list = existingByRole.get(slug) ?? [];
+    list.push(identity);
+    existingByRole.set(slug, list);
+  }
+
+  const usedByRole = new Map<string, number>();
+  const targets: Array<{ role: PlannedRole; existing?: { projectPath: string; cube: ActiveCube } }> = [];
+  for (const role of requested) {
+    const used = usedByRole.get(role.slug) ?? 0;
+    const match = existingByRole.get(role.slug)?.[used];
+    targets.push({ role, ...(match ? { existing: match } : {}) });
+    usedByRole.set(role.slug, used + 1);
+  }
+  const have = targets.filter((target) => target.existing).map((target) => target.role);
+  const missing = targets.filter((target) => !target.existing).map((target) => target.role);
+
+  if (existing) {
+    deps.stdout(`Cube        ${existing.cubeName} (existing)\n`);
+    if (have.length > 0) deps.stdout(`${renderRoleList('Have', have)}\n`);
+    deps.stdout(missing.length > 0
+      ? `${renderRoleList('Will create', missing)}\n`
+      : 'Will create nothing; every requested drone already exists\n');
+  } else {
+    deps.stdout(`Cube        ${context.derivedName} (new, template: ${templatePresentation(template).label})\n`);
+    deps.stdout(`${renderRoleList('Drones', requested)}\n`);
+  }
+
+  if (!args.yes) {
+    if (!deps.isTTY()) {
+      deps.stderr('borg quickstart: confirmation requires an interactive terminal; rerun with --yes.\n');
+      return 1;
+    }
+    const prompt = existing
+      ? 'Continue? [Y/n] '
+      : `Create and launch these ${requested.length} ${requested.length === 1 ? 'drone' : 'drones'}? [Y/n] `;
+    let answer: string;
+    try {
+      answer = await deps.prompt(prompt);
+    } catch {
+      deps.stderr('\nborg quickstart: cancelled before anything was created.\n');
+      return 130;
+    }
+    if (!affirmative(answer)) {
+      deps.stdout('Cancelled. Nothing was created.\n');
+      return 0;
+    }
+  }
+
+  const runAssimilateImpl = deps.runAssimilate ?? runAssimilate;
+  for (const target of targets) {
+    if (target.existing) continue;
+    let prepared: PreparedAssimilation | undefined;
+    let diagnostic = '';
+    const inner = deps.buildAssimilateDeps();
+    let code = 1;
+    try {
+      code = await runAssimilateImpl({
+        role: target.role.slug,
+        flags: {
+          server: serverOrigin,
+          yes: true,
+          cubeName: context.derivedName,
+          template,
+          cli: selectedCli,
+        },
+      }, {
+        ...inner,
+        stdout: (text) => { diagnostic += text; },
+        stderr: (text) => { diagnostic += text; },
+      }, {
+        launch: false,
+        onPrepared: (value) => { prepared = value; },
+      });
+    } catch (error) {
+      diagnostic += `${error instanceof Error ? error.message : String(error)}\n`;
+    }
+    const assignedRoleSlug = prepared ? roleSlug(prepared.roleName) : null;
+    const roleMismatch = assignedRoleSlug !== null && assignedRoleSlug !== target.role.slug;
+    if (code !== 0 || !prepared || roleMismatch) {
+      deps.stderr(`✗ ${target.role.slug}\n`);
+      if (diagnostic) deps.stderr(diagnostic);
+      if (roleMismatch) {
+        deps.stderr(
+          `borg quickstart: requested ${target.role.slug}, but the server assigned ${assignedRoleSlug}. ` +
+          `The assigned drone was kept; it does not fill the requested ${target.role.slug} slot.\n`,
+        );
+      }
+      const completed = targets.filter((item) => item.existing).length;
+      const remaining = targets.filter((item) => !item.existing).map((item) => item.role);
+      deps.stderr(
+        `Stopped. ${completed} of ${requested.length} drones exist; ${remaining.map((role) => role.slug).join(', ')} ${remaining.length === 1 ? 'is' : 'are'} missing.\n` +
+        `Fix the cause above, then run \`borg quickstart\` again — it continues from here and does not touch the drones that already exist.\n`,
+      );
+      return 1;
+    }
+    target.existing = {
+      projectPath: prepared.worktree,
+      cube: {
+        cubeId: prepared.cubeId,
+        droneId: prepared.droneId,
+        name: prepared.cubeName,
+        droneLabel: prepared.droneLabel,
+        apiUrl: serverOrigin,
+        sessionToken: '',
+        roleName: prepared.roleName,
+      },
+    };
+    deps.stdout(`✓ ${target.role.slug.padEnd(20)}${prepared.worktree}\n`);
+  }
+
+  const droneIds = targets.flatMap((target) => target.existing ? [target.existing.cube.droneId] : []);
+  const firstTarget = targets.find((target) => target.existing)?.existing?.cube;
+  const cubeName = firstTarget?.name ?? existing?.cubeName ?? context.derivedName;
+  const cubeId = firstTarget?.cubeId ?? existing?.cubeId;
+  if (!cubeId) {
+    deps.stderr('borg quickstart: the staffed cube identity could not be confirmed; run `borg quickstart` again.\n');
+    return 1;
+  }
+  deps.stdout(`Launching ${droneIds.length} sessions.\n`);
+  let launchOutput = '';
+  const launchDeps = deps.buildLaunchAllDeps();
+  let launchCode = 1;
+  try {
+    launchCode = await (deps.runLaunchAll ?? runLaunchAll)(
+      { cubeName, flags: { yes: true } },
+      {
+        ...launchDeps,
+        stdout: (text) => { launchOutput += text; },
+        stderr: (text) => { launchOutput += text; },
+      },
+      { droneIds, requireAllRequested: true, targetCube: { cubeId, name: cubeName } },
+    );
+  } catch (error) {
+    launchOutput += `${error instanceof Error ? error.message : String(error)}\n`;
+  }
+  if (launchCode !== 0) {
+    if (launchOutput) deps.stderr(launchOutput);
+    deps.stderr(launchCode === LAUNCH_ALL_NO_DISPATCH_EXIT_CODE
+      ? 'No sessions were launched: this environment has no terminal or tmux backend. Run `borg launch-all` to print the commands, then paste them.\n'
+      : 'The drones were created, but one or more sessions did not launch. Fix the cause above, then run `borg launch-all`.\n');
+    return 1;
+  }
+
+  deps.stdout(`✓ Cube \`${cubeName}\` is staffed. ${droneIds.length} ${droneIds.length === 1 ? 'drone' : 'drones'} launched.\n`);
+  const human = targets.find((target) => target.role.isHumanSeat && target.existing);
+  if (human?.existing) {
+    deps.stdout(
+      `Start in the ${human.role.slug} session (\`${human.existing.cube.droneLabel}\`) and tell it what\n` +
+      'you want built. It dispatches the rest.\n',
+    );
+  } else if (humanSeatRole) {
+    deps.stdout(`Start a ${humanSeatRole.name} session later with: borg assimilate ${humanSeatRole.slug}\n`);
+  }
+  return 0;
+}

package/src/remote-client.ts

@@ -564,6 +564,7 @@ async function localReadLogPage(
 
 interface PendingWakePage {
   entries: Array<{
+    id?: unknown;
     drone_id?: unknown;
     message?: unknown;
     visibility?: unknown;
@@ -622,6 +623,41 @@ export async function hasPendingWakeActivity(
   }
 }
 
+/**
+ * Inspect the durable unread window for one specific SSE entry without
+ * advancing the agent-owned cursor. Wake nonces are retries of that entry, so
+ * the entry itself remains the authority for whether another wake is owed.
+ */
+export async function hasPendingWakeEntry(
+  active: ActiveCube,
+  entryId: string,
+  deps: {
+    getCursor?: typeof getLocalServerCursor;
+    readPage?: (active: ActiveCube, opts: { cursor: LocalServerCursor | null; limit: number }) => Promise<PendingWakePage>;
+  } = {},
+): Promise<boolean> {
+  if (!active.serverTrustIdentity) {
+    throw new Error('Selected Borg server authority state is missing or unreadable');
+  }
+
+  const getCursor = deps.getCursor ?? getLocalServerCursor;
+  const readPage = deps.readPage ?? localReadLogPage;
+  let cursor = await getCursor(localCursorBinding(active));
+
+  for (;;) {
+    const page: PendingWakePage = await readPage(active, { cursor, limit: 500 });
+    if (page.entries.some((entry) =>
+      entry.id === entryId && isPendingWakeEntry(entry, active.droneId)
+    )) return true;
+    if (!page.has_more) return false;
+    if (!page.cursor ||
+      (cursor && page.cursor.id === cursor.id && page.cursor.created_at === cursor.created_at)) {
+      throw new Error('Local Borg server returned a non-advancing log cursor');
+    }
+    cursor = page.cursor;
+  }
+}
+
 async function resolveLocalLogCursor(
   active: ActiveCube,
   since: string,

package/src/seat-commands.ts

@@ -143,7 +143,7 @@ function oneLine(value: string): string {
 
 export function formatLocalSeatRows(rows: readonly LocalSeatRow[]): string {
   if (rows.length === 0) {
-    return 'No drone seats are registered on this machine. Run `borg assimilate` in a project repository to create one.\n';
+    return 'No drones are registered on this machine. Run `borg assimilate` in a project repository to create one.\n';
   }
   const headings = ['DRONE', 'CUBE', 'STATE', 'CLI', 'WORKTREE'];
   const values = rows.map((row) => [
@@ -176,7 +176,7 @@ export async function runSeats(deps: SeatCommandDeps): Promise<number> {
     deps.stdout(formatLocalSeatRows(await readLocalSeatRows(deps)));
     return 0;
   } catch (error) {
-    deps.stderr(`borg seats: could not read the local registry: ${error instanceof Error ? error.message : String(error)}\n`);
+    deps.stderr(`borg drones: could not read the local registry: ${error instanceof Error ? error.message : String(error)}\n`);
     return 1;
   }
 }
@@ -198,7 +198,7 @@ export async function runLaunchSeat(
     if (cubeIds.size === 0) {
       deps.stderr(
         `borg launch: no cube named '${args.cube}' is registered on this machine. ` +
-        `Run \`borg seats\` to list this machine's cubes and drones.\n`,
+        `Run \`borg drones\` to list this machine's cubes and drones.\n`,
       );
       return 1;
     }
@@ -212,19 +212,19 @@ export async function runLaunchSeat(
   if (matches.length === 0) {
     if (rows.length === 0) {
       deps.stderr(
-        `borg launch: drone '${args.target}' is not in this machine's seat registry. ` +
+        `borg launch: drone '${args.target}' is not in this machine's registry. ` +
         `The registry is local to each machine and lists only drones assimilated here. ` +
-        `Run \`borg seats\` on the machine where the drone was created.\n`,
+        `Run \`borg drones\` on the machine where the drone was created.\n`,
       );
     } else if (args.cube) {
       deps.stderr(
         `borg launch: no drone matches '${args.target}' in cube '${args.cube}'. ` +
-        `Run \`borg seats\` to list the drones you can launch.\n`,
+        `Run \`borg drones\` to list the drones you can launch.\n`,
       );
     } else {
       deps.stderr(
         `borg launch: no drone matches '${args.target}' on this machine. ` +
-        `Run \`borg seats\` to list the drones you can launch.\n`,
+        `Run \`borg drones\` to list the drones you can launch.\n`,
       );
     }
     return 1;
@@ -248,9 +248,9 @@ export async function runLaunchSeat(
   }
   if (selected.state !== 'active') {
     deps.stderr(
-      `borg launch: drone '${selected.droneLabel}' has a pending seat (shown as \`pending\` in \`borg seats\`) — ` +
+      `borg launch: drone '${selected.droneLabel}' is not fully assimilated (shown as \`pending\` in \`borg drones\`) — ` +
       `its assimilation did not complete, so launching now would start an unattached session. ` +
-      `To complete the seat, run \`borg assimilate\` in ${selected.worktree}, then run ` +
+      `To finish it, run \`borg assimilate\` in ${selected.worktree}, then run ` +
       `\`borg launch ${selected.droneLabel}\` again.\n`,
     );
     return 1;
@@ -264,8 +264,8 @@ export async function runLaunchSeat(
   }
   if (!preferred) {
     deps.stderr(
-      `borg launch: did not launch '${selected.droneLabel}' — its seat registration changed before the launch could start. ` +
-      `Run \`borg seats\` to see the current state, then try again.\n`,
+      `borg launch: did not launch '${selected.droneLabel}' — its registration changed before the launch could start. ` +
+      `Run \`borg drones\` to see the current state, then try again.\n`,
     );
     return 1;
   }
@@ -277,7 +277,7 @@ export async function runLaunchSeat(
     deps.stderr(
       `borg launch: did not launch '${selected.droneLabel}' — the worktree at ${selected.worktree} would resume ` +
       `'${preferred.droneLabel}' (cube '${preferred.name}') instead. To resume '${preferred.droneLabel}', run \`borg\` ` +
-      `in that worktree. To review this machine's seats, run \`borg seats\`.\n`,
+      `in that worktree. To review this machine's drones, run \`borg drones\`.\n`,
     );
     return 1;
   }

package/src/stream-status.ts

@@ -272,6 +272,9 @@ export function renderStreamStatus(inputs: RenderInputs): string {
     );
     lines.push(`- **OpenCode retried**: ${delivery.retried}`);
     lines.push(`- **OpenCode failed**: ${delivery.failed}`);
+    lines.push(
+      '- **OpenCode delivery-state meaning**: delivered-unconfirmed counts entries that may have been submitted but are not visible in session history; failed counts entries that could not be submitted or were rejected, until the durable source entry is observed consumed.'
+    );
   }
 
   // Runtime-specific wake-path warning. The wire-down case takes

package/src/unknown-subcommand.ts

@@ -16,12 +16,14 @@ export const KNOWN_SUBCOMMANDS = [
   'setup',
   'update',
   'doctor',
+  'clone',
+  'quickstart',
   'assimilate',
   'reset-local-connection',
   'recover-enrollment',
   'spawn',
   'cleanup',
-  'seats',
+  'drones',
   'launch',
   'launch-all',
   'server',