@a-t-h-i/bot-lobby 0.6.49 → 0.6.50

package/src/pi/fresh-context.ts

@@ -13,7 +13,7 @@
  * already run as pi processes of their own, each with its own context, and
  * are not touched here.
  */
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext, SessionBeforeCompactEvent } from "@earendil-works/pi-coding-agent";
 import { relative } from "node:path";
 import { TERMINAL_STATES, type Task } from "../schemas/task.ts";
 import { peekTasks, taskDirFor } from "../state/persistence.ts";
@@ -124,11 +124,13 @@ export function registerFreshContext(pi: ExtensionAPI, configDir: string): void
   // It may have ended while the oracle was idle (abandoned or archived from the lobby, finished in another window).
   pi.on("before_agent_start", (_event, ctx) => void closeEndedTask(pi, ctx, configDir));
   // Compacting a conversation the next request drops anyway would only cost a model call.
-  pi.on("session_before_compact", (event) => {
-    if (event.reason === "manual" || !freshContextOn()) return undefined;
-    const last = contextMarks(event.branchEntries).at(-1);
-    if (!last) return undefined;
-    const since = event.branchEntries.some((entry) => entry.type === "message" && Date.parse(entry.timestamp) >= last.at);
-    return since ? undefined : { cancel: true };
-  });
+  pi.on("session_before_compact", (event) => (staleCompaction(event) ? { cancel: true } : undefined));
+}
+
+/** An automatic compaction of the oracle's conversation from before its latest boundary, which the next request drops anyway. */
+export function staleCompaction(event: Pick<SessionBeforeCompactEvent, "reason" | "branchEntries">): boolean {
+  if (isSubagentProcess() || event.reason === "manual" || !freshContextOn()) return false;
+  const last = contextMarks(event.branchEntries).at(-1);
+  if (!last) return false;
+  return !event.branchEntries.some((entry) => entry.type === "message" && Date.parse(entry.timestamp) >= last.at);
 }

package/src/pi/plan-checklist.ts

@@ -18,7 +18,7 @@ const TOP_LEVEL_BULLET = /^()([*-])\s+(.*\S)\s*$/;
 const STEP_HEADING = /^\s*(?:#{1,6}\s+)?(?:\*\*)?\s*(?:step|phase|stage)\s+#?\d+\s*(?:\*\*)?\s*[:.)\u2014\u2013-]\s*(?:\*\*)?\s*(.*?)\s*(?:\*\*)?\s*$/i;
 const MIN_STEP_HEADINGS = 2;
 
-export type PlanStepStatus = "done" | "current" | "pending";
+export type PlanStepStatus = "done" | "current" | "pending" | "skipped";
 
 export interface PlanStep {
   text: string;
@@ -355,8 +355,8 @@ function byStart(runs: readonly AgentRun[]): AgentRun[] {
  * grows and a failure can never tick one off. The latest worker run's own target
  * is reported separately so a running or failed step reads current.
  */
-function replaySteps(steps: readonly string[], runs: readonly AgentRun[]): { completed: number; latest: number } {
-  const completed = new Set<number>();
+function replaySteps(steps: readonly string[], runs: readonly AgentRun[], skipped: ReadonlySet<number>): { completed: Set<number>; latest: number } {
+  const completed = new Set<number>(skipped);
   const latestRun = latestWorkerRun(runs);
   let latest = -1;
   for (const run of byStart(runs)) {
@@ -367,27 +367,43 @@ function replaySteps(steps: readonly string[], runs: readonly AgentRun[]): { com
     const target = matched >= 0 ? matched : nextOpenStep(steps, completed);
     if (target >= 0) markThrough(completed, target);
   }
-  return { completed: completed.size, latest };
+  return { completed, latest };
+}
+
+/**
+ * The plan steps the user skipped, as indexes: each skip names its step by
+ * text, so a skip whose step a revised plan no longer lists drops out.
+ */
+export function skippedIndexes(steps: readonly string[], skipped: readonly { text: string }[] | undefined): Set<number> {
+  const found = new Set<number>();
+  if (!skipped?.length) return found;
+  const wanted = new Set(skipped.map((entry) => normalize(entry.text)));
+  steps.forEach((text, index) => { if (wanted.has(normalize(text))) found.add(index); });
+  return found;
 }
 
 /** One-entry memo: the panel asks for the same checklist several times per frame. */
-let checklistMemo: { plan: string; runs: readonly AgentRun[]; steps: PlanStep[] } | undefined;
+let checklistMemo: { plan: string; runs: readonly AgentRun[]; skipped: readonly { text: string }[] | undefined; steps: PlanStep[] } | undefined;
 
 /**
  * Done/current/pending per plan step. A succeeded run completes its step, so the
  * next step becomes current (and the last step reads done); running, failed,
  * cancelled and timeout runs keep it current. Progress is monotonic: steps
  * already completed by successful worker runs stay done, and a later call that
- * names an earlier step can never tick it back. Memoized on the exact plan text
- * and runs array, so callers must not mutate either.
+ * names an earlier step can never tick it back. A step the user skipped reads
+ * skipped and counts as behind the work: the next open step becomes current.
+ * Memoized on the exact plan text, runs and skips, so callers must not mutate them.
  */
-export function planChecklist(plan: string, runs: readonly AgentRun[]): PlanStep[] {
-  if (checklistMemo && checklistMemo.plan === plan && checklistMemo.runs === runs) return checklistMemo.steps;
+export function planChecklist(plan: string, runs: readonly AgentRun[], skips?: readonly { text: string }[]): PlanStep[] {
+  if (checklistMemo && checklistMemo.plan === plan && checklistMemo.runs === runs && checklistMemo.skipped === skips) return checklistMemo.steps;
   const texts = planSteps(plan);
-  const replay = replaySteps(texts, runs);
-  const current = Math.max(replay.completed, replay.latest);
-  const steps = texts.map((text, index) => ({ text, status: stepStatus(index, current) }));
-  checklistMemo = { plan, runs, steps };
+  const skipped = skippedIndexes(texts, skips);
+  const replay = replaySteps(texts, runs, skipped);
+  const open = nextOpenStep(texts, replay.completed);
+  let current = Math.max(open < 0 ? texts.length : open, replay.latest);
+  while (skipped.has(current)) current += 1;
+  const steps = texts.map((text, index) => ({ text, status: skipped.has(index) ? "skipped" as const : stepStatus(index, current) }));
+  checklistMemo = { plan, runs, skipped: skips, steps };
   return steps;
 }
 
@@ -420,11 +436,11 @@ export function runSteps(steps: readonly string[], instruction: string | undefin
  * step it works on (a `Steps 2-4` run toward all three), and its success
  * completes them, so a later run that names no step goes to the next one.
  */
-export function stepWork(steps: readonly string[], runs: readonly AgentRun[], now = Date.now()): StepWork[] {
+export function stepWork(steps: readonly string[], runs: readonly AgentRun[], now = Date.now(), skipped: ReadonlySet<number> = new Set()): StepWork[] {
   const work: StepWork[] = steps.map(() => ({ ms: 0, active: false, activeAgentCount: 0, runIds: [] }));
   const assigned = new Map<string, number[]>();
   const counted = new Set<string>();
-  const completed = new Set<number>();
+  const completed = new Set<number>(skipped);
   for (const run of byStart(runs)) {
     if (run.role !== "worker") continue;
     if (counted.has(run.runId)) continue;
@@ -449,3 +465,19 @@ export function stepWork(steps: readonly string[], runs: readonly AgentRun[], no
   }
   return work;
 }
+
+/**
+ * What the oracle reads of the steps the user skipped: each by its number in
+ * the plan, with the user's reason, and that none of them is to be built.
+ * Empty when nothing is skipped (or a revised plan no longer lists the step).
+ */
+export function skippedStepsNote(plan: string | undefined, skips: readonly { text: string; reason: string }[] | undefined): string {
+  if (!plan || !skips?.length) return "";
+  const steps = planSteps(plan);
+  const lines = skips.flatMap((skip) => {
+    const index = steps.findIndex((text) => normalize(text) === normalize(skip.text));
+    return index < 0 ? [] : [`- Step ${index + 1}: ${skip.text} (reason: ${skip.reason})`];
+  });
+  if (lines.length === 0) return "";
+  return `Steps the user skipped (do not delegate, build or review them; the task may complete without them, and the next open step carries on):\n${lines.join("\n")}`;
+}

package/src/schemas/task.ts

@@ -207,6 +207,18 @@ export interface TaskGit {
   path?: string;
 }
 
+/** A plan step the user chose to skip, with the reason they gave; matched to the plan by its text. */
+export interface SkippedStep {
+  /** The step's text as the plan lists it. */
+  text: string;
+  /** Why the user skipped it, in their words (required). */
+  reason: string;
+  at: string;
+}
+
+/** Longest skip reason kept. */
+export const MAX_SKIP_REASON = 1000;
+
 export interface PhaseTiming {
   phase: TaskState;
   elapsedMs: number;
@@ -265,6 +277,8 @@ export interface Task {
   qaRisk?: QaRiskAssessment;
   /** Set only by the user: the work is accepted with the lint errors it has, so the task may complete. */
   lintWaiver?: { at: string };
+  /** Plan steps the user skipped, each with their reason; the oracle is told not to work on them. */
+  skippedSteps?: SkippedStep[];
 }
 
 export function createTask(

package/src/state/persistence.ts

@@ -104,7 +104,7 @@ export function saveTask(root: string, configDir: string, task: Task): void {
   rememberTiming(task);
 }
 
-/** Explicit user waivers and resolved approvals must survive an in-flight worker's snapshot. */
+/** Explicit user waivers, skipped steps and resolved approvals must survive an in-flight worker's snapshot. */
 function preserveUserInterventions(task: Task, latest: Task): void {
   const newlyWaived = !task.qaWaiver && latest.qaWaiver;
   task.qaWaiver ??= latest.qaWaiver;
@@ -117,6 +117,9 @@ function preserveUserInterventions(task: Task, latest: Task): void {
     const resolved = latest.approvals.find((entry) => entry.id === approval.id && entry.status !== "pending");
     if (approval.status === "pending" && resolved) Object.assign(approval, resolved);
   }
+  const skipped = new Set((task.skippedSteps ?? []).map((entry) => entry.text));
+  const newSkips = (latest.skippedSteps ?? []).filter((entry) => !skipped.has(entry.text));
+  if (newSkips.length > 0) task.skippedSteps = [...(task.skippedSteps ?? []), ...newSkips];
   const keys = new Set(task.decisions.map((entry) => JSON.stringify(entry)));
   task.decisions.push(...latest.decisions.filter((entry) => !keys.has(JSON.stringify(entry))));
 }

package/src/webui/api/index.ts

@@ -15,13 +15,15 @@ import { lobbyAbort, lobbyHistory, lobbySend, lobbySnapshot } from "./lobby.ts";
 import { promptsAnswer, promptsDismiss, promptsList } from "./prompts.ts";
 import { plannerAnswer, plannerCommentLine, plannerGet, plannerNew, plannerRetry, plannerSend, plannerEditMessage, plannerToggleSeat, plannerSave, plannerPrevious, plannerPreviousArchive, plannerPreviousDelete, plannerPreviousGet, plannerPreviousOpen } from "./planner.ts";
 import { quickfixCancel, quickfixList, quickfixMovedToTask, quickfixRunAnyway, quickfixSubmit } from "./quickfix.ts";
-import { tasksArchive, tasksArchived, tasksAuto, tasksComment, tasksComments, tasksDelete, tasksEditComment, tasksGet, tasksList, tasksMessage, tasksRestore, tasksOpen, tasksResume, tasksDeliveryReview, tasksDeliveryDefer, tasksDeliver, tasksAccept, tasksForceClose, tasksResolveApproval } from "./tasks.ts";
+import { tasksArchive, tasksArchived, tasksAuto, tasksComment, tasksComments, tasksDelete, tasksEditComment, tasksGet, tasksList, tasksMessage, tasksRestore, tasksOpen, tasksResume, tasksDeliveryReview, tasksDeliveryDefer, tasksDeliver, tasksAccept, tasksSkipStep, tasksForceClose, tasksResolveApproval } from "./tasks.ts";
 import { knowledgeAdd, knowledgeAsk, knowledgeComment, knowledgeEdit, knowledgeFiles, knowledgeOpen, knowledgeRemove, knowledgeReplaceFile, knowledgeUnnote } from "./knowledge.ts";
 import { plansDiscard, plansGet, plansStart } from "./plans.ts";
 import { gitCancelReview, gitJev, gitPull, gitPulls, gitReview } from "./git.ts";
 import { issuesCreate, issuesGet, issuesList } from "./issues.ts";
-import { sessionsAnswer, sessionsChat, sessionsList, sessionsMessage, sessionsStart, sessionsStop, sessionsSwitch } from "./sessions.ts";
+import { sessionsAnswer, sessionsArchive, sessionsChat, sessionsList, sessionsMessage, sessionsRename, sessionsStart, sessionsStop, sessionsSwitch } from "./sessions.ts";
 import { settingsGet, settingsLinters, settingsSet } from "./settings.ts";
+import { terminalClose, terminalInput, terminalList, terminalOpen, terminalResize } from "./terminal.ts";
+import { MAX_INPUT_CHARS } from "../terminal.ts";
 import { themesChoose, themesGet, themesRemove, themesRename, themesSave } from "./themes.ts";
 import { noticeText, pushNotice } from "../notices.ts";
 
@@ -134,6 +136,10 @@ function buildRoutes(): Record<string, Route> {
     schema: Type.Object({ taskId: TaskId }, { additionalProperties: false }),
     run: (body, ctx) => tasksAccept(body as { taskId: string }, ctx),
   };
+  routes["tasks.skipStep"] = {
+    schema: Type.Object({ taskId: TaskId, step: Type.Integer({ minimum: 0, maximum: 49 }), text: Type.String({ minLength: 1, maxLength: 20_000 }), reason: Type.String({ minLength: 1, maxLength: 1000 }) }, { additionalProperties: false }),
+    run: (body, ctx) => tasksSkipStep(body as Parameters<typeof tasksSkipStep>[0], ctx),
+  };
   routes["tasks.forceClose"] = {
     schema: Type.Object({ taskId: TaskId, title: Type.String({ maxLength: 20_000 }) }, { additionalProperties: false }),
     run: (body, ctx) => tasksForceClose(body as { taskId: string; title: string }, ctx),
@@ -219,6 +225,34 @@ function buildRoutes(): Record<string, Route> {
     schema: Type.Object({ key: Type.Optional(TaskId), sessionId: Type.Optional(TaskId), claimTaskId: Type.Optional(TaskId) }, { additionalProperties: false }),
     run: (body, ctx) => sessionsSwitch(body as { key?: string; sessionId?: string; claimTaskId?: string }, ctx),
   };
+  const TerminalId = Type.String({ minLength: 1, maxLength: 40 });
+  const Cols = Type.Integer({ minimum: 2, maximum: 500 });
+  const Rows = Type.Integer({ minimum: 2, maximum: 300 });
+  routes["terminal.list"] = { schema: Empty, run: () => terminalList() };
+  routes["terminal.open"] = {
+    schema: Type.Object({ cols: Cols, rows: Rows }, { additionalProperties: false }),
+    run: (body, ctx) => terminalOpen(body as { cols: number; rows: number }, ctx),
+  };
+  routes["terminal.input"] = {
+    schema: Type.Object({ id: TerminalId, data: Type.String({ minLength: 1, maxLength: MAX_INPUT_CHARS }) }, { additionalProperties: false }),
+    run: (body) => terminalInput(body as { id: string; data: string }),
+  };
+  routes["terminal.resize"] = {
+    schema: Type.Object({ id: TerminalId, cols: Cols, rows: Rows }, { additionalProperties: false }),
+    run: (body) => terminalResize(body as { id: string; cols: number; rows: number }),
+  };
+  routes["terminal.close"] = {
+    schema: Type.Object({ id: TerminalId }, { additionalProperties: false }),
+    run: (body) => terminalClose(body as { id: string }),
+  };
+  routes["sessions.rename"] = {
+    schema: Type.Object({ key: Type.Optional(TaskId), name: Type.String({ minLength: 1, maxLength: 500 }) }, { additionalProperties: false }),
+    run: (body, ctx) => sessionsRename(body as { key?: string; name: string }, ctx),
+  };
+  routes["sessions.archive"] = {
+    schema: Type.Object({ key: TaskId, archived: Type.Optional(Type.Boolean()) }, { additionalProperties: false }),
+    run: (body, ctx) => sessionsArchive(body as { key: string; archived?: boolean }, ctx),
+  };
   routes["sessions.answer"] = {
     schema: Type.Object({ key: TaskId, dialogId: TaskId, answer: DialogAnswer }, { additionalProperties: false }),
     run: (body, ctx) => sessionsAnswer(body as { key: string; dialogId: string; answer: { value: string } | { confirmed: boolean } | { cancelled: true } }, ctx),

package/src/webui/api/lobby.ts

@@ -22,7 +22,7 @@ function planFacts(task: Task, work: WorkProjection | undefined): Pick<SnapshotT
   const active = steps.filter((step) => step.active);
   const current = steps.find((step) => step.status === "current");
   return {
-    progress: { done: steps.filter((step) => step.status === "done").length, total: steps.length },
+    progress: { done: steps.filter((step) => step.status === "done" || step.status === "skipped").length, total: steps.length },
     ...(current ? { currentStep: current.text } : {}),
     ...(active.length > 0 ? { activeSteps: active.map((step) => ({ text: step.text, workedMs: step.workedMs, activeAgentCount: step.activeAgentCount, runIds: step.runIds })) } : {}),
     ...clock,

package/src/webui/api/plan-facts.ts

@@ -4,7 +4,7 @@
  * right now and the work time. Kept here (not via `persistedRuns`) so the
  * server never loads the TUI.
  */
-import { planChecklist, planSteps, stepWork, type PlanStep } from "../../pi/plan-checklist.ts";
+import { planChecklist, planSteps, skippedIndexes, stepWork, type PlanStep } from "../../pi/plan-checklist.ts";
 import type { AgentRun } from "../../schemas/findings.ts";
 import type { Task } from "../../schemas/task.ts";
 import type { WorkProjection } from "../../state/work-time.ts";
@@ -44,6 +44,8 @@ export interface StepView {
   agents: StepAgent[];
   /** Worker time on the step, in ms. */
   workedMs: number;
+  /** The user skipped it: why, and when. */
+  skip?: { reason: string; at: string };
 }
 
 export interface StepAgent {
@@ -62,8 +64,10 @@ export interface StepAgent {
 export function stepViews(task: Task, work: WorkProjection | undefined, now = Date.now()): StepView[] {
   if (!task.plan) return [];
   const runs = [...persistedTaskRuns(task), ...activeRuns(task, work)];
-  const checklist = planChecklist(task.plan, runs);
-  const times = stepWork(planSteps(task.plan), runs, now);
+  const texts = planSteps(task.plan);
+  const checklist = planChecklist(task.plan, runs, task.skippedSteps);
+  const times = stepWork(texts, runs, now, skippedIndexes(texts, task.skippedSteps));
+  const skipOf = (text: string) => task.skippedSteps?.find((entry) => skippedIndexes([text], [entry]).size > 0);
   const byId = new Map(runs.map((run) => [run.runId, run]));
   return checklist.map((step, index) => {
     const time = times[index] ?? { ms: 0, active: false, activeAgentCount: 0, runIds: [] };
@@ -71,6 +75,7 @@ export function stepViews(task: Task, work: WorkProjection | undefined, now = Da
       const run = byId.get(runId);
       return run ? [{ runId, ...(run.parentRunId ? { parentRunId: run.parentRunId } : {}), domain: run.domain, instruction: (run.instruction ?? "").split("\n")[0]!.trim(), startedAt: run.startedAt }] : [];
     });
-    return { text: step.text, status: time.active ? "current" : step.status, active: time.active, activeAgentCount: time.activeAgentCount, runIds: time.runIds, agents, workedMs: Math.round(time.ms) };
+    const skip = step.status === "skipped" ? skipOf(step.text) : undefined;
+    return { text: step.text, status: time.active && !skip ? "current" : step.status, active: time.active && !skip, activeAgentCount: time.activeAgentCount, runIds: time.runIds, agents, workedMs: Math.round(time.ms), ...(skip ? { skip: { reason: skip.reason, at: skip.at } } : {}) };
   });
 }

package/src/webui/api/sessions.ts

@@ -114,3 +114,24 @@ export function sessionsAnswer(body: { key: string; dialogId: string; answer: Di
   session!.answer(body.dialogId, body.answer);
   return { notice: "answer sent" };
 }
+
+/** Rename this window's session (no key) or a background one. */
+export function sessionsRename(body: { key?: string; name: string }, ctx: ApiContext): { notice: string } {
+  if (!ctx.service.renameSession) fail(501, "unsupported", "this lobby cannot rename sessions");
+  try {
+    return { notice: ctx.service.renameSession!(body.key, body.name) };
+  } catch (error) {
+    fail(/^no session/.test((error as Error).message) ? 404 : 400, /^no session/.test((error as Error).message) ? "not_found" : "bad_request", (error as Error).message);
+  }
+}
+
+/** Put an ended background session away from the list (`archived` true, the default), or bring it back. */
+export function sessionsArchive(body: { key: string; archived?: boolean }, ctx: ApiContext): { notice: string } {
+  if (!ctx.service.archiveSession) fail(501, "unsupported", "this lobby cannot archive sessions");
+  try {
+    return { notice: ctx.service.archiveSession!(body.key, body.archived ?? true) };
+  } catch (error) {
+    const message = (error as Error).message;
+    fail(/^no /.test(message) ? 404 : 409, /^no /.test(message) ? "not_found" : "conflict", message);
+  }
+}

package/src/webui/api/tasks.ts

@@ -70,7 +70,7 @@ function checkOf(task: Task): TaskRow["check"] {
 function progressOf(task: Task, work: WorkProjection | undefined, now: number): TaskRow["progress"] {
   const steps = stepViews(task, work, now);
   if (steps.length === 0) return undefined;
-  return { done: steps.filter((step) => step.status === "done").length, total: steps.length };
+  return { done: steps.filter((step) => step.status === "done" || step.status === "skipped").length, total: steps.length };
 }
 
 /** The work clock as the page shows it; a finished task's no longer counts. */
@@ -302,6 +302,15 @@ export async function tasksAccept(body: { taskId: string }, ctx: ApiContext): Pr
   return ctx.service.acceptTask(body.taskId);
 }
 
+/** Skip a plan step with the user's reason; refused once the plan changed under the page. */
+export async function tasksSkipStep(body: { taskId: string; step: number; text: string; reason: string }, ctx: ApiContext): Promise<{ notice: string }> {
+  const task = interventionTask(body.taskId, ctx);
+  if (!task.plan) fail(400, "bad_request", "this task has no plan yet");
+  if (!body.reason.trim()) fail(400, "bad_request", "say why you are skipping this step");
+  if (!ctx.service.skipTaskStep) fail(400, "bad_request", "skipping steps is unavailable");
+  return ctx.service.skipTaskStep(body.taskId, body.step, body.text, body.reason);
+}
+
 export async function tasksForceClose(body: { taskId: string; title: string }, ctx: ApiContext): Promise<{ notice: string }> {
   const task = interventionTask(body.taskId, ctx);
   if (body.title !== task.title) fail(400, "bad_request", "the title must match exactly");
@@ -337,6 +346,7 @@ export function tasksGet(body: { taskId: string }, ctx: ApiContext): TaskDetail
   const details = found.plan ? planDetails(found.plan) : undefined;
   return {
     canAccept: Boolean(active && ctx.service.acceptTask) && acceptable(found),
+    canSkip: Boolean(active && ctx.service.skipTaskStep && found.plan) && !TERMINAL_STATES.includes(found.state),
     canForceClose: Boolean(active && ctx.service.forceCloseTask) && !TERMINAL_STATES.includes(found.state) && (ctx.service.canForceCloseTask?.(found.id) ?? true),
     timing: projectPhaseTiming(found, new Date(now).toISOString()),
     ...(clock ? { work: clock } : {}),
@@ -348,6 +358,7 @@ export function tasksGet(body: { taskId: string }, ctx: ApiContext): TaskDetail
     steps: stepViews(found, work, now).map((step) => ({
       text: step.text,
       status: step.status === "pending" ? "open" : step.status,
+      ...(step.skip ? { skip: step.skip } : {}),
       ...(step.active ? { active: true, workedMs: step.workedMs, activeAgentCount: step.activeAgentCount, agents: step.agents } : {}),
     })),
     amendments: [...found.amendments],

package/src/webui/api/terminal.ts

@@ -0,0 +1,42 @@
+/** `terminal.*`: shells in the project's folder for the page's terminal drawer (see `../terminal.ts`). */
+import { fail, type ApiContext } from "./index.ts";
+import { terminalBackend, terminals, TerminalError } from "../terminal.ts";
+import type { TerminalInfo } from "../protocol.ts";
+
+function guard<T>(run: () => T): T {
+  try {
+    return run();
+  } catch (error) {
+    if (error instanceof TerminalError) fail(error.missing ? 404 : 409, error.missing ? "not_found" : "conflict", error.message);
+    throw error;
+  }
+}
+
+export async function terminalList(): Promise<{ available: boolean; reason?: string; terminals: TerminalInfo[] }> {
+  const backend = await terminalBackend();
+  return { available: backend.kind !== "none", ...(backend.kind === "none" ? { reason: backend.reason } : {}), terminals: terminals.list() };
+}
+
+export async function terminalOpen(body: { cols: number; rows: number }, ctx: ApiContext): Promise<TerminalInfo> {
+  try {
+    return await terminals.open(ctx.service.projectRoot?.() ?? process.cwd(), body.cols, body.rows);
+  } catch (error) {
+    if (error instanceof TerminalError) fail(409, "conflict", error.message);
+    throw error;
+  }
+}
+
+export function terminalInput(body: { id: string; data: string }): Record<string, never> {
+  guard(() => terminals.input(body.id, body.data));
+  return {};
+}
+
+export function terminalResize(body: { id: string; cols: number; rows: number }): Record<string, never> {
+  guard(() => terminals.resize(body.id, body.cols, body.rows));
+  return {};
+}
+
+export function terminalClose(body: { id: string }): Record<string, never> {
+  guard(() => terminals.close(body.id));
+  return {};
+}

package/src/webui/dev/fake-service.ts

@@ -9,6 +9,7 @@ import { LobbyFeed } from "../../lobby/feed.ts";
 import { promptHub } from "../../lobby/prompt-hub.ts";
 import { lobbyTopics } from "../../lobby/topics.ts";
 import type { BackgroundSession, DialogAnswer, SessionDialog } from "../../lobby/sessions.ts";
+import { cleanSessionName } from "../../lobby/sessions.ts";
 import type { PlanComment } from "../../state/comments.ts";
 import type { LobbyService } from "../../lobby/host.ts";
 import { loadScenario, type ScenarioFixture } from "./fixtures.ts";
@@ -280,11 +281,16 @@ function fakeBackground(entry: NonNullable<ScenarioFixture["backgroundSessions"]
     stop() {
       status = "exited";
       dialogs.length = 0;
+      lobbyTopics.bump("sessions");
     },
     answer(id: string, _answer: DialogAnswer) {
       const index = dialogs.findIndex((dialog) => dialog.id === id);
       if (index >= 0) dialogs.splice(index, 1);
     },
+    rename(name: string) {
+      session.name = name;
+      lobbyTopics.bump("sessions");
+    },
   };
   return session as unknown as BackgroundSession;
 }
@@ -335,6 +341,8 @@ export function createFixtureService(name: string, feed = new LobbyFeed()): Lobb
   const auto = new Set(fixture.autoTasks ?? []);
   const comments = new Map<string, Array<Record<string, unknown>>>(Object.entries(fixture.taskComments ?? {}));
   const backgrounds = (fixture.backgroundSessions ?? []).map(fakeBackground);
+  const archivedBackgrounds: BackgroundSession[] = [];
+  let sessionName = fixture.status.sessionName;
   let planning = fakePlanner(fixture.mockPlanner ?? defaultPlanner());
   let config: BotLobbyConfig = resolveConfig(fixture.settings?.config ?? {});
   const models = fixture.settings?.models ?? DEFAULT_MODELS;
@@ -391,7 +399,7 @@ export function createFixtureService(name: string, feed = new LobbyFeed()): Lobb
   let commentSeq = 0;
   const service = {
     sessionId: () => fixture.status.sessionId,
-    sessionName: () => fixture.status.sessionName,
+    sessionName: () => sessionName,
     masterBusy: () => fixture.status.busy,
     config: () => config,
     linters: () => fixture.settings?.linters ?? [{ tool: "ESLint", folder: "", installed: true }, { tool: "Ruff", folder: "services/api", installed: false }],
@@ -481,6 +489,15 @@ export function createFixtureService(name: string, feed = new LobbyFeed()): Lobb
     },
     sendToTask: (taskId: string, _text: string) => (tasks.some((task) => (task as { id: string }).id === taskId) ? `sent — the session driving ${taskId} passes it to its oracle` : `no task ${taskId}`),
     sendToSession: (_sessionId: string, _text: string) => "sent — that session passes it to its oracle within a few seconds",
+    skipTaskStep: async (taskId: string, step: number, text: string, reason: string) => {
+      const task = tasks.find((entry) => (entry as { id: string }).id === taskId) as { id: string; skippedSteps?: Array<{ text: string; reason: string; at: string }>; decisions?: Array<{ domain: string; text: string; createdAt: string }> } | undefined;
+      if (!task) throw new Error(`no task ${taskId}`);
+      const at = new Date().toISOString();
+      task.skippedSteps = [...(task.skippedSteps ?? []), { text, reason: reason.trim(), at }];
+      task.decisions = [...(task.decisions ?? []), { domain: "master", text: `The user skipped step ${step + 1} ("${text}") from the Tasks screen. Reason: ${reason.trim()}`, createdAt: at }];
+      lobbyTopics.bump("tasks");
+      return { notice: `step ${step + 1} skipped; the oracle has been told` };
+    },
     resumeTask: async (taskId: string) => {
       const task = tasks.find((entry) => (entry as { id: string }).id === taskId) as { id: string; title: string; paused?: boolean; ownerSessionId?: string } | undefined;
       if (!task) return { notice: `no task ${taskId}` };
@@ -500,6 +517,30 @@ export function createFixtureService(name: string, feed = new LobbyFeed()): Lobb
       return { notice: `resumed ${taskId} in a background session`, key: session.key };
     },
     sessions: () => [...backgrounds],
+    renameSession: (key: string | undefined, name: string) => {
+      const clean = cleanSessionName(name);
+      if (!key) {
+        sessionName = clean;
+        lobbyTopics.bump("status");
+        lobbyTopics.bump("sessions");
+        return `renamed this window to ${clean}`;
+      }
+      const session = backgrounds.find((entry) => entry.key === key);
+      if (!session) throw new Error(`no session ${key}`);
+      session.rename(clean);
+      return `renamed ${key} to ${clean}`;
+    },
+    archiveSession: (key: string, archived: boolean) => {
+      const from = archived ? backgrounds : archivedBackgrounds;
+      const index = from.findIndex((entry) => entry.key === key);
+      if (index < 0) throw new Error(archived ? `no session ${key} to archive` : `no archived session ${key}`);
+      const session = from[index]!;
+      if (session.alive) throw new Error(`${session.name} is still running: stop it before archiving it`);
+      from.splice(index, 1);
+      (archived ? archivedBackgrounds : backgrounds).push(session);
+      lobbyTopics.bump("sessions");
+      return archived ? `archived ${session.name}` : `brought back ${session.name}`;
+    },
     startSession: (start: { request?: string; plan?: { id: string; title: string }; auto?: boolean }) => {
       const key = `S${backgrounds.length + 1}`;
       const session = fakeBackground({ key, name: start.plan?.title ?? start.request?.trim().slice(0, 40) ?? "mock session", status: "starting", ...(start.plan ? { planId: start.plan.id } : {}) });

package/src/webui/protocol.ts

@@ -218,6 +218,23 @@ export type StreamEvent =
   | { type: "reply"; text: string }
   | { type: "notice"; text: string; level: NoticeLevel };
 
+/** A terminal the server runs (`terminal.*`): a shell in the project's folder. */
+export interface TerminalInfo {
+  id: string;
+  title: string;
+  cwd: string;
+  alive: boolean;
+  /** The shell's exit code, once it ended. */
+  exitCode?: number;
+  startedAt: number;
+}
+
+/** One message on a terminal's stream (`GET /api/terminal.stream?id=…`). */
+export type TerminalStreamEvent =
+  | { type: "reset"; data: string; alive: boolean; code?: number }
+  | { type: "data"; data: string }
+  | { type: "exit"; code?: number };
+
 /** The planning session as `planner.get` describes it. */
 export interface PlannerSnapshot {
   /** Seats on the panel next round. */
@@ -324,6 +341,8 @@ export interface EntryRefInfo {
 /** `tasks.get`: one task read whole, in the terminal's wording. */
 export interface TaskDetail {
   canAccept: boolean;
+  /** Open steps can be skipped (the user gives a reason). */
+  canSkip: boolean;
   canForceClose: boolean;
   timing?: TimingProjection;
   delivery?: Delivery;
@@ -337,9 +356,9 @@ export interface TaskDetail {
   planDetails?: string;
   /**
    * The plan as a checklist, in order; `current` is the step under way, `active` the steps a worker is on right now,
-   * each with its worker time (ms, as of the reply).
+   * each with its worker time (ms, as of the reply); `skip` carries the reason the user gave for skipping a step.
    */
-  steps: Array<{ text: string; status: "done" | "current" | "open"; active?: boolean; workedMs?: number; activeAgentCount?: number; agents?: StepAgentInfo[] }>;
+  steps: Array<{ text: string; status: "done" | "current" | "open" | "skipped"; skip?: { reason: string; at: string }; active?: boolean; workedMs?: number; activeAgentCount?: number; agents?: StepAgentInfo[] }>;
   /** How long the task's agents have worked on it, idle time left out (ms, as of the reply); `running` while they work. */
   work?: WorkClock;
   amendments: string[];
@@ -520,6 +539,7 @@ export interface Api {
   "tasks.open": { request: { taskId: string }; result: { sessionId?: string; key?: string; notice?: string } };
   "tasks.resume": { request: { taskId: string }; result: { notice: string; key?: string } };
   "tasks.accept": { request: { taskId: string }; result: { notice: string } };
+  "tasks.skipStep": { request: { taskId: string; step: number; text: string; reason: string }; result: { notice: string } };
   "tasks.forceClose": { request: { taskId: string; title: string }; result: { notice: string } };
   "tasks.resolveApproval": { request: { taskId: string; approvalId: string; decision: "approved" | "rejected"; note?: string }; result: { notice: string } };
   "tasks.deliveryReview": { request: { taskId: string }; result: { delivery: Delivery } };
@@ -535,6 +555,13 @@ export interface Api {
   "sessions.message": { request: { key?: string; sessionId?: string; text: string; attachments?: string[] }; result: { notice?: string } };
   "sessions.switch": { request: { key?: string; sessionId?: string; claimTaskId?: string }; result: { notice: string } };
   "sessions.answer": { request: { key: string; dialogId: string; answer: DialogAnswer }; result: { notice: string } };
+  "sessions.rename": { request: { key?: string; name: string }; result: { notice: string } };
+  "sessions.archive": { request: { key: string; archived?: boolean }; result: { notice: string } };
+  "terminal.list": { request: Record<string, never>; result: { available: boolean; reason?: string; terminals: TerminalInfo[] } };
+  "terminal.open": { request: { cols: number; rows: number }; result: TerminalInfo };
+  "terminal.input": { request: { id: string; data: string }; result: Record<string, never> };
+  "terminal.resize": { request: { id: string; cols: number; rows: number }; result: Record<string, never> };
+  "terminal.close": { request: { id: string }; result: Record<string, never> };
   "prompts.list": { request: Record<string, never>; result: { prompts: WebPrompt[] } };
   "prompts.answer": { request: { id: string; answer: unknown }; result: { notice?: string } };
   "prompts.dismiss": { request: { id: string }; result: Record<string, never> };

package/src/webui/server.ts

@@ -27,7 +27,8 @@ import {
   sessionCookie,
   sessionValue,
 } from "./auth.ts";
-import { callName, HttpError, routeApiCall, sendError, sendJson } from "./api/index.ts";
+import { applyBaseHeaders, callName, HttpError, routeApiCall, sendError, sendJson } from "./api/index.ts";
+import { terminals } from "./terminal.ts";
 import { distDir, serveStatic } from "./static.ts";
 import { EventHub } from "./events.ts";
 import { servePreview } from "./files.ts";
@@ -292,6 +293,19 @@ async function route(req: IncomingMessage, res: ServerResponse, state: RouteStat
     openStream(req, res, url, state);
     return;
   }
+  if (url.pathname === "/api/terminal.stream") {
+    if (req.method !== "GET") {
+      sendError(res, "unsupported", "only GET", 405);
+      return;
+    }
+    if (!isSignedIn(req.headers.cookie, state.session)) {
+      sendError(res, "unauthorized", "open the link Pi printed", 401);
+      return;
+    }
+    applyBaseHeaders(res);
+    if (!terminals.stream(req, res, url.searchParams.get("id") ?? "")) sendError(res, "not_found", "no such terminal", 404);
+    return;
+  }
   await routeApi(req, res, url, state);
 }
 
@@ -388,6 +402,7 @@ export async function startWebServer(options: WebServerOptions): Promise<WebServ
       return `http://127.0.0.1:${state.port}/#token=${state.link}`;
     },
     close: async () => {
+      terminals.closeAll();
       state.opener!.close();
       state.registry!.close();
       hub.close();