@a-t-h-i/bot-lobby 0.4.0 → 0.5.0

package/src/lobby/quickfix.ts

@@ -0,0 +1,227 @@
+/**
+ * Quick fixes: a direct prompt from the lobby goes straight to one coding
+ * subagent — no scouting, proposal, plan or QA gate — while any bot-lobby task
+ * keeps running. Jobs run one at a time in submission order so two quick fixes
+ * never edit the tree at once; each streams plain-words steps into its own log
+ * and the lobby feed, and every finished job lands in the metrics log.
+ */
+import { loadPrompt } from "../prompts/loader.ts";
+import { runPiAgent, spawnPiProcess, type PiStreamEvent, type ProcessRunner } from "../execution/pi-runner.ts";
+import { describeToolCall } from "../pi/activity.ts";
+import { appendMetrics, type MetricRecord } from "../state/metrics.ts";
+import type { LobbyFeed } from "./feed.ts";
+
+/** A quick fix edits code, so it gets the full coding tool set. */
+export const QUICK_FIX_TOOLS: readonly string[] = ["read", "bash", "edit", "write", "grep", "find", "ls"];
+
+export const QUICK_FIX_SOURCE = "QUICK FIX";
+
+export type QuickFixStatus = "queued" | "running" | "success" | "failed" | "cancelled" | "timeout";
+
+export interface QuickFixStep {
+  at: number;
+  text: string;
+  pending: boolean;
+}
+
+export interface QuickFixJob {
+  id: string;
+  prompt: string;
+  status: QuickFixStatus;
+  createdAt: number;
+  startedAt?: number;
+  finishedAt?: number;
+  model?: string;
+  thinking?: string;
+  steps: QuickFixStep[];
+  tools: number;
+  turns: number;
+  report?: string;
+  error?: string;
+  usage?: { input: number; output: number; cost: number; turns: number };
+}
+
+export interface QuickFixProfile {
+  model?: string;
+  thinking: string;
+  timeoutMs: number;
+  instructions?: string;
+}
+
+export interface QuickFixDeps {
+  cwd: string;
+  root: string;
+  configDir: string;
+  /** Model, thinking and time limit for the next job, read from settings at start time. */
+  profile: () => QuickFixProfile;
+  stallTimeoutMs?: number;
+  toolStallTimeoutMs?: number;
+  feed?: LobbyFeed;
+  runProcess?: ProcessRunner;
+  /** Called after every change so the lobby can repaint. */
+  onChange?: () => void;
+  notify?: (message: string, level: "info" | "warning" | "error") => void;
+}
+
+export const MAX_JOBS = 30;
+export const MAX_STEPS = 200;
+
+function isActive(job: QuickFixJob): boolean {
+  return job.status === "queued" || job.status === "running";
+}
+
+/** The system prompt a quick fix runs with: the quick-fix role plus the user's custom instructions. */
+export function quickFixPrompt(instructions?: string): string {
+  const custom = instructions?.trim();
+  return custom ? `${loadPrompt("quickfix.md")}\n\n## Custom Instructions\n\n${custom}` : loadPrompt("quickfix.md");
+}
+
+/** First line of a prompt, for lists. */
+export function jobTitle(job: Pick<QuickFixJob, "prompt">): string {
+  return job.prompt.split("\n").find((line) => line.trim())?.trim() ?? "(empty)";
+}
+
+export class QuickFixQueue {
+  jobs: QuickFixJob[] = [];
+  private readonly deps: QuickFixDeps;
+  private readonly controllers = new Map<string, AbortController>();
+  private counter = 0;
+
+  constructor(deps: QuickFixDeps) {
+    this.deps = deps;
+  }
+
+  get running(): QuickFixJob | undefined {
+    return this.jobs.find((job) => job.status === "running");
+  }
+
+  /** Queue a quick fix; it starts at once when nothing else is running. */
+  submit(prompt: string, now = Date.now()): QuickFixJob {
+    const text = prompt.trim();
+    if (!text) throw new Error("a quick fix needs a prompt");
+    const job: QuickFixJob = { id: `QF-${++this.counter}`, prompt: text, status: "queued", createdAt: now, steps: [], tools: 0, turns: 0 };
+    this.jobs = [...this.jobs, job].filter((entry, index, all) => isActive(entry) || index >= all.length - MAX_JOBS);
+    this.changed();
+    this.pump();
+    return job;
+  }
+
+  /** Cancel a queued or running job; finished jobs are left alone. */
+  cancel(id: string): boolean {
+    const job = this.jobs.find((entry) => entry.id === id);
+    if (!job || !isActive(job)) return false;
+    if (job.status === "queued") {
+      job.status = "cancelled";
+      job.finishedAt = Date.now();
+      this.changed();
+      return true;
+    }
+    this.controllers.get(id)?.abort();
+    return true;
+  }
+
+  /** Abort everything (session shutdown). */
+  cancelAll(): void {
+    for (const job of this.jobs) if (job.status === "queued") job.status = "cancelled";
+    for (const controller of this.controllers.values()) controller.abort();
+  }
+
+  private changed(): void {
+    this.deps.onChange?.();
+  }
+
+  private pump(): void {
+    if (this.running) return;
+    const next = this.jobs.find((job) => job.status === "queued");
+    if (next) void this.run(next);
+  }
+
+  private addStep(job: QuickFixJob, text: string, at: number): void {
+    for (const step of job.steps) step.pending = false;
+    job.steps = [...job.steps, { at, text, pending: true }].slice(-MAX_STEPS);
+    this.deps.feed?.step(QUICK_FIX_SOURCE, text, job.id, at);
+  }
+
+  private onEvent(job: QuickFixJob, event: PiStreamEvent): void {
+    const now = Date.now();
+    if (event.type === "tool_execution_start") {
+      job.tools += 1;
+      this.addStep(job, describeToolCall(event.toolName, event.args), now);
+    } else if (event.type === "turn_start") job.turns += 1;
+    else if (event.type === "thought") this.deps.feed?.thought(QUICK_FIX_SOURCE, event.text, now);
+    else if (event.type === "retry") this.addStep(job, `provider retry ${event.attempt}/${event.maxAttempts}`, now);
+    else return;
+    this.changed();
+  }
+
+  private async run(job: QuickFixJob): Promise<void> {
+    const profile = this.deps.profile();
+    const controller = new AbortController();
+    this.controllers.set(job.id, controller);
+    job.status = "running";
+    job.startedAt = Date.now();
+    job.thinking = profile.thinking;
+    if (profile.model) job.model = profile.model;
+    this.deps.feed?.log(QUICK_FIX_SOURCE, `started: ${jobTitle(job)}`, "info", job.startedAt);
+    this.changed();
+    try {
+      const result = await runPiAgent(
+        {
+          cwd: this.deps.cwd,
+          task: job.prompt,
+          systemPrompt: quickFixPrompt(profile.instructions),
+          tools: QUICK_FIX_TOOLS,
+          model: profile.model,
+          thinking: profile.thinking,
+          timeoutMs: profile.timeoutMs,
+          signal: controller.signal,
+          stallTimeoutMs: this.deps.stallTimeoutMs,
+          toolStallTimeoutMs: this.deps.toolStallTimeoutMs,
+          onEvent: (event) => this.onEvent(job, event),
+        },
+        this.deps.runProcess ?? spawnPiProcess,
+      );
+      job.status = result.status;
+      job.report = result.output.trim() || undefined;
+      job.error = result.error;
+      job.usage = result.usage;
+      if (result.model) job.model = result.model;
+    } catch (error) {
+      job.status = "failed";
+      job.error = (error as Error).message;
+    } finally {
+      this.controllers.delete(job.id);
+      this.finish(job);
+    }
+  }
+
+  private finish(job: QuickFixJob): void {
+    job.finishedAt = Date.now();
+    for (const step of job.steps) step.pending = false;
+    this.deps.feed?.end(job.id, job.status !== "success");
+    const ok = job.status === "success";
+    const outcome = ok ? "done" : `${job.status}${job.error ? ` — ${job.error.split("\n")[0]}` : ""}`;
+    this.deps.feed?.log(QUICK_FIX_SOURCE, `${outcome}: ${jobTitle(job)}`, ok ? "success" : job.status === "cancelled" ? "warning" : "error", job.finishedAt);
+    appendMetrics(this.deps.root, this.deps.configDir, [quickFixMetric(job)]);
+    this.deps.notify?.(`bot-lobby quick fix ${outcome}: ${jobTitle(job)}`, ok ? "info" : "warning");
+    this.changed();
+    this.pump();
+  }
+}
+
+export function quickFixMetric(job: QuickFixJob): MetricRecord {
+  const started = job.startedAt ?? job.createdAt;
+  return {
+    id: `${job.id}-${started}`,
+    kind: "quickfix",
+    agent: QUICK_FIX_SOURCE,
+    ...(job.model ? { model: job.model } : {}),
+    ...(job.thinking ? { thinking: job.thinking } : {}),
+    status: job.status === "queued" || job.status === "running" ? "failed" : job.status,
+    startedAt: new Date(started).toISOString(),
+    durationMs: Math.max(0, (job.finishedAt ?? started) - started),
+    turns: job.usage?.turns || job.turns || undefined,
+    tools: job.tools,
+    ...(job.usage ? { input: job.usage.input, output: job.usage.output, cost: job.usage.cost } : {}),
+  };
+}

package/src/lobby/runtime.ts

@@ -0,0 +1,440 @@
+/**
+ * The lobby inside pi: one runtime per interactive session. It mounts the
+ * full-screen view as an overlay on pi's own TUI (captured through a zero-line
+ * anchor widget, so pi does not treat the lobby as a blocking dialog), steps
+ * aside while a real dialog asks the user something, narrates the Master's own
+ * turn into the feed, passes plan comments to the Master that owns a task and
+ * records each Master turn in the metrics log.
+ */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getSelectListTheme } from "@earendil-works/pi-coding-agent";
+import { Key, type OverlayHandle, type TUI } from "@earendil-works/pi-tui";
+import { TERMINAL_STATES } from "../schemas/task.ts";
+import { listTasks, loadTask } from "../state/persistence.ts";
+import { detectProjectRoot, loadConfig } from "../state/project.ts";
+import { addPlanComment, commentMessage, markCommentsDelivered, readPlanComments, undeliveredComments } from "../state/comments.ts";
+import { discardPlannedTask, listPlannedTasks, markPlannedTaskStarted, plannedTaskRequest, type PlannedTask } from "../state/backlog.ts";
+import { appendMetrics, readMetrics, type MetricStatus } from "../state/metrics.ts";
+import { describeToolCall } from "../pi/activity.ts";
+import { applyStatus, currentZenTask, isMinimized, onMinimizeChange, onRunUpdates, setMinimized, setWidgetSuppressor, ZenScene, zenSnapshot } from "../pi/ui.ts";
+import { isSubagentProcess } from "../pi/quiet.ts";
+import { modelRef, resolveLobbyProfile, resolvePanelProfile } from "../pi/model-support.ts";
+import { modelLookup } from "../pi/tools.ts";
+import { startTask } from "../pi/start-task.ts";
+import type { LobbyAgentKind, PanelMember } from "../schemas/configuration.ts";
+import { chatFromEntries, chatText, lobbyFeed, textOf } from "./feed.ts";
+import { QuickFixQueue } from "./quickfix.ts";
+import { PlanningSession, type PlannerSeed } from "./planner.ts";
+import { execCommand, IssuesState } from "./issues.ts";
+import { LobbyView, type LobbyHost, type TabId } from "./view.ts";
+import type { LobbyTheme } from "./layout.ts";
+
+export const ANCHOR_KEY = "bot-lobby-anchor";
+/** How often the owning session looks for new plan comments. */
+export const COMMENT_POLL_MS = 3000;
+
+interface Runtime {
+  pi: ExtensionAPI;
+  configDir: string;
+  ctx: ExtensionContext;
+  root: string;
+  tui?: TUI;
+  view?: LobbyView;
+  handle?: OverlayHandle;
+  visible: boolean;
+  /** Stepped aside while pi shows a dialog. */
+  asideForPrompt: boolean;
+  scene: ZenScene;
+  quickfix: QuickFixQueue;
+  planner?: PlanningSession;
+  issues: IssuesState;
+  poll?: ReturnType<typeof setInterval>;
+  unsubscribeFeed?: () => void;
+}
+
+let runtime: Runtime | undefined;
+
+export function isLobbyVisible(): boolean {
+  return runtime?.visible === true;
+}
+
+function rerender(): void {
+  if (runtime?.visible) runtime.tui?.requestRender();
+}
+
+function sessionModel(ctx: ExtensionContext): string | undefined {
+  return ctx.model ? modelRef(ctx.model) : undefined;
+}
+
+function lobbyProfile(state: Runtime, kind: LobbyAgentKind) {
+  return resolveLobbyProfile(loadConfig(), kind, {
+    lookup: modelLookup(state.ctx),
+    sessionModel: sessionModel(state.ctx),
+    warn: (message) => state.ctx.ui.notify(message, "warning"),
+  });
+}
+
+/** Pass new comments on this session's task to its Master (held while minimized or paused). */
+export function deliverComments(): number {
+  const state = runtime;
+  if (!state || isMinimized()) return 0;
+  const task = currentZenTask();
+  if (!task || task.paused || TERMINAL_STATES.includes(task.state)) return 0;
+  const fresh = undeliveredComments(readPlanComments(state.root, state.configDir, task.id));
+  if (fresh.length === 0) return 0;
+  const current = loadTask(state.root, state.configDir, task.id) ?? task;
+  state.pi.sendUserMessage(commentMessage(task.id, fresh, Boolean(current.plan)), state.ctx.isIdle() ? undefined : { deliverAs: "steer" });
+  markCommentsDelivered(state.root, state.configDir, task.id, fresh.map((comment) => comment.id));
+  lobbyFeed.log("LOBBY", `passed ${fresh.length} plan comment${fresh.length === 1 ? "" : "s"} on ${task.id} to the oracle`, "info");
+  return fresh.length;
+}
+
+function addComment(state: Runtime, taskId: string, text: string): string {
+  const task = loadTask(state.root, state.configDir, taskId);
+  if (!task) return `no task ${taskId}`;
+  if (TERMINAL_STATES.includes(task.state)) return `${taskId} is ${task.state}; there is no plan left to change`;
+  const sessionId = state.ctx.sessionManager.getSessionId();
+  try {
+    addPlanComment(state.root, state.configDir, taskId, text, sessionId);
+  } catch (error) {
+    return (error as Error).message;
+  }
+  lobbyFeed.log("LOBBY", `comment on ${taskId}'s plan saved`, "info");
+  if (task.ownerSessionId === sessionId) {
+    if (deliverComments() === 0) return `comment saved — it reaches the oracle once ${taskId} is resumed or restored`;
+    return `comment sent to the oracle — it will ${task.plan ? "amend the plan" : "revise the proposal"}`;
+  }
+  if (!task.ownerSessionId) return `comment saved — ${taskId} has no owning session; it is delivered once a session claims it`;
+  return `comment saved — the session driving ${taskId} passes it to its oracle`;
+}
+
+function failed(state: Runtime, what: string, error: Error): void {
+  lobbyFeed.log("LOBBY", `${what} — ${error.message}`, "error");
+  state.ctx.ui.notify(`bot-lobby: ${what} — ${error.message}`, "error");
+}
+
+function toOracle(state: Runtime, text: string): string | undefined {
+  const busy = !state.ctx.isIdle();
+  if (text.startsWith("/")) {
+    state.pi.sendUserMessage(text, { expandPromptTemplates: true, ...(busy ? { deliverAs: "followUp" as const } : {}) });
+    return `sent ${text.split(/\s+/)[0]} to pi (built-in commands need the lobby hidden: alt+l)`;
+  }
+  if (!currentZenTask()) {
+    startTask(state.pi, state.ctx, state.configDir, text).catch((error: Error) => failed(state, "could not start the task", error));
+    return "starting a task — the oracle takes it from here";
+  }
+  state.pi.sendUserMessage(text, busy ? { deliverAs: "steer" } : undefined);
+  return undefined;
+}
+
+function startPlanned(state: Runtime, plan: PlannedTask): string {
+  const current = currentZenTask();
+  if (current) return `this session already drives ${current.id}; finish or cancel it first, or start ${plan.id} from another session`;
+  startTask(state.pi, state.ctx, state.configDir, plannedTaskRequest(plan))
+    .then((task) => {
+      if (!task) return;
+      markPlannedTaskStarted(state.root, state.configDir, plan.id, task.id);
+      state.view?.setTab("lobby");
+      rerender();
+    })
+    .catch((error: Error) => failed(state, `could not start ${plan.id}`, error));
+  return `starting ${plan.id} as a task…`;
+}
+
+function seatProfile(state: Runtime, member: PanelMember) {
+  return resolvePanelProfile(loadConfig(), member, {
+    lookup: modelLookup(state.ctx),
+    sessionModel: sessionModel(state.ctx),
+    warn: (message) => state.ctx.ui.notify(message, "warning"),
+  });
+}
+
+function newPlanner(state: Runtime, seed?: PlannerSeed, seats?: readonly PanelMember[]): PlanningSession {
+  state.planner?.cancel();
+  const config = loadConfig();
+  const workflow = config.workflow;
+  state.planner = new PlanningSession({
+    cwd: state.ctx.cwd,
+    root: state.root,
+    configDir: state.configDir,
+    profile: () => lobbyProfile(state, "planner"),
+    memberProfile: (member) => seatProfile(state, member),
+    panel: seats ?? config.lobby.planningPanel,
+    stallTimeoutMs: workflow.stallTimeoutMs,
+    toolStallTimeoutMs: workflow.toolStallTimeoutMs,
+    feed: lobbyFeed,
+    onChange: rerender,
+  }, seed);
+  return state.planner;
+}
+
+function host(state: Runtime, tui: TUI): LobbyHost {
+  return {
+    rows: () => tui.terminal.rows,
+    theme: () => state.ctx.ui.theme as LobbyTheme,
+    sessionId: () => state.ctx.sessionManager.getSessionId(),
+    zen: () => {
+      const snapshot = zenSnapshot();
+      return { ...(snapshot.task ? { task: snapshot.task } : {}), runs: snapshot.runs };
+    },
+    // The scene's height budget is 3/4 of the rows it is given.
+    scene: (width, height) => state.scene.lines(width, Math.floor(height / 0.75), state.ctx.ui.theme),
+    advanceScene: (now) => {
+      state.scene.advance(now);
+      return state.scene.delay(now);
+    },
+    feed: lobbyFeed,
+    masterBusy: () => !state.ctx.isIdle(),
+    tasks: () => listTasks(state.root, state.configDir),
+    plans: () => listPlannedTasks(state.root, state.configDir),
+    comments: (taskId) => readPlanComments(state.root, state.configDir, taskId),
+    metrics: () => readMetrics(state.root, state.configDir),
+    toOracle: (text) => toOracle(state, text),
+    comment: (taskId, text) => addComment(state, taskId, text),
+    startPlanned: (plan) => startPlanned(state, plan),
+    discardPlan: (id) => discardPlannedTask(state.root, state.configDir, id),
+    abortMaster: () => state.ctx.abort(),
+    hide: () => hideLobby(),
+    quickfix: state.quickfix,
+    planner: () => state.planner,
+    newPlanner: (seed, seats) => newPlanner(state, seed, seats),
+    defaultPanel: () => loadConfig().lobby.planningPanel,
+    seatLabel: (member) => {
+      const profile = seatProfile(state, member);
+      return `${profile.model ?? "session model"} · ${profile.thinking}`;
+    },
+    issues: state.issues,
+    profileLabel: (kind) => {
+      const profile = lobbyProfile(state, kind);
+      return `${profile.model ?? "session model"} · ${profile.thinking}`;
+    },
+    requestRender: () => tui.requestRender(),
+  };
+}
+
+/** Show the lobby (optionally on `tab`); false when there is no interactive TUI. */
+export function showLobby(tab?: TabId): boolean {
+  const state = runtime;
+  if (!state?.tui) return false;
+  if (isMinimized()) setMinimized(false);
+  if (!state.view || !state.handle) {
+    const theme = state.ctx.ui.theme;
+    state.view = new LobbyView(state.tui, host(state, state.tui), { borderColor: (text) => theme.fg("border", text), selectList: getSelectListTheme() });
+    state.handle = state.tui.showOverlay(state.view, { width: "100%", maxHeight: "100%", anchor: "top-left" });
+  } else {
+    state.handle.setHidden(false);
+    state.handle.focus();
+  }
+  state.visible = true;
+  state.asideForPrompt = false;
+  if (tab) state.view.setTab(tab);
+  state.view.start();
+  applyStatus(state.ctx, state.root, state.configDir);
+  state.tui.requestRender();
+  return true;
+}
+
+export function hideLobby(): void {
+  const state = runtime;
+  if (!state?.view || !state.visible) return;
+  state.visible = false;
+  state.asideForPrompt = false;
+  state.view.stop();
+  state.handle?.setHidden(true);
+  applyStatus(state.ctx, state.root, state.configDir);
+  state.tui?.requestRender();
+}
+
+export function toggleLobby(): boolean {
+  if (isLobbyVisible()) {
+    hideLobby();
+    return true;
+  }
+  return showLobby();
+}
+
+/** Open the lobby when this session drives a task and the config asks for it. */
+export function autoOpenLobby(): void {
+  if (runtime && loadConfig().lobby.autoOpen && currentZenTask()) showLobby("lobby");
+}
+
+/** Step aside while pi shows a dialog (an approval, a question), and come back after. */
+function promptStarted(): void {
+  const state = runtime;
+  if (!state?.visible || !state.handle) return;
+  state.asideForPrompt = true;
+  state.handle.setHidden(true);
+}
+
+function promptEnded(): void {
+  const state = runtime;
+  if (!state?.asideForPrompt || !state.handle) return;
+  state.asideForPrompt = false;
+  if (state.visible) state.handle.setHidden(false);
+}
+
+function shutdown(): void {
+  const state = runtime;
+  if (!state) return;
+  runtime = undefined;
+  if (state.poll) clearInterval(state.poll);
+  state.unsubscribeFeed?.();
+  state.quickfix.cancelAll();
+  state.planner?.cancel();
+  state.view?.dispose();
+  state.handle?.hide();
+  setWidgetSuppressor(() => false);
+  onRunUpdates(undefined);
+  onMinimizeChange(undefined);
+}
+
+/** Create the session's lobby runtime (interactive master sessions only). */
+export function initLobby(pi: ExtensionAPI, ctx: ExtensionContext, configDir: string): void {
+  shutdown();
+  if (isSubagentProcess() || ctx.mode !== "tui") return;
+  const root = detectProjectRoot(ctx.cwd, configDir);
+  const workflow = loadConfig().workflow;
+  const state: Runtime = {
+    pi,
+    configDir,
+    ctx,
+    root,
+    visible: false,
+    asideForPrompt: false,
+    scene: new ZenScene(),
+    quickfix: undefined as unknown as QuickFixQueue,
+    issues: new IssuesState(execCommand, ctx.cwd, rerender),
+  };
+  state.quickfix = new QuickFixQueue({
+    cwd: ctx.cwd,
+    root,
+    configDir,
+    profile: () => lobbyProfile(state, "quickfix"),
+    stallTimeoutMs: workflow.stallTimeoutMs,
+    toolStallTimeoutMs: workflow.toolStallTimeoutMs,
+    feed: lobbyFeed,
+    onChange: rerender,
+    notify: (message, level) => {
+      if (!state.visible) ctx.ui.notify(message, level);
+    },
+  });
+  runtime = state;
+  lobbyFeed.clear();
+  lobbyFeed.seedChat(chatFromEntries(ctx.sessionManager.getBranch()));
+  state.unsubscribeFeed = lobbyFeed.onChange(rerender);
+  setWidgetSuppressor(() => runtime?.visible === true);
+  onRunUpdates((runs) => lobbyFeed.runs(runs));
+  onMinimizeChange((value) => {
+    if (value) hideLobby();
+  });
+  // Capture pi's TUI through a zero-line widget below the editor.
+  ctx.ui.setWidget(ANCHOR_KEY, (tui) => {
+    state.tui = tui;
+    return { render: () => [], invalidate: () => {} };
+  }, { placement: "belowEditor" });
+  state.poll = setInterval(() => deliverComments(), COMMENT_POLL_MS);
+  state.poll.unref?.();
+}
+
+interface MasterTurn {
+  startedAt: number;
+  /** The task the turn worked on; kept from the start so the turn that completes it still counts. */
+  taskId?: string;
+  model?: string;
+  thinking: string;
+  tools: number;
+  turns: number;
+  input: number;
+  output: number;
+  cost: number;
+}
+
+function turnStatus(messages: readonly unknown[]): MetricStatus {
+  const last = [...messages].reverse().find((message) => (message as { role?: string })?.role === "assistant") as { stopReason?: string } | undefined;
+  if (last?.stopReason === "aborted") return "cancelled";
+  if (last?.stopReason === "error") return "failed";
+  return "success";
+}
+
+/** Narrate the Master's own turn into the feed and record it as a metric; the lobby follows pi's dialogs. */
+export function registerLobbyEvents(pi: ExtensionAPI, configDir: string): void {
+  if (isSubagentProcess()) return;
+  let turn: MasterTurn | undefined;
+  const track = (ctx: ExtensionContext) => {
+    if (runtime) runtime.ctx = ctx;
+  };
+  pi.registerShortcut(Key.alt("l"), {
+    description: "bot-lobby: open or hide the lobby",
+    handler: (ctx) => {
+      if (!toggleLobby()) ctx.ui.notify("The lobby needs pi's interactive terminal UI.", "warning");
+    },
+  });
+  pi.on("session_start", (_event, ctx) => {
+    initLobby(pi, ctx, configDir);
+    autoOpenLobby();
+  });
+  pi.on("session_shutdown", () => shutdown());
+  pi.on("ui_prompt_start", () => promptStarted());
+  pi.on("ui_prompt_end", () => promptEnded());
+  pi.on("agent_start", (_event, ctx) => {
+    track(ctx);
+    const taskId = currentZenTask()?.id;
+    turn = { startedAt: Date.now(), ...(taskId ? { taskId } : {}), ...(ctx.model ? { model: modelRef(ctx.model) } : {}), thinking: pi.getThinkingLevel(), tools: 0, turns: 0, input: 0, output: 0, cost: 0 };
+  });
+  pi.on("tool_execution_start", (event) => {
+    if (turn) turn.tools += 1;
+    lobbyFeed.begin("MASTER", describeToolCall(event.toolName, event.args), event.toolCallId);
+  });
+  pi.on("tool_execution_end", (event) => lobbyFeed.end(event.toolCallId, event.isError));
+  pi.on("message_update", (event) => {
+    const update = event.assistantMessageEvent;
+    if (update.type === "thinking_delta") lobbyFeed.thinkDelta("MASTER", update.delta);
+    else if (update.type === "thinking_end") lobbyFeed.thinkEnd("MASTER", update.content);
+    else if (update.type === "text_delta") lobbyFeed.replyDelta(update.delta);
+  });
+  pi.on("message_end", (event) => {
+    const message = event.message as { role?: string; content?: unknown; stopReason?: string; errorMessage?: string; usage?: { input?: number; output?: number; cost?: { total?: number } } };
+    if (message.role === "assistant") {
+      lobbyFeed.replyEnd();
+      lobbyFeed.thinkEnd("MASTER");
+      if (message.stopReason === "error") {
+        const error = (message.errorMessage ?? "the model call failed").split("\n")[0]!;
+        lobbyFeed.say("note", `✗ the oracle's turn failed: ${error}`);
+        lobbyFeed.log("MASTER", `turn failed — ${error}`, "error");
+      }
+      if (turn) {
+        turn.turns += 1;
+        turn.input += message.usage?.input ?? 0;
+        turn.output += message.usage?.output ?? 0;
+        turn.cost += message.usage?.cost?.total ?? 0;
+      }
+    }
+    if (message.role !== "user" && message.role !== "assistant") return;
+    const line = chatText(message.role, textOf(message.content));
+    if (line) lobbyFeed.say(line.role, line.text);
+  });
+  pi.on("agent_end", (event, ctx) => {
+    track(ctx);
+    const finished = turn;
+    turn = undefined;
+    lobbyFeed.replyEnd();
+    const taskId = finished?.taskId ?? currentZenTask()?.id;
+    if (!finished || !taskId || !runtime) return;
+    appendMetrics(runtime.root, configDir, [{
+      id: `master-${finished.startedAt}`,
+      kind: "master",
+      agent: "MASTER",
+      ...(finished.model ? { model: finished.model } : {}),
+      thinking: finished.thinking,
+      status: turnStatus(event.messages),
+      startedAt: new Date(finished.startedAt).toISOString(),
+      durationMs: Date.now() - finished.startedAt,
+      ...(finished.turns ? { turns: finished.turns } : {}),
+      tools: finished.tools,
+      input: finished.input,
+      output: finished.output,
+      cost: finished.cost,
+      taskId,
+    }]);
+  });
+}