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

package/src/pi/ui.ts

@@ -129,8 +129,17 @@ export function isMinimized(): boolean {
   return minimized;
 }
 
+/** Told when minimize changes, so the lobby can step aside too. */
+let minimizeListener: ((value: boolean) => void) | undefined;
+
+export function onMinimizeChange(listener: ((value: boolean) => void) | undefined): void {
+  minimizeListener = listener;
+}
+
 export function setMinimized(value: boolean): void {
+  if (minimized === value) return;
   minimized = value;
+  minimizeListener?.(value);
 }
 
 /** Flip minimize/restore and refresh the footer; the session is unchanged. */
@@ -191,45 +200,27 @@ export function isReaction(previous: string | undefined, next: Situation): boole
   return !previous.startsWith("working|") || next.flag !== undefined || next.handover === true;
 }
 
-/** Animated zen scene + plan checklist shown above the editor while a task is active. */
-class ZenWidget implements Component {
-  private tick = 0;
-  private cache: { key: string; theme: Theme; lines: string[] } | undefined;
-  private delay = liveTickDelay();
-  private timer: ReturnType<typeof setInterval>;
-  private disposed = false;
+/**
+ * The animated zen scene: the tick, each sprite's expression schedule and the
+ * reactions to what the agents go through. The widget and the lobby's home tab
+ * each own one and advance it from their own clock.
+ */
+export class ZenScene {
+  tick = 0;
   private readonly expressions: Record<ExpressionKey, ExpressionState>;
   private readonly situations: Partial<Record<SlotId, string>> = {};
-  private readonly tui: TUI;
-  private readonly theme: () => Theme;
   private readonly rng: () => number;
+  private cache: { key: string; theme: Theme | undefined; lines: string[] } | undefined;
 
-  constructor(tui: TUI, theme: () => Theme, rng: () => number = Math.random) {
-    this.tui = tui;
-    this.theme = theme;
+  constructor(rng: () => number = Math.random, now = Date.now()) {
     this.rng = rng;
-    const now = Date.now();
     const entries = EXPRESSION_KEYS.map((key) => [key, createExpression(now, rng, gapFor(key))] as const);
     this.expressions = Object.fromEntries(entries) as Record<ExpressionKey, ExpressionState>;
-    this.timer = setInterval(() => this.advance(), this.delay);
-    mountedWidget = this;
-  }
-
-  /** Repaint now: state changed between ticks. */
-  refresh(): void {
-    if (!this.disposed) this.tui.requestRender();
   }
 
-  private advance(): void {
-    if (this.disposed) return;
+  /** One clock step: expressions advance and agents react to their new situations. */
+  advance(now = Date.now()): void {
     this.tick += 1;
-    const now = Date.now();
-    this.play(now);
-    this.retime(now);
-    this.tui.requestRender();
-  }
-
-  private play(now: number): void {
     const situations = slotSituations(zenState.runs, now);
     for (const key of EXPRESSION_KEYS) {
       this.expressions[key] = advanceExpression(this.expressions[key], now, this.rng, gapFor(key, situations), blinkChanceFor(key, situations));
@@ -241,39 +232,24 @@ class ZenWidget implements Component {
     }
   }
 
-  /** One interval, retimed when work starts or stops or an expression plays. */
-  private retime(now: number): void {
-    const delay = expressionTickDelay(Object.values(this.expressions), now, isLive(), talkFrame(oracleSpokeAt, now) !== undefined);
-    if (delay === this.delay) return;
-    this.delay = delay;
-    clearInterval(this.timer);
-    this.timer = setInterval(() => this.advance(), delay);
+  /** The delay until the next step: fast while an expression plays or the oracle talks. */
+  delay(now = Date.now()): number {
+    return expressionTickDelay(Object.values(this.expressions), now, isLive(), talkFrame(oracleSpokeAt, now) !== undefined);
   }
 
   private motion(now: number): OracleMotion {
     return { phase: expressionPhase(this.expressions.oracle, now), talk: talkFrame(oracleSpokeAt, now) };
   }
 
-  private frames(): Partial<Record<ExpressionKey, number>> {
-    return Object.fromEntries(EXPRESSION_KEYS.map((key) => [key, this.expressions[key].frame]));
-  }
-
-  private variants(): Partial<Record<SlotId, number>> {
-    return Object.fromEntries(SLOT_IDS.map((id) => [id, this.expressions[id].variant]));
-  }
-
   /**
-   * The panel only changes with the tick, an expression frame, the widget state or
-   * the elapsed second, so every other repaint (typing in the editor, streaming
-   * output) reuses the last lines instead of recomposing the scene.
+   * The scene lines for the current zen state. They only change with the tick,
+   * an expression frame, the widget state or the elapsed second, so any other
+   * repaint (typing, streaming output) reuses the last lines.
    */
-  render(width: number): string[] {
-    const now = Date.now();
-    const rows = this.tui.terminal.rows;
-    const theme = this.theme();
-    const expressions = this.frames();
+  lines(width: number, rows: number, theme: Theme | undefined, now = Date.now()): string[] {
+    const expressions = Object.fromEntries(EXPRESSION_KEYS.map((key) => [key, this.expressions[key].frame])) as Partial<Record<ExpressionKey, number>>;
+    const variants = Object.fromEntries(SLOT_IDS.map((id) => [id, this.expressions[id].variant])) as Partial<Record<SlotId, number>>;
     const quiet = isQuiet();
-    const variants = this.variants();
     const frameKey = [...EXPRESSION_KEYS.map((key) => expressions[key] ?? 0), ...SLOT_IDS.map((id) => variants[id] ?? 0)].join(",");
     const motion = this.motion(now);
     const key = `${width}|${rows}|${this.tick}|${frameKey}|${motion.phase}|${motion.talk}|${zenVersion}|${Math.floor(now / 1000)}|${quiet}`;
@@ -287,6 +263,59 @@ class ZenWidget implements Component {
   invalidate(): void {
     this.cache = undefined;
   }
+}
+
+/** The zen state as the lobby reads it: the session's active task and its runs. */
+export function zenSnapshot(): { task: Task | undefined; runs: readonly AgentRun[]; version: number; oracleActivity: string | undefined } {
+  return { task: zenState.task, runs: zenState.runs, version: zenVersion, oracleActivity };
+}
+
+/** Zen scene + plan checklist shown above the editor while a task is active and the lobby is closed. */
+class ZenWidget implements Component {
+  private readonly scene: ZenScene;
+  private delay = liveTickDelay();
+  private timer: ReturnType<typeof setInterval>;
+  private disposed = false;
+  private readonly tui: TUI;
+  private readonly theme: () => Theme;
+
+  constructor(tui: TUI, theme: () => Theme, rng: () => number = Math.random) {
+    this.tui = tui;
+    this.theme = theme;
+    this.scene = new ZenScene(rng);
+    this.timer = setInterval(() => this.advance(), this.delay);
+    mountedWidget = this;
+  }
+
+  /** Repaint now: state changed between ticks. */
+  refresh(): void {
+    if (!this.disposed) this.tui.requestRender();
+  }
+
+  private advance(): void {
+    if (this.disposed) return;
+    const now = Date.now();
+    this.scene.advance(now);
+    this.retime(now);
+    this.tui.requestRender();
+  }
+
+  /** One interval, retimed when work starts or stops or an expression plays. */
+  private retime(now: number): void {
+    const delay = this.scene.delay(now);
+    if (delay === this.delay) return;
+    this.delay = delay;
+    clearInterval(this.timer);
+    this.timer = setInterval(() => this.advance(), delay);
+  }
+
+  render(width: number): string[] {
+    return this.scene.lines(width, this.tui.terminal.rows, this.theme());
+  }
+
+  invalidate(): void {
+    this.scene.invalidate();
+  }
 
   dispose(): void {
     this.disposed = true;
@@ -295,6 +324,21 @@ class ZenWidget implements Component {
   }
 }
 
+/** True while the full-screen lobby is showing; the small widget then stays unmounted. */
+let widgetSuppressed: () => boolean = () => false;
+let widgetMounted = false;
+
+/** The lobby registers how to tell whether it covers the screen. */
+export function setWidgetSuppressor(check: () => boolean): void {
+  widgetSuppressed = check;
+}
+
+function unmountWidget(ctx: ExtensionContext): void {
+  if (!widgetMounted) return;
+  widgetMounted = false;
+  ctx.ui.setWidget(STATUS_KEY, undefined);
+}
+
 function leaveZen(ctx: ExtensionContext): void {
   if (!zenOn) return;
   zenOn = false;
@@ -317,17 +361,32 @@ export function applyStatus(ctx: ExtensionContext, root: string, configDir: stri
   const active = Boolean(task && !TERMINAL_STATES.includes(task.state));
   if (!active) {
     leaveZen(ctx);
+    widgetMounted = false;
     ctx.ui.setWidget(STATUS_KEY, undefined);
     return;
   }
+  zenOn = true;
   ctx.ui.setWorkingVisible(false);
   ctx.ui.setWorkingIndicator({ frames: [] });
-  if (!zenOn) {
-    zenOn = true;
+  if (widgetSuppressed()) return unmountWidget(ctx);
+  if (!widgetMounted) {
+    widgetMounted = true;
     ctx.ui.setWidget(STATUS_KEY, (tui) => new ZenWidget(tui, () => ctx.ui.theme));
   }
 }
 
+/** The session's active task as the widget last loaded it (undefined when none or minimized). */
+export function currentZenTask(): Task | undefined {
+  return zenState.task;
+}
+
+/** Called with every streamed run update, so the lobby's activity log can follow the agents. */
+let runListener: ((runs: readonly AgentRun[]) => void) | undefined;
+
+export function onRunUpdates(listener: ((runs: readonly AgentRun[]) => void) | undefined): void {
+  runListener = listener;
+}
+
 /**
  * Streamed run updates (start, every activity change, finish) from an in-flight
  * `orchestrate` call. The task on disk does not change mid-call, so this only
@@ -335,6 +394,7 @@ export function applyStatus(ctx: ExtensionContext, root: string, configDir: stri
  * Before any task is loaded it falls back to `applyStatus` so the widget appears.
  */
 export function reportRuns(ctx: ExtensionContext, root: string, configDir: string, runs: AgentRun[]): void {
+  runListener?.(runs);
   if (!zenState.task && !minimized) {
     applyStatus(ctx, root, configDir, runs);
     return;
@@ -344,6 +404,7 @@ export function reportRuns(ctx: ExtensionContext, root: string, configDir: strin
 
 export function clearStatus(ctx: ExtensionContext): void {
   leaveZen(ctx);
+  widgetMounted = false;
   oracleActivity = undefined;
   zenState = { task: undefined, live: [], runs: [] };
   ctx.ui.setStatus(STATUS_KEY, undefined);

package/src/schemas/configuration.ts

@@ -40,9 +40,15 @@ export interface ScoutConfig {
 }
 
 /** Subagent kinds with their own settings entry. */
-export const SUBAGENT_KINDS = ["designer", "backend", "qa", "scout", "researcher"] as const;
+export const SUBAGENT_KINDS = ["designer", "backend", "qa", "scout", "researcher", "quickfix", "planner"] as const;
 export type SubagentKind = (typeof SUBAGENT_KINDS)[number];
 
+/** Lobby agents that run outside the workflow: direct quick fixes and the task planner. */
+export type LobbyAgentKind = "quickfix" | "planner";
+
+/** Settings kinds a workflow run (domain + role) can draw from. */
+export type WorkflowProfileKind = Domain | "scout" | "researcher";
+
 export interface WorkflowConfig {
   maxReviewIterations: number;
   maxParallelScouts: number;
@@ -69,13 +75,34 @@ export interface KnowledgeConfig {
   scratchpadMaxChars: number;
 }
 
+/** Planning panel seats: each domain agent, plus the researcher, questions the user in plan mode. */
+export const PANEL_MEMBERS = ["backend", "designer", "qa", "researcher"] as const;
+export type PanelMember = (typeof PANEL_MEMBERS)[number];
+
+export function isPanelMember(value: string): value is PanelMember {
+  return (PANEL_MEMBERS as readonly string[]).includes(value);
+}
+
+/** The full-screen lobby. */
+export interface LobbyConfig {
+  /** Open by itself when this session starts or resumes a task. */
+  autoOpen: boolean;
+  /** Who sits on the planning panel next to the oracle, until toggled in the Plan tab. */
+  planningPanel: PanelMember[];
+}
+
 export interface BotLobbyConfig {
   master: AgentModelConfig;
   agents: Record<"designer" | "backend" | "qa", AgentModelConfig>;
   scout: ScoutConfig;
   researcher: AgentModelConfig;
+  /** Direct quick fixes from the lobby: no scouting, planning or review. */
+  quickFix: AgentModelConfig;
+  /** The task planner that grills the user until a plan is clear; `timeoutMs` bounds one turn. */
+  planner: AgentModelConfig;
   workflow: WorkflowConfig;
   knowledge: KnowledgeConfig;
+  lobby: LobbyConfig;
 }
 
 export const DEFAULT_CONFIG: BotLobbyConfig = {
@@ -87,6 +114,8 @@ export const DEFAULT_CONFIG: BotLobbyConfig = {
   },
   scout: { model: INHERIT_MODEL, timeoutMs: 8 * 60 * 1000 },
   researcher: { model: INHERIT_MODEL, thinking: "low", instructions: "", timeoutMs: 10 * 60 * 1000 },
+  quickFix: { model: INHERIT_MODEL, thinking: "low", instructions: "", timeoutMs: 10 * 60 * 1000 },
+  planner: { model: INHERIT_MODEL, thinking: "high", instructions: "", timeoutMs: 5 * 60 * 1000 },
   workflow: {
     maxReviewIterations: 2,
     maxParallelScouts: 3,
@@ -106,6 +135,7 @@ export const DEFAULT_CONFIG: BotLobbyConfig = {
     scratchpadMaxParagraphs: 4,
     scratchpadMaxChars: 2000,
   },
+  lobby: { autoOpen: true, planningPanel: [...PANEL_MEMBERS] },
 };
 
 function positive(value: unknown): number | undefined {
@@ -129,6 +159,17 @@ function normalizeScout(override: Partial<ScoutConfig> | undefined): ScoutConfig
   };
 }
 
+function normalizeLobby(value: unknown): LobbyConfig {
+  const source = value as { autoOpen?: unknown; planningPanel?: unknown } | undefined;
+  const panel = Array.isArray(source?.planningPanel)
+    ? [...new Set(source.planningPanel.filter((entry): entry is PanelMember => typeof entry === "string" && isPanelMember(entry)))]
+    : [...DEFAULT_CONFIG.lobby.planningPanel];
+  return {
+    autoOpen: typeof source?.autoOpen === "boolean" ? source.autoOpen : DEFAULT_CONFIG.lobby.autoOpen,
+    planningPanel: PANEL_MEMBERS.filter((member) => panel.includes(member)),
+  };
+}
+
 /** Deep-merge user config over defaults, keeping unknown keys out. */
 export function resolveConfig(partial: unknown): BotLobbyConfig {
   const src = (partial ?? {}) as Record<string, unknown>;
@@ -144,8 +185,11 @@ export function resolveConfig(partial: unknown): BotLobbyConfig {
     },
     scout: normalizeScout(src.scout as Partial<ScoutConfig> | undefined),
     researcher: normalizeAgent(DEFAULT_CONFIG.researcher, src.researcher as Partial<AgentModelConfig> | undefined),
+    quickFix: normalizeAgent(DEFAULT_CONFIG.quickFix, src.quickFix as Partial<AgentModelConfig> | undefined),
+    planner: normalizeAgent(DEFAULT_CONFIG.planner, src.planner as Partial<AgentModelConfig> | undefined),
     workflow,
     knowledge,
+    lobby: normalizeLobby(src.lobby),
   };
 }
 
@@ -157,7 +201,7 @@ export function hasScoutThinking(partial: unknown): boolean {
 
 /** What one subagent run uses: model (undefined = not configured), thinking and time limit. */
 export interface AgentProfile {
-  kind: SubagentKind;
+  kind: WorkflowProfileKind;
   model?: string;
   thinking: string;
   timeoutMs: number;
@@ -165,7 +209,7 @@ export interface AgentProfile {
 }
 
 /** The settings entry a domain/role run draws from. */
-export function profileKind(domain: Domain, role: Role): SubagentKind {
+export function profileKind(domain: Domain, role: Role): WorkflowProfileKind {
   if (role === "scout") return "scout";
   if (role === "researcher") return "researcher";
   return domain;
@@ -192,6 +236,27 @@ export function agentProfile(config: BotLobbyConfig, domain: Domain, role: Role)
   return { kind, model: modelOf(entry.model), thinking: entry.thinking, timeoutMs: entry.timeoutMs ?? fallback, instructions };
 }
 
+/** The settings entry of a lobby agent (quick fix or planner). */
+export function lobbyAgentConfig(config: BotLobbyConfig, kind: LobbyAgentKind): AgentModelConfig {
+  return kind === "quickfix" ? config.quickFix : config.planner;
+}
+
+/** Profile for a lobby agent run, from settings alone; `model` is undefined while unset. */
+export function lobbyAgentProfile(config: BotLobbyConfig, kind: LobbyAgentKind): { model?: string; thinking: string; timeoutMs: number; instructions?: string } {
+  const entry = lobbyAgentConfig(config, kind);
+  return { model: modelOf(entry.model), thinking: entry.thinking, timeoutMs: entry.timeoutMs ?? config.workflow.agentTimeoutMs, instructions: entry.instructions };
+}
+
+/**
+ * A planning panel seat's profile: the domain's (or the researcher's) model,
+ * thinking and custom instructions, bounded by the planner's per-turn limit.
+ */
+export function panelMemberProfile(config: BotLobbyConfig, member: PanelMember): { model?: string; thinking: string; timeoutMs: number; instructions?: string } {
+  const entry = member === "researcher" ? config.researcher : config.agents[member];
+  const timeoutMs = config.planner.timeoutMs ?? config.workflow.agentTimeoutMs;
+  return { model: modelOf(entry.model), thinking: entry.thinking, timeoutMs, instructions: entry.instructions };
+}
+
 /** Resolves the model, thinking and time limit one subagent run uses. */
 export type ProfileResolver = (domain: Domain, role: Role) => AgentProfile;
 

package/src/schemas/findings.ts

@@ -111,6 +111,10 @@ export interface AgentRun {
   finishedAt?: string;
   /** Short target of the activity in flight: a file, command head or pattern. */
   detail?: string;
+  /** The tool call in flight in plain words (`reading users.ts`); feeds the lobby's activity log. */
+  step?: string;
+  /** The agent's latest finished thought, bounded; the lobby shows it in its thinking pane. */
+  thought?: string;
   /** Assistant turns and tool calls so far. */
   turns?: number;
   tools?: number;
@@ -121,6 +125,8 @@ export interface AgentRun {
   noteKind?: "info" | "warning";
   /** Model that actually served the run. */
   model?: string;
+  /** Thinking level the run was started with. */
+  thinking?: string;
   /** Killed by the stall watchdog after going silent. */
   stalled?: boolean;
   /** Asked to wrap up before its deadline; the report may be partial. */

package/src/schemas/task.ts

@@ -79,6 +79,7 @@ export interface RunLogEntry {
   startedAt: string;
   finishedAt?: string;
   model?: string;
+  thinking?: string;
   turns?: number;
   tools?: number;
   input?: number;

package/src/state/backlog.ts

@@ -0,0 +1,106 @@
+/**
+ * Pending tasks: plans the user worked out with the planner (optionally from a
+ * GitHub issue) and saved for later. They are not bot-lobby tasks yet, so no
+ * session owns them and the workflow never sees them; starting one creates a
+ * real task in the session that starts it. One file per entry, so two sessions
+ * saving at once cannot overwrite each other.
+ */
+import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { writeFileEnsured } from "../knowledge/store.ts";
+import { dataRoot } from "./project.ts";
+import { taskSlug } from "./persistence.ts";
+
+export interface IssueRef {
+  number: number;
+  title: string;
+  url?: string;
+}
+
+export interface PlannedTask {
+  id: string;
+  title: string;
+  /** The agreed plan in Markdown; it becomes the task request when started. */
+  brief: string;
+  createdAt: string;
+  updatedAt: string;
+  status: "pending" | "started";
+  issue?: IssueRef;
+  /** The bot-lobby task started from this entry. */
+  startedTaskId?: string;
+}
+
+export function backlogDir(root: string, configDir: string): string {
+  return join(dataRoot(root, configDir), "backlog");
+}
+
+function entryPath(root: string, configDir: string, id: string): string {
+  return join(backlogDir(root, configDir), `${id}.json`);
+}
+
+function isPlannedTask(value: unknown): value is PlannedTask {
+  const entry = value as Partial<PlannedTask> | undefined;
+  return Boolean(entry && typeof entry.id === "string" && typeof entry.title === "string" && typeof entry.brief === "string");
+}
+
+/** Save a new pending task; the id is `PLAN-<slug>` with a numeric suffix when taken. */
+export function savePlannedTask(
+  root: string,
+  configDir: string,
+  input: { title: string; brief: string; issue?: IssueRef },
+  now = new Date(),
+): PlannedTask {
+  const title = input.title.trim() || "planned task";
+  const brief = input.brief.trim();
+  if (!brief) throw new Error("a planned task needs a plan");
+  const base = `PLAN-${taskSlug(title, 32) || now.getTime().toString(36)}`;
+  let id = base;
+  for (let n = 2; existsSync(entryPath(root, configDir, id)); n++) id = `${base}-${n}`;
+  const at = now.toISOString();
+  const entry: PlannedTask = { id, title, brief, createdAt: at, updatedAt: at, status: "pending", ...(input.issue ? { issue: input.issue } : {}) };
+  writeFileEnsured(entryPath(root, configDir, id), JSON.stringify(entry, null, 2));
+  return entry;
+}
+
+export function loadPlannedTask(root: string, configDir: string, id: string): PlannedTask | undefined {
+  try {
+    const value = JSON.parse(readFileSync(entryPath(root, configDir, id), "utf8")) as unknown;
+    return isPlannedTask(value) ? value : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Every saved entry, pending first, newest first within each group; unreadable files are skipped. */
+export function listPlannedTasks(root: string, configDir: string): PlannedTask[] {
+  const dir = backlogDir(root, configDir);
+  if (!existsSync(dir)) return [];
+  const entries: PlannedTask[] = [];
+  for (const file of readdirSync(dir)) {
+    if (!file.endsWith(".json")) continue;
+    const entry = loadPlannedTask(root, configDir, file.slice(0, -".json".length));
+    if (entry) entries.push(entry);
+  }
+  return entries.sort((a, b) => {
+    if (a.status !== b.status) return a.status === "pending" ? -1 : 1;
+    return b.updatedAt.localeCompare(a.updatedAt);
+  });
+}
+
+export function markPlannedTaskStarted(root: string, configDir: string, id: string, taskId: string, now = new Date()): PlannedTask | undefined {
+  const entry = loadPlannedTask(root, configDir, id);
+  if (!entry) return undefined;
+  const next: PlannedTask = { ...entry, status: "started", startedTaskId: taskId, updatedAt: now.toISOString() };
+  writeFileEnsured(entryPath(root, configDir, id), JSON.stringify(next, null, 2));
+  return next;
+}
+
+export function discardPlannedTask(root: string, configDir: string, id: string): void {
+  rmSync(entryPath(root, configDir, id), { force: true });
+}
+
+/** The request a started task carries: the agreed plan, plus the issue it came from. */
+export function plannedTaskRequest(entry: PlannedTask): string {
+  const source = entry.issue ? `\n\nFrom GitHub issue #${entry.issue.number}: ${entry.issue.title}${entry.issue.url ? ` (${entry.issue.url})` : ""}` : "";
+  return `${entry.title}\n\nAgreed plan (from the planning session):\n${entry.brief}${source}`;
+}

package/src/state/comments.ts

@@ -0,0 +1,136 @@
+/**
+ * Plan comments: notes the user leaves on a task's approved plan (or its
+ * proposal) from the lobby, in any pi session. They live beside the task as an
+ * append-only JSON-lines log, never inside state.json, because the owning
+ * session rewrites state.json at the end of every workflow step and would
+ * silently drop a comment written by another session in the meantime.
+ *
+ * Each line is one event: a comment, its delivery to the owning Master, or the
+ * Master addressing it with an amended plan. Reading folds the events.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { taskDir } from "../knowledge/paths.ts";
+import { dataRoot } from "./project.ts";
+
+export type CommentStatus = "open" | "delivered" | "addressed";
+
+export interface PlanComment {
+  id: string;
+  taskId: string;
+  text: string;
+  createdAt: string;
+  /** The pi session that wrote the comment, when known. */
+  by?: string;
+  status: CommentStatus;
+  deliveredAt?: string;
+  addressedAt?: string;
+}
+
+type CommentEvent =
+  | { kind: "comment"; id: string; text: string; at: string; by?: string }
+  | { kind: "delivered"; id: string; at: string }
+  | { kind: "addressed"; id: string; at: string };
+
+/** Longest comment kept; the Master gets it verbatim. */
+export const MAX_COMMENT_CHARS = 2000;
+
+export function commentsPath(root: string, configDir: string, taskId: string): string {
+  return join(taskDir(dataRoot(root, configDir), taskId), "comments.jsonl");
+}
+
+function append(path: string, event: CommentEvent): void {
+  mkdirSync(dirname(path), { recursive: true });
+  appendFileSync(path, `${JSON.stringify(event)}\n`, "utf8");
+}
+
+function readEvents(path: string): CommentEvent[] {
+  if (!existsSync(path)) return [];
+  let text: string;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch {
+    return [];
+  }
+  const events: CommentEvent[] = [];
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const event = JSON.parse(line) as CommentEvent;
+      if (event && typeof event.id === "string" && typeof event.kind === "string") events.push(event);
+    } catch {
+      // A torn line from a crashed writer is skipped, never fatal.
+    }
+  }
+  return events;
+}
+
+/** Fold the event log into comments, oldest first. */
+export function foldComments(taskId: string, events: readonly CommentEvent[]): PlanComment[] {
+  const byId = new Map<string, PlanComment>();
+  for (const event of events) {
+    if (event.kind === "comment") {
+      if (byId.has(event.id)) continue;
+      byId.set(event.id, { id: event.id, taskId, text: event.text, createdAt: event.at, ...(event.by ? { by: event.by } : {}), status: "open" });
+      continue;
+    }
+    const comment = byId.get(event.id);
+    if (!comment) continue;
+    if (event.kind === "delivered" && comment.status === "open") {
+      comment.status = "delivered";
+      comment.deliveredAt = event.at;
+    } else if (event.kind === "addressed" && comment.status !== "addressed") {
+      comment.status = "addressed";
+      comment.addressedAt = event.at;
+    }
+  }
+  return [...byId.values()];
+}
+
+export function readPlanComments(root: string, configDir: string, taskId: string): PlanComment[] {
+  return foldComments(taskId, readEvents(commentsPath(root, configDir, taskId)));
+}
+
+/** Record a new comment; blank text is refused. */
+export function addPlanComment(root: string, configDir: string, taskId: string, text: string, by?: string, now = new Date()): PlanComment {
+  const body = text.trim().slice(0, MAX_COMMENT_CHARS);
+  if (!body) throw new Error("a plan comment needs some text");
+  const at = now.toISOString();
+  const id = `C-${now.getTime().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+  append(commentsPath(root, configDir, taskId), { kind: "comment", id, text: body, at, ...(by ? { by } : {}) });
+  return { id, taskId, text: body, createdAt: at, ...(by ? { by } : {}), status: "open" };
+}
+
+export function markCommentsDelivered(root: string, configDir: string, taskId: string, ids: readonly string[], now = new Date()): void {
+  const path = commentsPath(root, configDir, taskId);
+  for (const id of ids) append(path, { kind: "delivered", id, at: now.toISOString() });
+}
+
+export function markCommentsAddressed(root: string, configDir: string, taskId: string, ids: readonly string[], now = new Date()): void {
+  const path = commentsPath(root, configDir, taskId);
+  for (const id of ids) append(path, { kind: "addressed", id, at: now.toISOString() });
+}
+
+/** Comments the owning Master has not been told about yet. */
+export function undeliveredComments(comments: readonly PlanComment[]): PlanComment[] {
+  return comments.filter((comment) => comment.status === "open");
+}
+
+/** Comments the plan does not reflect yet: new or delivered but not addressed. */
+export function pendingComments(comments: readonly PlanComment[]): PlanComment[] {
+  return comments.filter((comment) => comment.status !== "addressed");
+}
+
+/**
+ * The message the owning Master receives for new comments: plan comments ask
+ * for an amended plan, comments before a plan exists ask for a new proposal.
+ */
+export function commentMessage(taskId: string, comments: readonly PlanComment[], hasPlan: boolean): string {
+  const noun = comments.length === 1 ? "a comment" : `${comments.length} comments`;
+  const target = hasPlan ? "the approved plan" : "the proposal";
+  const lines = comments.map((comment) => `- ${comment.text.replace(/\s*\n\s*/g, " ")}`);
+  const ask = hasPlan
+    ? "Amend the plan to address them: call orchestrate action=plan with the full revised plan (it replaces the current one and marks these comments addressed), then continue the work. If a comment needs no change, say why."
+    : "Take them into account: revise the proposal and call orchestrate action=propose again.";
+  return [`The user left ${noun} on ${target} of ${taskId} from the lobby:`, ...lines, "", ask].join("\n");
+}