@stevecastaneda/paseo-progress 1.3.0 → 1.4.0

package/server/launcher.ts

@@ -1,9 +1,19 @@
 import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { delimiter, dirname, join } from "node:path";
+import { basename, dirname, join, posix, win32 } from "node:path";
 
 export const PLUGIN_ID = "progress";
 
+// Where Paseo's command may be, in the order tried: an override, the one
+// Paseo names for the agents and plugins it starts, PATH, then the app's
+// default install. The launcher script below carries the same list.
+export function paseoCommands(env: NodeJS.ProcessEnv = process.env, platform: NodeJS.Platform = process.platform): string[] {
+  const installed = platform === "win32"
+    ? env.LOCALAPPDATA && win32.join(env.LOCALAPPDATA, "Programs", "Paseo", "resources", "bin", "paseo.cmd")
+    : "/Applications/Paseo.app/Contents/Resources/bin/paseo";
+  return [env.PASEO_BIN, env.PASEO_CLI, "paseo", installed].filter((cli): cli is string => Boolean(cli));
+}
+
 // The launcher never names a plugin folder. Each run asks Paseo which copy of
 // the plugin it is running, so updates and `npm run dev` switches keep working.
 export function launcherScript(): string {
@@ -20,11 +30,28 @@ const { spawnSync } = process.getBuiltinModule("node:child_process");
 const { existsSync } = process.getBuiltinModule("node:fs");
 const { join } = process.getBuiltinModule("node:path");
 
+const windows = process.platform === "win32";
+
+function paseoCommands() {
+  const env = process.env;
+  const installed = windows
+    ? env.LOCALAPPDATA && join(env.LOCALAPPDATA, "Programs", "Paseo", "resources", "bin", "paseo.cmd")
+    : "/Applications/Paseo.app/Contents/Resources/bin/paseo";
+  return [env.PASEO_BIN, env.PASEO_CLI, "paseo", installed].filter(Boolean);
+}
+
+// On Windows Paseo's command is paseo.cmd, which Node can start, or find on
+// PATH, only through cmd.exe.
+function askPaseo(cli) {
+  return windows
+    ? spawnSync('"' + cli + '" plugin ls ${PLUGIN_ID} --json', { shell: true, encoding: "utf8" })
+    : spawnSync(cli, ["plugin", "ls", "${PLUGIN_ID}", "--json"], { encoding: "utf8" });
+}
+
 function pluginDirectory() {
   if (process.env.PASEO_PROGRESS_PLUGIN_DIR) return process.env.PASEO_PROGRESS_PLUGIN_DIR;
-  const clis = [process.env.PASEO_BIN, "paseo", "/Applications/Paseo.app/Contents/Resources/bin/paseo"].filter(Boolean);
-  for (const cli of clis) {
-    const result = spawnSync(cli, ["plugin", "ls", "${PLUGIN_ID}", "--json"], { encoding: "utf8" });
+  for (const cli of paseoCommands()) {
+    const result = askPaseo(cli);
     if (result.error || result.status !== 0) continue;
     try {
       const plugin = JSON.parse(result.stdout).find((entry) => entry.id === "${PLUGIN_ID}");
@@ -57,31 +84,64 @@ export function defaultLauncherPath(home = homedir()): string {
 
 export type LauncherState = "missing" | "current" | "outdated" | "foreign";
 
-export async function launcherState(path: string): Promise<LauncherState> {
-  const current = await readFile(path, "utf8").catch(() => null);
+type LauncherFile = { path: string; content: string };
+
+// PowerShell and cmd run only files with an extension like .cmd, so on
+// Windows a .cmd file beside the launcher runs it with node.
+function launcherFiles(path: string, platform: NodeJS.Platform): LauncherFile[] {
+  const files = [{ path, content: launcherScript() }];
+  if (platform === "win32") {
+    files.push({ path: `${path}.cmd`, content: `@echo off\r\nrem ${MARKER}. Lets PowerShell and cmd run ${basename(path)}.\r\nnode "%~dp0${basename(path)}" %*\r\nexit /b %errorlevel%\r\n` });
+  }
+  return files;
+}
+
+async function fileState(file: LauncherFile): Promise<LauncherState> {
+  const current = await readFile(file.path, "utf8").catch(() => null);
   if (current === null) return "missing";
-  if (current === launcherScript()) return "current";
+  if (current === file.content) return "current";
   return current.includes(MARKER) ? "outdated" : "foreign";
 }
 
-// Writes the launcher when it is missing or out of date. Never replaces a file
-// something else put there. Returns whether it wrote.
-export async function installLauncher(path: string): Promise<boolean> {
-  const state = await launcherState(path);
-  if (state === "current") return false;
-  if (state === "foreign") throw new Error(`${path} already exists and was not written by this plugin. Move it, or pass another path.`);
-  await mkdir(dirname(path), { recursive: true });
-  await writeFile(path, launcherScript());
-  await chmod(path, 0o755);
-  return true;
+async function fileStates(path: string, platform: NodeJS.Platform) {
+  const files = launcherFiles(path, platform);
+  const states = await Promise.all(files.map(fileState));
+  return files.map((file, index) => ({ ...file, state: states[index] }));
+}
+
+// Writes the launcher files that are missing or out of date. Never replaces a
+// file something else put there. Returns whether it wrote.
+export async function installLauncher(path: string, platform: NodeJS.Platform = process.platform): Promise<boolean> {
+  const files = await fileStates(path, platform);
+  const foreign = files.find((file) => file.state === "foreign");
+  if (foreign) throw new Error(`${foreign.path} already exists and was not written by this plugin. Move it, or pass another path.`);
+  let wrote = false;
+  for (const file of files) {
+    if (file.state === "current") continue;
+    await mkdir(dirname(file.path), { recursive: true });
+    await writeFile(file.path, file.content);
+    await chmod(file.path, 0o755);
+    wrote = true;
+  }
+  return wrote;
 }
 
 // For the panel: whether agents on the daemon host can run `paseo-progress`.
-export async function launcherStatus(path = defaultLauncherPath(), pathEnv = process.env.PATH ?? "") {
+// When something else is in the way, path names that file.
+export async function launcherStatus(path = defaultLauncherPath(), pathEnv = process.env.PATH ?? "", platform: NodeJS.Platform = process.platform) {
+  const files = await fileStates(path, platform);
+  const states = files.map((file) => file.state);
+  const foreign = files.find((file) => file.state === "foreign");
+  const state: LauncherState = foreign ? "foreign"
+    : states.every((each) => each === "current") ? "current"
+    : states.every((each) => each === "missing") ? "missing" : "outdated";
+  // Windows paths ignore case and may end in either slash.
+  const paths = platform === "win32" ? win32 : posix;
+  const folder = (dir: string) => platform === "win32" ? dir.replace(/[\\/]+$/, "").toLowerCase() : dir.replace(/\/+$/, "");
   return {
-    path,
-    state: await launcherState(path),
-    onPath: pathEnv.split(delimiter).some((entry) => entry.replace(/\/+$/, "") === dirname(path)),
+    path: foreign?.path ?? path,
+    state,
+    onPath: pathEnv.split(paths.delimiter).some((entry) => folder(entry) === folder(paths.dirname(path))),
   };
 }
 

package/server/question-mode.ts

@@ -0,0 +1,61 @@
+// The question mode lives in Paseo's settings, which only the plugin's server
+// process can read. It mirrors the mode into a file the paseo-progress command
+// can read on its own.
+import { readFile, rm } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { z } from "zod";
+import type { PluginSettings } from "@getpaseo/plugin/server";
+import { DEFAULT_QUESTION_MODE, QUESTION_MODES, type QuestionMode } from "../shared/question-modes.ts";
+import type { questionSettings } from "../shared/settings.ts";
+import { stateRoot, writeAtomic } from "./store.ts";
+
+const mirrorSchema = z.object({ questionMode: z.enum(QUESTION_MODES) });
+
+export function questionModePath(home = homedir()): string {
+  return join(stateRoot(home), "settings.json");
+}
+
+// The default unless the mirror says otherwise, so a missing or damaged file
+// never lets an agent build ahead of the user.
+export async function readQuestionMode(home = homedir()): Promise<QuestionMode> {
+  try {
+    return mirrorSchema.parse(JSON.parse(await readFile(questionModePath(home), "utf8"))).questionMode;
+  } catch {
+    return DEFAULT_QUESTION_MODE;
+  }
+}
+
+export async function writeQuestionMode(mode: QuestionMode, home = homedir()): Promise<void> {
+  await writeAtomic(questionModePath(home), `${JSON.stringify({ questionMode: mode })}\n`);
+}
+
+type Settings = Pick<PluginSettings<(typeof questionSettings)["schema"]>, "read" | "subscribe">;
+type State = Awaited<ReturnType<Settings["read"]>>;
+
+// Writes the mode now and on every change. Stopping deletes the mirror, so
+// agents fall back to the default while the plugin is off.
+export function mirrorQuestionMode(settings: Settings, home = homedir()): { stop(): Promise<void>; settled: Promise<void> } {
+  let writes = Promise.resolve();
+  let changed = false;
+  const write = (state: State | null) => {
+    const mode = state?.status === "ready" ? state.values.mode : DEFAULT_QUESTION_MODE;
+    writes = writes.then(() => writeQuestionMode(mode, home)).catch(() => {});
+    return writes;
+  };
+  const unsubscribe = settings.subscribe((state) => {
+    changed = true;
+    return write(state);
+  });
+  // A change heard while the first read is in flight is newer than that read.
+  const settled = settings.read().catch(() => null).then((state) => (changed ? writes : write(state)));
+  return {
+    settled,
+    async stop() {
+      await unsubscribe();
+      await settled;
+      await writes;
+      await rm(questionModePath(home), { force: true });
+    },
+  };
+}

package/server/skill.ts

@@ -1,9 +1,9 @@
-import { execFile } from "node:child_process";
+import { exec, execFile } from "node:child_process";
 import { lstat, mkdir, readlink, symlink, unlink } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 import { promisify } from "node:util";
-import { PLUGIN_ID } from "./launcher.ts";
+import { paseoCommands, PLUGIN_ID } from "./launcher.ts";
 
 export const SKILL_NAME = "paseo-progress";
 
@@ -41,7 +41,9 @@ export async function installSkill(paths: string[], pluginDirectory: string): Pr
     if (states[index] !== "missing" && states[index] !== "outdated") continue;
     if (states[index] === "outdated") await unlink(path);
     await mkdir(dirname(path), { recursive: true });
-    await symlink(skillSource(pluginDirectory), path, "dir");
+    // A junction on Windows, where a directory symlink needs admin rights or
+    // Developer Mode. Other systems ignore the type and make a symlink.
+    await symlink(skillSource(pluginDirectory), path, "junction");
     wrote = true;
   }
   return wrote;
@@ -60,10 +62,9 @@ export async function skillStatus(paths: string[], pluginDirectory: string) {
 // The server bundle doesn't know its own folder, so ask Paseo, the same way
 // the launcher does.
 export async function findPluginDirectory(): Promise<string> {
-  const clis = [process.env.PASEO_BIN, "paseo", "/Applications/Paseo.app/Contents/Resources/bin/paseo"].filter((cli): cli is string => Boolean(cli));
-  for (const cli of clis) {
+  for (const cli of paseoCommands()) {
     try {
-      const { stdout } = await promisify(execFile)(cli, ["plugin", "ls", PLUGIN_ID, "--json"]);
+      const { stdout } = await askPaseo(cli);
       const plugin = (JSON.parse(stdout) as Array<{ id: string; path?: string }>).find((entry) => entry.id === PLUGIN_ID);
       if (plugin?.path) return plugin.path;
     } catch {
@@ -73,6 +74,14 @@ export async function findPluginDirectory(): Promise<string> {
   throw new Error("Could not ask Paseo where this plugin is installed.");
 }
 
+// On Windows Paseo's command is paseo.cmd, which Node can start, or find on
+// PATH, only through cmd.exe.
+function askPaseo(cli: string) {
+  return process.platform === "win32"
+    ? promisify(exec)(`"${cli}" plugin ls ${PLUGIN_ID} --json`)
+    : promisify(execFile)(cli, ["plugin", "ls", PLUGIN_ID, "--json"]);
+}
+
 export async function handleSkillStatus() {
   return skillStatus(defaultSkillPaths(), await findPluginDirectory());
 }

package/server/store.ts

@@ -3,11 +3,11 @@
 // one folder per worktree, so git never sees them and nothing needs hiding.
 // Only runs the user asks to save are written into the repo, one file per run.
 import { execFile } from "node:child_process";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { realpathSync } from "node:fs";
-import { appendFile, mkdir, readdir, readFile, rm, rmdir, stat, writeFile } from "node:fs/promises";
+import { appendFile, mkdir, readdir, readFile, rename, rm, rmdir, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { basename, join, normalize, resolve } from "node:path";
+import { basename, dirname, join, normalize, resolve } from "node:path";
 import { promisify } from "node:util";
 import { LEGACY_FOLDER, PANEL_OPENED_NAME, PROGRESS_FILE_NAME } from "../shared/events.ts";
 import { withLock } from "./lock.ts";
@@ -40,6 +40,23 @@ async function exists(path: string): Promise<boolean> {
   return Boolean(await stat(path).catch(() => null));
 }
 
+// The plugin's per-user folder on this computer.
+export function stateRoot(home = homedir()): string {
+  return join(home, ".local", "state", "paseo-progress");
+}
+
+// Readers see the old file or the new one, never half of one.
+export async function writeAtomic(path: string, text: string): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  const temp = `${path}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temp, text);
+    await rename(temp, path);
+  } finally {
+    await rm(temp, { force: true });
+  }
+}
+
 // One folder per worktree on this computer, named so a person can tell which
 // worktree it belongs to.
 export function outsideDirectory(root: string, home = homedir()): string {
@@ -48,7 +65,7 @@ export function outsideDirectory(root: string, home = homedir()): string {
     real = realpathSync(root);
   } catch {}
   const hash = createHash("sha1").update(real).digest("hex").slice(0, 8);
-  return join(home, ".local", "state", "paseo-progress", `${basename(real)}-${hash}`);
+  return join(stateRoot(home), `${basename(real)}-${hash}`);
 }
 
 // Whether git tracks a 0.1.x progress file, per worktree, until the file changes.

package/server/whats-new.ts

@@ -0,0 +1,127 @@
+// After an update, the panel shows what changed in this version, once. The
+// notes come from the changelog in the plugin's own README, so they're
+// written in one place. Whether they've been seen is kept per user on this
+// computer.
+import { readdir, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { z } from "zod";
+import { NOTE_KINDS, type NoteKind, type WhatsNew, type WhatsNewNote } from "../shared/whats-new.ts";
+import { spans } from "../shared/write-up.ts";
+import { findPluginDirectory } from "./skill.ts";
+import { stateRoot, writeAtomic } from "./store.ts";
+
+export type Release = { version: string; readme: string | null };
+
+const seenSchema = z.object({ seen: z.string() });
+const packageSchema = z.object({ version: z.string() });
+
+export function whatsNewPath(home = homedir()): string {
+  return join(stateRoot(home), "whats-new.json");
+}
+
+// The top-level bullets under `### <version>` in the README's `## Changelog`,
+// or null when that version has none.
+export function changelogNotes(readme: string, version: string): WhatsNewNote[] | null {
+  let section: "other" | "changelog" | "version" = "other";
+  const notes: string[] = [];
+  for (const line of readme.replace(/\r\n?/g, "\n").split("\n")) {
+    if (section === "version" && /^#{2,3}\s/.test(line)) break;
+    if (/^##\s/.test(line)) section = line.trim() === "## Changelog" ? "changelog" : "other";
+    else if (section === "changelog" && line.trim() === `### ${version}`) section = "version";
+    else if (section === "version" && /^[-*]\s/.test(line)) notes.push(line.slice(2).trim());
+    else if (section === "version" && notes.length && /^\s+\S/.test(line) && !/^\s+([-*+]|\d+[.)])\s/.test(line)) {
+      notes[notes.length - 1] += ` ${line.trim()}`;
+    }
+  }
+  return notes.length ? notes.map(note) : null;
+}
+
+// A bullet can open with a kind tag, like `[Fixed]`, and then a bold
+// sentence, like `**Title.** Detail.`, which is its title.
+function note(bullet: string): WhatsNewNote {
+  const tag = /^\[([a-z]+)\]\s*(.*)$/i.exec(bullet);
+  const kind = tag ? noteKind(tag[1]) : undefined;
+  const rest = kind ? tag![2] : bullet;
+  const text = rest.split(/(`[^`]+`)/).map((part, index) => index % 2 ? part : curly(part)).join("");
+  const lead = /^\*\*([^*]+?[.!?])\*\*\s*(.*)$/.exec(text);
+  return { ...(kind && { kind }), ...(lead ? { title: plain(lead[1]), body: lead[2] } : { body: text }) };
+}
+
+function noteKind(tag: string): NoteKind | undefined {
+  const key = tag.toLowerCase();
+  return Object.hasOwn(NOTE_KINDS, key) ? key as NoteKind : undefined;
+}
+
+// The README is typed with straight quotes; the panel shows typeset ones. Code keeps its own.
+function curly(text: string): string {
+  return text.replace(/(^|[\s([{])"/g, "$1\u201c").replace(/"/g, "\u201d").replace(/(^|[\s([{])'/g, "$1\u2018").replace(/'/g, "\u2019");
+}
+
+function plain(markdown: string): string {
+  return spans(markdown).map((span) => span.text).join("");
+}
+
+// A note's title, or else the first sentence of its body, without Markdown.
+export function headline(note: WhatsNewNote): string {
+  if (note.title) return note.title;
+  const body = plain(note.body);
+  return /^.*?[.!?](?=\s|$)/.exec(body)?.[0] ?? body;
+}
+
+async function readSeen(home: string): Promise<string | null> {
+  try {
+    return seenSchema.parse(JSON.parse(await readFile(whatsNewPath(home), "utf8"))).seen;
+  } catch {
+    return null;
+  }
+}
+
+export async function markWhatsNewSeen(version: string, home = homedir()): Promise<void> {
+  await writeAtomic(whatsNewPath(home), `${JSON.stringify({ seen: version })}\n`);
+}
+
+// A worktree's folder (see outsideDirectory) means the plugin was in use
+// before this version, so this is an update, not a new install.
+async function usedBefore(home: string): Promise<boolean> {
+  const entries = await readdir(stateRoot(home), { withFileTypes: true }).catch(() => []);
+  return entries.some((entry) => entry.isDirectory() && /-[0-9a-f]{8}$/.test(entry.name));
+}
+
+// What to show, or null. A new install has nothing to catch up on, so it
+// records this version as seen.
+export async function whatsNew({ version, readme }: Release, home = homedir()): Promise<WhatsNew | null> {
+  const notes = readme === null ? null : changelogNotes(readme, version);
+  if (!notes) return null;
+  const seen = await readSeen(home);
+  if (seen === version) return null;
+  if (seen === null && !(await usedBefore(home))) {
+    await markWhatsNewSeen(version, home);
+    return null;
+  }
+  return { version, headline: headline(notes[0]), notes };
+}
+
+// The server bundle can't read files beside it, so ask Paseo where the plugin
+// is. Read once per load: an update reloads the bundle, which starts over.
+let release: Promise<Release> | null = null;
+
+function currentRelease(): Promise<Release> {
+  release ??= findPluginDirectory().then(async (directory) => ({
+    version: packageSchema.parse(JSON.parse(await readFile(join(directory, "package.json"), "utf8"))).version,
+    readme: await readFile(join(directory, "README.md"), "utf8").catch(() => null),
+  }));
+  release.catch(() => {
+    release = null;
+  });
+  return release;
+}
+
+export async function handleGetWhatsNew(): Promise<WhatsNew | null> {
+  return whatsNew(await currentRelease());
+}
+
+export async function handleDismissWhatsNew(input: { version: string }) {
+  await markWhatsNewSeen(input.version);
+  return {};
+}

package/shared/dashboard.ts

@@ -1,4 +1,5 @@
 import { EVENT_VERSION, eventSchema, type DELIVERABLE_KINDS, type FileLink, type ProgressEvent, type QuestionOption, type TicketStatus } from "./events.ts";
+import { QUESTION_MODE_RULES, type QuestionState } from "./question-modes.ts";
 
 // One recorded change to a ticket, oldest first. `stage: ""` clears the stage.
 export interface TicketChange {
@@ -43,14 +44,18 @@ export interface Question {
   title: string;
   question: string;
   options: QuestionOption[];
-  // The option the agent leans toward. Nothing is built until the user answers.
+  // The option the agent leans toward.
   recommended: string;
+  // What the agent does while the question is open.
+  state: QuestionState;
+  // Why the question holds even in Keep building mode.
+  big?: string;
   background?: string;
   files: FileLink[];
   raisedBy?: string;
   ticketId?: string;
   askedAt: string;
-  // `changedCourse` only on older answers, from when agents built a default before asking.
+  // `changedCourse`: the agent had built another option and changed course.
   answer?: { choice: string; words?: string; changedCourse?: boolean; at: string };
 }
 
@@ -279,6 +284,8 @@ export function reduceProgress(parsed: { events: ParsedLine[]; issues: FileIssue
           question: event.question,
           options: event.options ?? [],
           recommended: event.recommend ?? event.default ?? "",
+          state: event.mode ? QUESTION_MODE_RULES[event.mode].state(Boolean(event.big)) : event.default !== undefined && !event.waits ? "building" : "waiting",
+          big: event.big,
           background: event.background,
           files: event.files ?? [],
           raisedBy: event.raisedBy,

package/shared/events.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { QUESTION_MODES } from "./question-modes.ts";
 
 // One line of `progress.jsonl`. The command-line tool writes these; the
 // dashboard reducer reads them. `v` lets later versions change a shape without
@@ -77,9 +78,11 @@ export const eventSchema = z.discriminatedUnion("type", [
   // A blocker that is not a ticket status, like a failing external service.
   z.object({ ...base, type: z.literal("stuck.set"), id: text, reason: text, ticket: text.optional() }),
   z.object({ ...base, type: z.literal("stuck.clear"), id: text }),
-  // The agent asks, recommends an option, and builds none of them before the
-  // answer: it works only on what the question doesn't affect. Older questions
-  // carry `default` (the option the agent carried on with) and `waits` instead.
+  // The agent asks and recommends an option. `mode` is the question mode when
+  // asked; without it (0.3.0 to 1.3.x) the agent built nothing before the
+  // answer, like "work-around". `big` says why the question holds even in
+  // "keep-building" mode. Questions from before 0.3.0 carry `default`, the
+  // option the agent carried on with unless it `waits`.
   z.object({
     ...base,
     type: z.literal("question.ask"),
@@ -89,6 +92,8 @@ export const eventSchema = z.discriminatedUnion("type", [
     options: z.array(questionOptionSchema).max(26).optional(),
     // The agent's pick: an option letter, or a word such as "Looks right" when there are no options.
     recommend: text.optional(),
+    mode: z.enum(QUESTION_MODES).optional(),
+    big: text.optional(),
     default: text.optional(),
     waits: z.boolean().optional(),
     background: text.optional(),
@@ -104,7 +109,7 @@ export const eventSchema = z.discriminatedUnion("type", [
     choice: text,
     // The user's own words, quoted under the answer.
     words: text.optional(),
-    // Older answers: true when the agent had to undo work built on its default.
+    // True when the agent had to undo work built on another option.
     changedCourse: z.boolean().optional(),
   }),
   // Adds detail to an open question; its reference and default stay.

package/shared/question-modes.ts

@@ -0,0 +1,45 @@
+// What an agent does when it asks the user a question, picked in Paseo's
+// Settings. The command, the settings page, and the dashboard all read this
+// table. No Paseo imports: the command's bundle includes this file.
+export const QUESTION_MODES = ["stop", "work-around", "keep-building"] as const;
+export type QuestionMode = (typeof QUESTION_MODES)[number];
+
+// Also what a missing or damaged mirror means.
+export const DEFAULT_QUESTION_MODE: QuestionMode = "work-around";
+
+// An open question on the dashboard: the agent stopped all work, holds what the
+// question affects, or builds its recommendation.
+export type QuestionState = "stopped" | "waiting" | "building";
+
+interface QuestionModeRules {
+  label: string;
+  hint: string;
+  // What the agent does until the answer. `question ask` prints it after "Mode: <label>."
+  askRule(question: { recommend: string; big: boolean }): string;
+  state(big: boolean): QuestionState;
+}
+
+const HOLD = "Build no option before the answer, not even your recommendation. Work on everything the question doesn't affect. If nothing else is left, end your turn, tell the user in chat which questions you're waiting on, and leave the run open.";
+
+export const QUESTION_MODE_RULES: Record<QuestionMode, QuestionModeRules> = {
+  stop: {
+    label: "Stop",
+    hint: "Agents stop all work when they ask, until you answer.",
+    askRule: () => "Ask any other questions you already have, then stop all work and resume only after an answer. End your turn now, tell the user in chat which questions you're waiting on, and leave the run open.",
+    state: () => "stopped",
+  },
+  "work-around": {
+    label: "Work around",
+    hint: "Agents hold what your answer affects and keep working on the rest.",
+    askRule: () => HOLD,
+    state: () => "waiting",
+  },
+  "keep-building": {
+    label: "Keep building",
+    hint: "Agents build their recommended option while you decide, and change course if you pick another. Big questions still wait.",
+    askRule: ({ recommend, big }) => big
+      ? `This question is big, so hold it like Work around. ${HOLD}`
+      : `Build ${recommend} now and keep working. If the user picks another option, undo the work built on ${recommend} and build their choice first. If the rest of the work is done while it's still open, leave it open and tell the user in chat; don't withdraw it.`,
+    state: (big) => (big ? "waiting" : "building"),
+  },
+};

package/shared/rpc.ts

@@ -1,6 +1,7 @@
 import { defineRpc } from "@getpaseo/plugin";
 import { z } from "zod";
 import type { Dashboard } from "./dashboard.ts";
+import type { WhatsNew } from "./whats-new.ts";
 
 // `panelOpened`: the Progress panel has been opened for this worktree before.
 // `root`: the worktree root the file was read from, which stored paths are
@@ -163,3 +164,20 @@ export const readDeliverablePiece = defineRpc({
   }),
   output: z.object({ data: z.string(), bytes: z.number() }),
 });
+
+// This version's changelog notes, once after an update; null otherwise.
+// `headline` is the first sentence of the first note, without Markdown.
+// A changelog bullet. `title` is its bold lead without Markdown, when it has
+// one; `body` is the rest, Markdown kept.
+export const getWhatsNew = defineRpc({
+  name: "progress.whats-new.get",
+  input: z.object({}),
+  output: z.custom<WhatsNew | null>(),
+});
+
+// The user closed it; it stays away for this version.
+export const dismissWhatsNew = defineRpc({
+  name: "progress.whats-new.dismiss",
+  input: z.object({ version: z.string().min(1) }),
+  output: z.object({}),
+});

package/shared/settings.ts

@@ -0,0 +1,10 @@
+import { defineSettings } from "@getpaseo/plugin";
+import { z } from "zod";
+import { DEFAULT_QUESTION_MODE, QUESTION_MODES } from "./question-modes.ts";
+
+export const questionSettings = defineSettings({
+  id: "questions",
+  scope: "host",
+  version: 1,
+  schema: z.object({ mode: z.enum(QUESTION_MODES).default(DEFAULT_QUESTION_MODE) }),
+});

package/shared/show.ts

@@ -1,8 +1,10 @@
 import type { Dashboard } from "./dashboard.ts";
 import { headlineText, shortTitle } from "./dashboard.ts";
 import { formatAgo, formatClock, formatMinutes, formatWorkDone, minutesSince } from "./format.ts";
+import type { QuestionState } from "./question-modes.ts";
 
 const STATUS: Record<string, string> = { not_started: "Not started", working: "Working", blocked: "Blocked", done: "Done", skipped: "Skipped" };
+const QUESTION_STATE: Record<QuestionState, string> = { stopped: "agent stopped until the answer", waiting: "waiting for the answer", building: "building with it" };
 
 // The dashboard as plain text, so an agent can check what the user sees.
 export function dashboardText(dashboard: Dashboard, nowMs: number): string {
@@ -44,7 +46,7 @@ export function dashboardText(dashboard: Dashboard, nowMs: number): string {
   if (dashboard.questions.open.length) {
     lines.push("", "Questions waiting");
     for (const question of dashboard.questions.open) {
-      lines.push(`  ${question.id} ${question.ticketId ? `[${question.ticketId}] ` : ""}(${question.title}): ${question.question} You recommended ${question.recommended}`);
+      lines.push(`  ${question.id} ${question.ticketId ? `[${question.ticketId}] ` : ""}(${question.title}): ${question.question} You recommended ${question.recommended}, ${QUESTION_STATE[question.state]}${question.big ? `. Big: ${question.big}` : ""}`);
       for (const option of question.options) lines.push(`      ${option.letter}) ${option.label}${option.consequence ? `: ${option.consequence}` : ""}`);
     }
   }

package/shared/whats-new.ts

@@ -0,0 +1,16 @@
+// A changelog bullet can open with a tag, like `- [Fixed] **Title.** Detail.`,
+// that says what kind of change it is. The parser and the dialog both read
+// this table. `tone` is the hue the dialog colors the tag with.
+export const NOTE_KINDS = {
+  new: { label: "New", tone: "green" },
+  improved: { label: "Improved", tone: "violet" },
+  fixed: { label: "Fixed", tone: "amber" },
+} as const;
+
+export type NoteTone = (typeof NOTE_KINDS)[NoteKind]["tone"];
+
+export type NoteKind = keyof typeof NOTE_KINDS;
+
+export type WhatsNewNote = { kind?: NoteKind; title?: string; body: string };
+
+export type WhatsNew = { version: string; headline: string; notes: WhatsNewNote[] };