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

package/src/schemas/configuration.ts

@@ -1,13 +1,24 @@
+import type { Domain, Role } from "./agent.ts";
+
 export type ModelRef = "inherit" | string;
 
 /** Thinking levels accepted by the pi CLI (`--thinking`). */
 export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
 export type ThinkingLevelName = (typeof THINKING_LEVELS)[number];
 
-/** Value meaning "use the model/thinking of the current session". */
+/**
+ * A model value meaning "not configured". The master keeps the live session;
+ * a subagent falls back to the session's model until settings pin one.
+ * Thinking never inherits: every agent runs at the level its settings name.
+ */
 const INHERIT = "inherit";
 export const INHERIT_MODEL = INHERIT;
+/** Legacy thinking sentinel; configs that still carry it migrate to `DEFAULT_THINKING`. */
 export const INHERIT_THINKING = INHERIT;
+/** Level used for a missing, legacy `inherit` or unknown thinking value. */
+export const DEFAULT_THINKING: ThinkingLevelName = "medium";
+/** Scouts are reconnaissance: always fast, never configurable. */
+export const SCOUT_THINKING: ThinkingLevelName = "low";
 
 export function isThinkingLevel(value: string): value is ThinkingLevelName {
   return (THINKING_LEVELS as readonly string[]).includes(value);
@@ -18,8 +29,26 @@ export interface AgentModelConfig {
   thinking: string;
   /** Free-form instructions layered on top of this agent's built-in prompt. */
   instructions?: string;
+  /** Time limit per run; falls back to `workflow.agentTimeoutMs`. */
+  timeoutMs?: number;
+}
+
+/** Scouts pick a model and a time limit only; their thinking is fixed at `SCOUT_THINKING`. */
+export interface ScoutConfig {
+  model: ModelRef;
+  timeoutMs: number;
 }
 
+/** Subagent kinds with their own settings entry. */
+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;
@@ -27,8 +56,16 @@ export interface WorkflowConfig {
   requireApprovalForDependencies: boolean;
   requireApprovalForArchitectureChanges: boolean;
   agentTimeoutMs: number;
-  /** Bounded retries for transient agent failures (crash/timeout), §59. */
+  /** Bounded retries for transient agent failures (crash/stall), §59. A spent deadline never retries. */
   maxAgentRetries: number;
+  /** Kill a subagent after this long without any output; 0 disables. */
+  stallTimeoutMs: number;
+  /** Silence allowed while a single tool call runs (tests, builds); 0 disables. */
+  toolStallTimeoutMs: number;
+  /** Fraction of the time limit at which an agent is asked to wrap up and report; 0 disables. */
+  wrapUpAt: number;
+  /** Workers that may run at once when the Master delegates several domains together. */
+  maxParallelWorkers: number;
 }
 
 export interface KnowledgeConfig {
@@ -38,20 +75,47 @@ 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 = {
   master: { model: INHERIT_MODEL, thinking: "high", instructions: "" },
   agents: {
-    designer: { model: INHERIT_MODEL, thinking: INHERIT_THINKING, instructions: "" },
-    backend: { model: INHERIT_MODEL, thinking: INHERIT_THINKING, instructions: "" },
-    qa: { model: INHERIT_MODEL, thinking: INHERIT_THINKING, instructions: "" },
+    designer: { model: INHERIT_MODEL, thinking: DEFAULT_THINKING, instructions: "", timeoutMs: 15 * 60 * 1000 },
+    backend: { model: INHERIT_MODEL, thinking: DEFAULT_THINKING, instructions: "", timeoutMs: 15 * 60 * 1000 },
+    qa: { model: INHERIT_MODEL, thinking: DEFAULT_THINKING, instructions: "", timeoutMs: 15 * 60 * 1000 },
   },
+  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,
@@ -60,6 +124,10 @@ export const DEFAULT_CONFIG: BotLobbyConfig = {
     requireApprovalForArchitectureChanges: true,
     agentTimeoutMs: 15 * 60 * 1000,
     maxAgentRetries: 1,
+    stallTimeoutMs: 5 * 60 * 1000,
+    toolStallTimeoutMs: 10 * 60 * 1000,
+    wrapUpAt: 0.75,
+    maxParallelWorkers: 3,
   },
   knowledge: {
     compactionThreshold: 20000,
@@ -67,25 +135,39 @@ export const DEFAULT_CONFIG: BotLobbyConfig = {
     scratchpadMaxParagraphs: 4,
     scratchpadMaxChars: 2000,
   },
+  lobby: { autoOpen: true, planningPanel: [...PANEL_MEMBERS] },
 };
 
-/** Merge one agent's override over its default, dropping an invalid thinking level but keeping the inherit sentinel. */
+function positive(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined;
+}
+
+/** Merge one agent's override over its default; legacy `inherit` or unknown thinking falls back to the default level. */
 function normalizeAgent(base: AgentModelConfig, override: Partial<AgentModelConfig> | undefined): AgentModelConfig {
   const merged = { ...base, ...(override ?? {}) };
-  const thinking = merged.thinking === INHERIT_THINKING || isThinkingLevel(merged.thinking) ? merged.thinking : base.thinking;
-  return { ...merged, thinking };
+  const thinking = isThinkingLevel(merged.thinking) ? merged.thinking : base.thinking;
+  const timeoutMs = positive(merged.timeoutMs) ?? base.timeoutMs;
+  return { ...merged, thinking, ...(timeoutMs ? { timeoutMs } : {}) };
+}
+
+/** Scouts keep a model and a time limit; any thinking value in the file is dropped. */
+function normalizeScout(override: Partial<ScoutConfig> | undefined): ScoutConfig {
+  const base = DEFAULT_CONFIG.scout;
+  return {
+    model: typeof override?.model === "string" && override.model.trim() ? override.model : base.model,
+    timeoutMs: positive(override?.timeoutMs) ?? base.timeoutMs,
+  };
 }
 
-/** Replace every agent's inherit thinking with the live session level; a missing/invalid level omits the flag. */
-export function inheritThinking(config: BotLobbyConfig, level: string | undefined): BotLobbyConfig {
-  const resolved = level && isThinkingLevel(level) ? level : "";
-  const agents = Object.fromEntries(
-    Object.entries(config.agents).map(([name, agent]) => [
-      name,
-      agent.thinking === INHERIT_THINKING ? { ...agent, thinking: resolved } : { ...agent },
-    ]),
-  ) as BotLobbyConfig["agents"];
-  return { ...config, agents };
+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. */
@@ -101,7 +183,84 @@ export function resolveConfig(partial: unknown): BotLobbyConfig {
       backend: normalizeAgent(DEFAULT_CONFIG.agents.backend, srcAgents.backend),
       qa: normalizeAgent(DEFAULT_CONFIG.agents.qa, srcAgents.qa),
     },
+    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),
   };
 }
+
+/** True when a config file still carries a thinking value for scouts, which is ignored. */
+export function hasScoutThinking(partial: unknown): boolean {
+  const scout = (partial as { scout?: Record<string, unknown> } | undefined)?.scout;
+  return Boolean(scout && typeof scout === "object" && "thinking" in scout);
+}
+
+/** What one subagent run uses: model (undefined = not configured), thinking and time limit. */
+export interface AgentProfile {
+  kind: WorkflowProfileKind;
+  model?: string;
+  thinking: string;
+  timeoutMs: number;
+  instructions?: string;
+}
+
+/** The settings entry a domain/role run draws from. */
+export function profileKind(domain: Domain, role: Role): WorkflowProfileKind {
+  if (role === "scout") return "scout";
+  if (role === "researcher") return "researcher";
+  return domain;
+}
+
+function modelOf(ref: ModelRef): string | undefined {
+  return ref === INHERIT_MODEL || !ref.trim() ? undefined : ref;
+}
+
+/**
+ * Resolve model, thinking and time limit for one run from settings alone.
+ * Workers and the QA gate use their domain's entry, scouts and researchers
+ * their own; custom instructions always come from the domain, so a designer
+ * scout still carries the designer's house rules.
+ */
+export function agentProfile(config: BotLobbyConfig, domain: Domain, role: Role): AgentProfile {
+  const kind = profileKind(domain, role);
+  const instructions = config.agents[domain].instructions;
+  const fallback = config.workflow.agentTimeoutMs;
+  if (kind === "scout") {
+    return { kind, model: modelOf(config.scout.model), thinking: SCOUT_THINKING, timeoutMs: config.scout.timeoutMs || fallback, instructions };
+  }
+  const entry = kind === "researcher" ? config.researcher : config.agents[kind];
+  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;
+
+/** The resolver a request carries, or plain settings when none was supplied (tests, headless use). */
+export function profileFor(config: BotLobbyConfig, resolver: ProfileResolver | undefined, domain: Domain, role: Role): AgentProfile {
+  return resolver ? resolver(domain, role) : agentProfile(config, domain, role);
+}

package/src/schemas/findings.ts

@@ -67,6 +67,8 @@ export interface ReviewResult {
   requiredChanges: string[];
   optionalImprovements: string[];
   pushback?: Pushback;
+  /** Set when the engine downgraded an unsupported PASS. */
+  downgraded?: string;
   raw: string;
 }
 
@@ -107,4 +109,28 @@ export interface AgentRun {
   usage?: { input: number; output: number; cost: number; turns: number };
   startedAt: string;
   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;
+  /** Epoch ms of the last streamed output; drives the "quiet" warning. */
+  lastEventAt?: number;
+  /** Transient status worth surfacing: retrying, compacting, wrapping up, waiting on a file. */
+  note?: string;
+  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. */
+  wrappedUp?: boolean;
+  /** File this worker is queued for at the file desk. */
+  waitingFor?: string;
 }

package/src/schemas/task.ts

@@ -1,4 +1,4 @@
-import type { Domain } from "./agent.ts";
+import type { Domain, Role } from "./agent.ts";
 
 export const TASK_STATES = [
   "created",
@@ -70,6 +70,30 @@ export interface WorkerRunRecord {
 /** Upper bound on persisted worker records; plans cap at 50 steps. */
 export const MAX_WORKER_RECORDS = 64;
 
+/** One finished subagent run of any role, kept for `/bot-lobby runs`. */
+export interface RunLogEntry {
+  runId: string;
+  domain: Domain;
+  role: Role;
+  status: "running" | "success" | "failed" | "cancelled" | "timeout";
+  startedAt: string;
+  finishedAt?: string;
+  model?: string;
+  thinking?: string;
+  turns?: number;
+  tools?: number;
+  input?: number;
+  output?: number;
+  cost?: number;
+  attempts?: number;
+  stalled?: boolean;
+  wrappedUp?: boolean;
+  error?: string;
+}
+
+/** Upper bound on persisted run-log entries. */
+export const MAX_RUN_LOG = 64;
+
 export interface Task {
   id: string;
   title: string;
@@ -89,6 +113,8 @@ export interface Task {
   approvals: Approval[];
   /** Worker delegations in start order; absent on tasks created before tracking. */
   workerRuns?: WorkerRunRecord[];
+  /** Recent finished runs of every role, newest last. */
+  runLog?: RunLogEntry[];
   createdAt: string;
   updatedAt: string;
   /** The pi session (ctx.sessionManager id) that owns this task; absent on legacy tasks. */

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");
+}