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

package/src/lobby/service.ts

@@ -4,7 +4,7 @@
  * the prompt hub (see ../ask/web.ts).
  */
 import { SessionManager, type ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { TERMINAL_STATES, type Task } from "../schemas/task.ts";
+import { MAX_SKIP_REASON, TERMINAL_STATES, type Task } from "../schemas/task.ts";
 import { updateBlockingRequest } from "../state/blocking-requests.ts";
 import { randomUUID } from "node:crypto";
 import { loadTask, ownedTask, peekOwnedTask, peekTasks, saveTask } from "../state/persistence.ts";
@@ -36,7 +36,8 @@ import { pendingRequest, startRequest } from "../pi/route.ts";
 import { deliverComments, setAuto } from "../pi/owner.ts";
 import { chatFromEntries, lobbyFeed, type ChatEntry } from "./feed.ts";
 import { availableClassifiers, classifier, effortFor, hintsFor } from "../classifier/instance.ts";
-import { launchPi, SessionRegistry, type BackgroundSession, type SessionLauncher } from "./sessions.ts";
+import { cleanSessionName, launchPi, SessionRegistry, type BackgroundSession, type SessionLauncher } from "./sessions.ts";
+import { askForSession } from "./session-questions.ts";
 import { SessionChats } from "./session-files.ts";
 import { answerMessage, questionnaires, settledQuestions } from "./ask.ts";
 import { askUser } from "../ask/web.ts";
@@ -54,6 +55,8 @@ import type { Runtime } from "./runtime.ts";
 import { findLinters } from "../execution/lint.ts";
 import { handleResolveApproval, lastQaAsks, waiveLint, waiveQa } from "../workflow/workflow.ts";
 import { recordDecision } from "../master/decisions.ts";
+import { stepViews } from "../webui/api/plan-facts.ts";
+import { truncate } from "../text.ts";
 import { fail } from "../webui/api/index.ts";
 
 /** The state background callbacks report to; set while the lobby service runs. */
@@ -217,6 +220,31 @@ export function backgroundSessions(): readonly BackgroundSession[] {
   return registry?.sessions ?? [];
 }
 
+/** Rename this window's session (no key) or one of its background sessions. */
+function renameSession(state: Runtime, key: string | undefined, name: string): string {
+  const clean = cleanSessionName(name);
+  if (!key) {
+    state.pi.setSessionName(clean);
+    lobbyTopics.bump("status");
+    lobbyTopics.bump("sessions");
+    return `renamed this window to ${clean}`;
+  }
+  const session = backgroundSessions().find((entry) => entry.key === key && entry.projectRoot === state.root);
+  if (!session) throw new Error(`no session ${key}`);
+  session.rename(clean);
+  return `renamed ${key} to ${clean}`;
+}
+
+/** Put an ended background session away from the sidebar, or bring it back. */
+function archiveSession(state: Runtime, key: string, archived: boolean): string {
+  const list = registry ? (archived ? registry.sessions : registry.archived) : [];
+  const session = list.find((entry) => entry.key === key && entry.projectRoot === state.root);
+  if (!session) throw new Error(archived ? `no session ${key} to archive` : `no archived session ${key}`);
+  if (session.alive) throw new Error(`${session.name} is still running: stop it before archiving it`);
+  registry!.archive(key, archived);
+  return archived ? `archived ${session.name}` : `brought back ${session.name}`;
+}
+
 /** A background session changed: say so when one asks something or fails. */
 function sessionsChanged(): void {
   lobbyTopics.bump("sessions");
@@ -270,7 +298,7 @@ function startSession(state: Runtime, start: { request?: string; plan?: PlannedT
   // A request may lead with flags (`--worktree add login`); the session is named after what follows them.
   const name = taskName(plan?.title ?? (stripStartFlags(request!) || request!));
   try {
-    const session = sessionRegistry().start(state.ctx.cwd, { name, projectRoot: state.root, onDialog: dialogTracker(state), ...(plan ? { planId: plan.id } : { request: request! }), ...(start.auto ? { auto: true } : {}) }, sessionModel(state.ctx));
+    const session = sessionRegistry().start(state.ctx.cwd, { name, projectRoot: state.root, onDialog: dialogTracker(state), ask: askForSession, ...(plan ? { planId: plan.id } : { request: request! }), ...(start.auto ? { auto: true } : {}) }, sessionModel(state.ctx));
     lobbyFeed.log("LOBBY", `started "${name}" in a new session`, "success");
     return session;
   } catch (error) {
@@ -284,7 +312,7 @@ export function resumeSession(state: Runtime, start: Relaunch): BackgroundSessio
     const session = sessionRegistry().start(state.ctx.cwd, {
       name: start.name,
       projectRoot: state.root,
-      onDialog: dialogTracker(state),
+      onDialog: dialogTracker(state), ask: askForSession,
       sessionFile: start.sessionFile,
       ...(start.message ? { message: start.message } : {}),
     });
@@ -374,7 +402,7 @@ async function resumeTask(state: Runtime, taskId: string): Promise<{ notice: str
     const session = sessionRegistry().start(state.ctx.cwd, {
       name: task.title,
       projectRoot: state.root,
-      onDialog: dialogTracker(state),
+      onDialog: dialogTracker(state), ask: askForSession,
       taskId,
       ...(file ? { sessionFile: file } : {}),
       message: `/bot-lobby carry-on ${taskId}`,
@@ -398,9 +426,19 @@ function mutableTask(state: Runtime, taskId: string): Task {
 }
 
 async function wakeTask(state: Runtime, task: Task, message: string): Promise<string> {
+  if (!tellOracle(state, task, message)) return (await resumeTask(state, task.id)).notice;
+  return "the owning oracle has been notified";
+}
+
+/**
+ * Leave a message in the task's inbox and hand it to its oracle now when a
+ * session here runs the task; false when the task is paused or stopped, so the
+ * oracle reads it once the task carries on.
+ */
+function tellOracle(state: Runtime, task: Task, message: string): boolean {
   const inbox = sendToInbox(state.root, state.configDir, task.id, message, state.ctx.sessionManager.getSessionId());
   const route = resumeRoute(task, taskDrivers(state));
-  if (route.kind === "stopped" || route.kind === "paused") return (await resumeTask(state, task.id)).notice;
+  if (route.kind === "stopped" || route.kind === "paused") return false;
   if (task.ownerSessionId === state.ctx.sessionManager.getSessionId()) {
     state.pi.sendUserMessage(message, state.ctx.isIdle() ? undefined : { deliverAs: "followUp" });
     markInboxDelivered(state.root, state.configDir, task.id, [inbox.id]);
@@ -411,7 +449,7 @@ async function wakeTask(state: Runtime, task: Task, message: string): Promise<st
       markInboxDelivered(state.root, state.configDir, task.id, [inbox.id]);
     }
   }
-  return "the owning oracle has been notified";
+  return true;
 }
 
 function canForceCloseTask(state: Runtime, taskId: string): boolean {
@@ -445,6 +483,33 @@ async function acceptTask(state: Runtime, taskId: string): Promise<{ notice: str
   return { notice: `${task.id} accepted as it is; ${wake}` };
 }
 
+/**
+ * Skip a plan step on the user's word, with their reason: kept on the task
+ * (the checklist shows it skipped, the reason under it), recorded as a
+ * decision, and passed to the task's oracle so it carries on without it. A
+ * paused or stopped task is not resumed: its oracle reads it when it carries on.
+ */
+async function skipTaskStep(state: Runtime, taskId: string, step: number, text: string, reason: string): Promise<{ notice: string }> {
+  const task = mutableTask(state, taskId);
+  const why = reason.trim().replace(/\s+/g, " ");
+  if (!why) fail(400, "bad_request", "say why you are skipping this step");
+  if (why.length > MAX_SKIP_REASON) fail(400, "bad_request", `keep the reason under ${MAX_SKIP_REASON} characters`);
+  if (!task.plan) fail(400, "bad_request", "this task has no plan yet");
+  const steps = stepViews(task, taskWork(state.root, state.configDir, task.id));
+  const found = steps[step];
+  if (!found || found.text !== text) fail(409, "conflict", "the plan changed; refresh the task");
+  if (found.status === "done") fail(409, "conflict", "that step is already done");
+  if (found.status === "skipped") fail(409, "conflict", "that step is already skipped");
+  task.skippedSteps = [...(task.skippedSteps ?? []), { text, reason: why, at: new Date().toISOString() }];
+  recordDecision(task, `The user skipped step ${step + 1} ("${truncate(text, 200)}") from the Tasks screen. Reason: ${why}`);
+  saveTask(state.root, state.configDir, task);
+  lobbyTopics.bump("tasks");
+  lobbyTopics.bump("lobby");
+  const message = `The user skipped step ${step + 1} of ${task.id}'s plan: "${text}". Their reason: ${why}. Do not delegate, build or review that step; if an agent is on it now, let it stop there or tell it to. Carry on with the next open step.`;
+  if (!tellOracle(state, task, message)) return { notice: `step ${step + 1} skipped; the oracle reads why when the task carries on` };
+  return { notice: `step ${step + 1} skipped; the oracle has been told` };
+}
+
 async function resolveTaskApproval(state: Runtime, taskId: string, approvalId: string, decision: "approved" | "rejected", note?: string): Promise<{ notice: string }> {
   const task = mutableTask(state, taskId);
   if (!task.approvals.some((entry) => entry.id === approvalId && entry.status === "pending")) fail(409, "conflict", "approval is no longer pending");
@@ -893,12 +958,15 @@ export function createLobbyService(state: Runtime): LobbyService {
     refreshWorkspace: () => refreshWorkspace(state),
     sessionName: () => state.pi.getSessionName(),
     sessions: () => backgroundSessions().filter((session) => session.projectRoot === state.root),
+    renameSession: (key, name) => renameSession(state, key, name),
+    archiveSession: (key, archived) => archiveSession(state, key, archived),
     startSession: (start) => startSession(state, start),
     isAuto: (taskId) => autoFor(state, taskId),
     setAuto: (taskId, on) => switchAuto(state, taskId, on),
     sendToTask: (taskId, text) => sendToTask(state, taskId, text),
     resumeTask: (taskId) => resumeTask(state, taskId),
     acceptTask: (taskId) => acceptTask(state, taskId),
+    skipTaskStep: (taskId, step, text, reason) => skipTaskStep(state, taskId, step, text, reason),
     forceCloseTask: (taskId, title) => forceCloseTask(state, taskId, title),
     canForceCloseTask: (taskId) => canForceCloseTask(state, taskId),
     resolveTaskApproval: (taskId, approvalId, decision, note) => resolveTaskApproval(state, taskId, approvalId, decision, note),

package/src/lobby/session-questions.ts

@@ -0,0 +1,49 @@
+/**
+ * A background session's questions, asked wherever the user is. A session
+ * started "in a new session" runs headless, so every question it asks (its
+ * oracle's questionnaire, a pick, a line of text, a yes/no) reaches this
+ * window as an RPC dialog. Each one is put in this window's question queue,
+ * the same pop-up the user's own session asks in, named after the session it
+ * comes from, so nobody has to switch sessions to answer. The answer goes
+ * back to the session; a dialog answered some other way (or a session that
+ * ends) takes its question back out of the queue.
+ */
+import { readRelayRequest } from "../ask/relay.ts";
+import { readResult } from "../ask/web.ts";
+import { promptHub, type PromptHub } from "./prompt-hub.ts";
+import type { DialogAnswer, SessionDialog } from "./sessions.ts";
+
+export interface SessionQuestion {
+  /** The session's name, shown as who asks. */
+  from: string;
+  dialog: SessionDialog;
+  signal: AbortSignal;
+}
+
+/** Put a session's dialog to the user in the question pop-up; undefined when it was taken back first. */
+export async function askForSession({ from, dialog, signal }: SessionQuestion, hub: PromptHub = promptHub): Promise<DialogAnswer | undefined> {
+  const options = { signal };
+  const relayed = dialog.method === "editor" ? readRelayRequest(dialog.title, dialog.prefill) : undefined;
+  if (relayed) {
+    const outcome = await hub.ask("questionnaire", from, { questions: relayed }, options);
+    if (outcome.how === "cancelled") return undefined;
+    const result = outcome.how === "answered" ? readResult(outcome.value) : undefined;
+    return { value: JSON.stringify(result ?? { answers: [], cancelled: true }) };
+  }
+  if (dialog.method === "select") {
+    const outcome = await hub.ask("choose", from, { title: dialog.title, options: dialog.options ?? [] }, options);
+    return settled(outcome, (value) => (typeof value === "string" ? { value } : undefined));
+  }
+  if (dialog.method === "confirm") {
+    const outcome = await hub.ask("confirm", from, { question: dialog.title, ...(dialog.message ? { detail: dialog.message } : {}) }, options);
+    return settled(outcome, (value) => (typeof value === "boolean" ? { confirmed: value } : undefined));
+  }
+  const outcome = await hub.ask("text", from, { question: dialog.title, ...(dialog.placeholder ? { placeholder: dialog.placeholder } : {}) }, options);
+  return settled(outcome, (value) => (typeof value === "string" ? { value } : undefined));
+}
+
+function settled(outcome: { how: "answered" | "dismissed" | "cancelled"; value: unknown }, read: (value: unknown) => DialogAnswer | undefined): DialogAnswer | undefined {
+  if (outcome.how === "cancelled") return undefined;
+  if (outcome.how === "dismissed") return { cancelled: true };
+  return read(outcome.value) ?? { cancelled: true };
+}

package/src/lobby/sessions.ts

@@ -54,6 +54,11 @@ export interface SessionStart {
   message?: string;
   /** The task it was started to carry on (resumed from the Tasks screen). */
   taskId?: string;
+  /**
+   * Put a dialog to the user (this window's question pop-up); resolves with the answer, or undefined when the
+   * dialog was settled some other way first (`signal` aborts then).
+   */
+  ask?: (question: { from: string; dialog: SessionDialog; signal: AbortSignal }) => Promise<DialogAnswer | undefined>;
 }
 
 let counter = 0;
@@ -80,6 +85,9 @@ export class BackgroundSession {
   /** Dialogs the session waits on, oldest first. */
   readonly dialogs: SessionDialog[] = [];
   private readonly onDialog: NonNullable<SessionStart["onDialog"]>;
+  private readonly ask?: SessionStart["ask"];
+  /** The dialogs being asked in the question pop-up, to take back when they are settled another way. */
+  private readonly asking = new Map<string, AbortController>();
   private readonly proc: SessionProcess;
   private buffer = "";
   private stderr = "";
@@ -96,6 +104,7 @@ export class BackgroundSession {
     if (start.planId) this.planId = start.planId;
     if (start.taskId) this.taskId = start.taskId;
     this.onDialog = start.onDialog ?? (() => {});
+    if (start.ask) this.ask = start.ask;
     this.proc = proc;
     this.onChange = onChange;
     proc.stdout?.on("data", (chunk) => this.receive(String(chunk)));
@@ -121,6 +130,8 @@ export class BackgroundSession {
     this.exitCode = code;
     for (const dialog of this.dialogs) this.onDialog(dialog.id, false, this.sessionId);
     this.dialogs.length = 0;
+    for (const controller of this.asking.values()) controller.abort();
+    this.asking.clear();
     if (this.killTimer) clearTimeout(this.killTimer);
     this.feed.say("note", reason);
     for (const resolve of this.exitWaiters.splice(0)) resolve();
@@ -175,6 +186,8 @@ export class BackgroundSession {
     const index = this.dialogs.findIndex((dialog) => dialog.id === id);
     if (index < 0) return;
     this.dialogs.splice(index, 1);
+    this.asking.get(id)?.abort();
+    this.asking.delete(id);
     this.onDialog(id, false, this.sessionId);
     if (this.alive && this.proc.stdin) this.proc.stdin.write(`${JSON.stringify({ type: "extension_ui_response", id, ...answer })}\n`);
     this.onChange();
@@ -184,6 +197,13 @@ export class BackgroundSession {
    * Stop the session: its process ends (its task keeps its state and can be
    * resumed or claimed later). One that does not end within `graceMs` is killed.
    */
+  /** Give the session a new name, here and in its pi (its saved session takes it too). */
+  rename(name: string): void {
+    this.name = name;
+    if (this.alive) this.write({ type: "set_session_name", name });
+    this.onChange();
+  }
+
   stop(graceMs = STOP_GRACE_MS): void {
     if (!this.alive) return;
     try {
@@ -248,6 +268,21 @@ export class BackgroundSession {
     this.onChange();
   }
 
+  /** Ask the dialog in the question pop-up, wherever the user is; its answer goes back to the session. */
+  private putToUser(dialog: SessionDialog): void {
+    if (!this.ask) return;
+    const controller = new AbortController();
+    this.asking.set(dialog.id, controller);
+    this.ask({ from: this.name, dialog, signal: controller.signal }).then(
+      (answer) => {
+        if (this.asking.get(dialog.id) !== controller) return;
+        this.asking.delete(dialog.id);
+        if (answer) this.answer(dialog.id, answer);
+      },
+      () => this.asking.delete(dialog.id),
+    );
+  }
+
   private uiRequest(event: Record<string, unknown>): void {
     const id = String(event.id ?? "");
     const method = String(event.method ?? "");
@@ -262,6 +297,7 @@ export class BackgroundSession {
         ...(typeof event.prefill === "string" ? { prefill: event.prefill } : {}),
       });
       this.onDialog(id, true, this.sessionId);
+      this.putToUser(this.dialogs.at(-1)!);
       this.feed.log("LOBBY", `waiting for you: ${String(event.title ?? "a question").split("\n")[0]}`, "warning");
     } else if (method === "notify") {
       const level = event.notifyType === "error" ? "error" : event.notifyType === "warning" ? "warning" : "info";
@@ -299,6 +335,8 @@ export const launchPi = (args: string[], cwd: string, overrides: NodeJS.ProcessE
   const env: NodeJS.ProcessEnv = { ...process.env, PI_SKIP_VERSION_CHECK: "1" };
   delete env.BOT_LOBBY_SUBAGENT;
   delete env.BOT_LOBBY_WEB_PROJECT;
+  // It has no page of its own: its questions come to this window (see ask/web.ts).
+  env.BOT_LOBBY_BACKGROUND = "1";
   Object.assign(env, overrides);
   const proc: ChildProcess = spawn(invocation.command, invocation.args, { cwd, env, shell: false, detached: POSIX, windowsHide: true, stdio: ["pipe", "pipe", "pipe"] });
   return proc as unknown as SessionProcess;
@@ -306,6 +344,19 @@ export const launchPi = (args: string[], cwd: string, overrides: NodeJS.ProcessE
 
 /** Ended background sessions kept in the list (with their feeds); older ones are let go. */
 export const MAX_ENDED = 6;
+/** Archived sessions kept so an archive can be undone; older ones are let go. */
+export const MAX_ARCHIVED = 20;
+/** Longest session name the lobby sets. */
+export const MAX_SESSION_NAME = 120;
+
+/** A session name as the lobby keeps it: one line, spaces collapsed, not too long. */
+export function cleanSessionName(name: string): string {
+  const clean = name.replace(/\s+/g, " ").trim();
+  if (!clean) throw new Error("a session needs a name");
+  if (clean.length > MAX_SESSION_NAME) throw new Error(`keep the name under ${MAX_SESSION_NAME} characters`);
+  return clean;
+}
+
 
 /** Every background session this window started, oldest first (ended ones beyond the newest few let go). */
 export class SessionRegistry {
@@ -341,6 +392,21 @@ export class SessionRegistry {
     return this.sessions.find((session) => session.key === key);
   }
 
+  /** Ended sessions put away from the list, newest last; one can come back while this pi runs. */
+  readonly archived: BackgroundSession[] = [];
+
+  /** Put an ended session away (true), or bring an archived one back (false); false when there was no such session. */
+  archive(key: string, archived = true): boolean {
+    const from = archived ? this.sessions : this.archived;
+    const index = from.findIndex((session) => session.key === key && !session.alive);
+    if (index < 0) return false;
+    const [session] = from.splice(index, 1);
+    (archived ? this.archived : this.sessions).push(session!);
+    if (this.archived.length > MAX_ARCHIVED) this.archived.splice(0, this.archived.length - MAX_ARCHIVED);
+    this.onChange();
+    return true;
+  }
+
   /** The background session running a pi session id, if this window started it. */
   bySessionId(sessionId: string | undefined): BackgroundSession | undefined {
     return sessionId ? this.sessions.find((session) => session.sessionId === sessionId) : undefined;

package/src/pi/auto-compaction.ts

@@ -1,5 +1,5 @@
 import { compact, CONFIG_DIR_NAME, DEFAULT_COMPACTION_SETTINGS, estimateTokens, findCutPoint, type ExtensionAPI, type ExtensionContext, type TurnEndEvent } from "@earendil-works/pi-coding-agent";
-import { contextMarks, freshContextOn } from "./fresh-context.ts";
+import { contextMarks, freshContextOn, staleCompaction } from "./fresh-context.ts";
 import { AUTO_COMPACT_ENV, isSubagentProcess } from "./quiet.ts";
 import { dataRoot, detectProjectRoot, loadConfig } from "../state/project.ts";
 import { describeShared, DIGEST_INSTRUCTION, parseDigest, shareDigest, type DigestItem } from "../knowledge/oracle-digest.ts";
@@ -34,8 +34,9 @@ export function compactionThreshold(window: number, reserve = DEFAULT_COMPACTION
 }
 
 /**
- * Compact at a settled tool boundary; ctx.compact() would abort the turn we need to continue. Each agent's settings
- * can turn it off. The oracle's checkpoint also lists what it learned that is worth keeping, tagged by agent, and
+ * Compact at a settled tool boundary, below pi's own threshold (pi 1.3 still sets that only per model in settings, and
+ * ctx.compact() would abort the turn we need to continue). Each agent's settings can turn it off. Compactions pi
+ * starts itself get the same checkpoint through `session_before_compact`. The oracle's checkpoint also lists what it learned that is worth keeping, tagged by agent, and
  * that goes into the knowledge base: its own, and the designer's, backend's and QA's where it concerns them.
  */
 export function registerAutoCompaction(pi: ExtensionAPI, summarize: typeof compact = compact, options: AutoCompactionOptions = {}): void {
@@ -88,26 +89,52 @@ export function registerAutoCompaction(pi: ExtensionAPI, summarize: typeof compa
     busy = true;
     ctx.ui.notify("Compacting agent context", "info");
     try {
-      const auth = await ctx.modelRegistry.getApiKeyAndHeaders(ctx.model);
-      if (!auth.ok) throw new Error(auth.error);
-      const headers = auth.headers ? Object.fromEntries(Object.entries(auth.headers).filter((entry): entry is [string, string] => entry[1] !== null)) : undefined;
-      const retry = pi.getSettings().retry;
-      const retryPolicy = { enabled: retry?.enabled ?? true, maxRetries: retry?.maxRetries ?? 3, baseDelayMs: retry?.baseDelayMs ?? 2_000, maxAgentDelayMs: retry?.maxAgentDelayMs };
-      const result = await summarize({ firstKeptEntryId, messagesToSummarize: messages, turnPrefixMessages: [], isSplitTurn: false, tokensBefore: estimate, previousSummary: previous?.type === "compaction" ? previous.summary : undefined, fileOps, settings: { enabled: true, reserveTokens: reserve, keepRecentTokens } }, auth.baseUrl ? { ...ctx.model, baseUrl: auth.baseUrl } : ctx.model, auth.apiKey, headers, oracle ? `${CHECKPOINT} ${DIGEST_INSTRUCTION}` : CHECKPOINT, ctx.signal, undefined, undefined, auth.env, retryPolicy);
-      ctx.signal?.throwIfAborted();
+      const result = await checkpoint({ firstKeptEntryId, messagesToSummarize: messages, turnPrefixMessages: [], isSplitTurn: false, tokensBefore: estimate, previousSummary: previous?.type === "compaction" ? previous.summary : undefined, fileOps, settings: { enabled: true, reserveTokens: reserve, keepRecentTokens } }, ctx, ctx.signal);
       ctx.ui.notify("Agent context compacted", "info");
-      if (oracle) {
-        try {
-          const items = parseDigest(result.summary);
-          const shared = items.length ? share(items, ctx) : "";
-          if (shared) ctx.ui.notify(`Knowledge updated: ${shared}`, "info");
-        } catch (error) {
-          ctx.ui.notify(`Could not update knowledge: ${(error as Error).message}`, "warning");
-        }
-      }
+      learn(result.summary, ctx);
       return { entries: [...event.entries, { type: "compaction" as const, summary: result.summary, firstKeptEntryId, usage: result.usage, details: result.details }] };
     } catch (error) {
       ctx.ui.notify(`Context compaction failed: ${(error as Error).message}`, "warning");
     } finally { busy = false; }
   });
+  // pi's own compactions (its context threshold, overflow recovery, /compact) write the same checkpoint from pi's
+  // preparation, so every summary an agent continues from has the same shape and the oracle's still feeds knowledge.
+  pi.on("session_before_compact", async (event, ctx) => {
+    if (staleCompaction(event) || !ctx.model) return undefined;
+    try {
+      const compaction = await checkpoint(event.preparation, ctx, event.signal, event.customInstructions);
+      learn(compaction.summary, ctx);
+      return { compaction };
+    } catch (error) {
+      if (event.signal.aborted) throw error;
+      ctx.ui.notify(`Checkpoint failed, using pi's summary: ${(error as Error).message}`, "warning");
+      return undefined;
+    }
+  });
+
+  /** Summarize with the checkpoint prompt (and, for the oracle, its knowledge digest) on the session's model. */
+  async function checkpoint(preparation: Parameters<typeof compact>[0], ctx: ExtensionContext, signal: AbortSignal | undefined, extra?: string) {
+    const model = ctx.model!;
+    const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+    if (!auth.ok) throw new Error(auth.error);
+    const headers = auth.headers ? Object.fromEntries(Object.entries(auth.headers).filter((entry): entry is [string, string] => entry[1] !== null)) : undefined;
+    const retry = pi.getSettings().retry;
+    const retryPolicy = { enabled: retry?.enabled ?? true, maxRetries: retry?.maxRetries ?? 3, baseDelayMs: retry?.baseDelayMs ?? 2_000, maxAgentDelayMs: retry?.maxAgentDelayMs };
+    const instructions = [oracle ? `${CHECKPOINT} ${DIGEST_INSTRUCTION}` : CHECKPOINT, extra].filter(Boolean).join("\n\n");
+    const result = await summarize(preparation, auth.baseUrl ? { ...model, baseUrl: auth.baseUrl } : model, auth.apiKey, headers, instructions, signal, undefined, undefined, auth.env, retryPolicy);
+    signal?.throwIfAborted();
+    return result;
+  }
+
+  /** The oracle's digest from a checkpoint, shared into the knowledge base. */
+  function learn(summary: string, ctx: ExtensionContext): void {
+    if (!oracle) return;
+    try {
+      const items = parseDigest(summary);
+      const shared = items.length ? share(items, ctx) : "";
+      if (shared) ctx.ui.notify(`Knowledge updated: ${shared}`, "info");
+    } catch (error) {
+      ctx.ui.notify(`Could not update knowledge: ${(error as Error).message}`, "warning");
+    }
+  }
 }

package/src/pi/events.ts

@@ -19,6 +19,7 @@ import { isAutoMode } from "../state/auto.ts";
 import { triageContext } from "../classifier/triage.ts";
 import { qaStillDue, rosterWords } from "../workflow/track.ts";
 import { previousTaskNote } from "./fresh-context.ts";
+import { skippedStepsNote } from "./plan-checklist.ts";
 import { budgetLine, budgetState, clockTask, pauseClocks, readBudget, resumeClocks, startClock, stopClocks, turnStarted } from "../state/budget.ts";
 
 /** Tools that wait on the user: the task's clock waits with them. */
@@ -52,6 +53,7 @@ export function masterTaskContext(task: Task, comments: readonly PlanComment[] =
     `Request: ${truncate(task.approvedPlan && task.plan ? requestBesidePlan(taskRequest(task)) : taskRequest(task), 2000)}`,
     task.proposal ? `Current proposal:\n${truncate(task.proposal, 2000)}` : "",
     task.plan ? `Approved plan:\n${truncate(task.plan, 3000)}` : "",
+    skippedStepsNote(task.plan, task.skippedSteps),
     task.amendments.length > 0 ? `User amendments:\n${task.amendments.map((entry) => `- ${entry}`).join("\n")}` : "",
     open.length > 0 ? `Open plan comments (from the lobby):\n${open.map((comment) => `- ${truncate(comment.text, 600)}`).join("\n")}` : "",
     task.approvedPlan ? `The user agreed this task's plan in the planning panel (${task.approvedPlan}), and it is the task's plan: delegate its steps without clarifying, scouting or proposing, and answer open questions from the plan.${task.track?.satOut?.length ? ` ${rosterWords(task.track.satOut)} sat out the panel: do not give ${task.track.satOut.length === 1 ? "it" : "them"} work${task.track.satOut.includes("qa") ? ", and there is no QA gate (complete once every step is done)" : ""}.` : ""}` : "",

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/pi/tools.ts

@@ -132,8 +132,8 @@ export function workflowDeps(
     effort: effortFor((model, thinking) => checkThinking(modelLookup(ctx)(model), thinking).level),
     // Time spent waiting on the user is not the task's: its budget clock waits too.
     // The questions go to the web page, where a free-text answer may run to several lines.
-    ask: async (question) => (canAsk() ? whileAsking(() => askText(question)) : undefined),
-    choose: async (title, options) => (canAsk() ? whileAsking(() => askChoice(title, options)) : undefined),
+    ask: async (question) => (canAsk() ? whileAsking(() => askText(question, undefined, ctx)) : undefined),
+    choose: async (title, options) => (canAsk() ? whileAsking(() => askChoice(title, options, undefined, ctx)) : undefined),
     // An agent's own questions (the designer's), relayed as the questionnaire.
     ...(canAsk() ? { askQuestions: (questions: AskQuestion[], from: string, askSignal?: AbortSignal) => whileAsking(() => askUser(questions, ctx, askSignal, from)) } : {}),
     notify: (message, level = "info") => {

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(