@stevecastaneda/paseo-progress 1.3.0 → 1.4.0

package/dist/server/cli.js

@@ -2007,8 +2007,8 @@ function emoji() {
 }
 var ipv4 = /^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$/;
 var ipv6 = /^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:))$/;
-var mac = (delimiter2) => {
-  const escapedDelim = escapeRegex(delimiter2 ?? ":");
+var mac = (delimiter) => {
+  const escapedDelim = escapeRegex(delimiter ?? ":");
   return new RegExp(`^(?:[0-9A-F]{2}${escapedDelim}){5}[0-9A-F]{2}$|^(?:[0-9a-f]{2}${escapedDelim}){5}[0-9a-f]{2}$`);
 };
 var cidrv4 = /^((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3}(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\/([0-9]|[1-2][0-9]|3[0-2])$/;
@@ -19678,6 +19678,31 @@ function date4(params) {
   return _coercedDate(ZodDate, params);
 }
 
+// shared/question-modes.ts
+var QUESTION_MODES = ["stop", "work-around", "keep-building"];
+var DEFAULT_QUESTION_MODE = "work-around";
+var 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.";
+var QUESTION_MODE_RULES = {
+  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"
+  }
+};
+
 // shared/events.ts
 var PROGRESS_FILE_NAME = "progress.jsonl";
 var PANEL_OPENED_NAME = "progress-panel-opened";
@@ -19737,9 +19762,11 @@ var eventSchema = external_exports.discriminatedUnion("type", [
   // A blocker that is not a ticket status, like a failing external service.
   external_exports.object({ ...base, type: external_exports.literal("stuck.set"), id: text, reason: text, ticket: text.optional() }),
   external_exports.object({ ...base, type: external_exports.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`.
   external_exports.object({
     ...base,
     type: external_exports.literal("question.ask"),
@@ -19749,6 +19776,8 @@ var eventSchema = external_exports.discriminatedUnion("type", [
     options: external_exports.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: external_exports.enum(QUESTION_MODES).optional(),
+    big: text.optional(),
     default: text.optional(),
     waits: external_exports.boolean().optional(),
     background: text.optional(),
@@ -19764,7 +19793,7 @@ var eventSchema = external_exports.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: external_exports.boolean().optional()
   }),
   // Adds detail to an open question; its reference and default stay.
@@ -19918,6 +19947,8 @@ function reduceProgress(parsed, now) {
           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 !== void 0 && !event.waits ? "building" : "waiting",
+          big: event.big,
           background: event.background,
           files: event.files ?? [],
           raisedBy: event.raisedBy,
@@ -20250,7 +20281,7 @@ function findRoot(cwd) {
 
 // server/launcher.ts
 import { chmod, mkdir as mkdir3, readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
-import { delimiter, dirname as dirname2, join as join3 } from "node:path";
+import { basename, dirname as dirname2, join as join3, posix, win32 } from "node:path";
 var PLUGIN_ID = "progress";
 function launcherScript() {
   return `#!/usr/bin/env node
@@ -20266,11 +20297,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}");
@@ -20295,29 +20343,50 @@ process.exit(run.status === null ? 1 : run.status);
 `;
 }
 var MARKER = `Written by the ${PLUGIN_ID} Paseo plugin`;
-async function launcherState(path) {
-  const current = await readFile2(path, "utf8").catch(() => null);
+function launcherFiles(path, platform) {
+  const files = [{ path, content: launcherScript() }];
+  if (platform === "win32") {
+    files.push({ path: `${path}.cmd`, content: `@echo off\r
+rem ${MARKER}. Lets PowerShell and cmd run ${basename(path)}.\r
+node "%~dp0${basename(path)}" %*\r
+exit /b %errorlevel%\r
+` });
+  }
+  return files;
+}
+async function fileState(file2) {
+  const current = await readFile2(file2.path, "utf8").catch(() => null);
   if (current === null) return "missing";
-  if (current === launcherScript()) return "current";
+  if (current === file2.content) return "current";
   return current.includes(MARKER) ? "outdated" : "foreign";
 }
-async function installLauncher(path) {
-  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 mkdir3(dirname2(path), { recursive: true });
-  await writeFile2(path, launcherScript());
-  await chmod(path, 493);
-  return true;
+async function fileStates(path, platform) {
+  const files = launcherFiles(path, platform);
+  const states = await Promise.all(files.map(fileState));
+  return files.map((file2, index) => ({ ...file2, state: states[index] }));
+}
+async function installLauncher(path, platform = process.platform) {
+  const files = await fileStates(path, platform);
+  const foreign = files.find((file2) => file2.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 file2 of files) {
+    if (file2.state === "current") continue;
+    await mkdir3(dirname2(file2.path), { recursive: true });
+    await writeFile2(file2.path, file2.content);
+    await chmod(file2.path, 493);
+    wrote = true;
+  }
+  return wrote;
 }
 
 // server/store.ts
 import { execFile } from "node:child_process";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { realpathSync } from "node:fs";
-import { appendFile as appendFile2, mkdir as mkdir4, readdir, readFile as readFile3, rm as rm2, rmdir, stat as stat3, writeFile as writeFile3 } from "node:fs/promises";
+import { appendFile as appendFile2, mkdir as mkdir4, readdir, readFile as readFile3, rename, rm as rm2, rmdir, stat as stat3, writeFile as writeFile3 } from "node:fs/promises";
 import { homedir } from "node:os";
-import { basename, join as join4, normalize, resolve as resolve2 } from "node:path";
+import { basename as basename2, dirname as dirname3, join as join4, normalize, resolve as resolve2 } from "node:path";
 import { promisify } from "node:util";
 var LOCK_NAME2 = `${PROGRESS_FILE_NAME}.lock`;
 var SAVE_RUNS_KEY = "paseo-progress.saveRuns";
@@ -20339,6 +20408,9 @@ async function git(cwd, args) {
 async function exists2(path) {
   return Boolean(await stat3(path).catch(() => null));
 }
+function stateRoot(home = homedir()) {
+  return join4(home, ".local", "state", "paseo-progress");
+}
 function outsideDirectory(root, home = homedir()) {
   let real = root;
   try {
@@ -20346,7 +20418,7 @@ function outsideDirectory(root, home = homedir()) {
   } catch {
   }
   const hash2 = createHash("sha1").update(real).digest("hex").slice(0, 8);
-  return join4(home, ".local", "state", "paseo-progress", `${basename(real)}-${hash2}`);
+  return join4(stateRoot(home), `${basename2(real)}-${hash2}`);
 }
 var trackedLegacy = /* @__PURE__ */ new Map();
 async function legacyTracked(root, mtimeMs) {
@@ -20436,6 +20508,22 @@ async function saveRunCopy(root, text2) {
 `);
 }
 
+// server/question-mode.ts
+import { readFile as readFile4, rm as rm3 } from "node:fs/promises";
+import { homedir as homedir2 } from "node:os";
+import { join as join5 } from "node:path";
+var mirrorSchema = external_exports.object({ questionMode: external_exports.enum(QUESTION_MODES) });
+function questionModePath(home = homedir2()) {
+  return join5(stateRoot(home), "settings.json");
+}
+async function readQuestionMode(home = homedir2()) {
+  try {
+    return mirrorSchema.parse(JSON.parse(await readFile4(questionModePath(home), "utf8"))).questionMode;
+  } catch {
+    return DEFAULT_QUESTION_MODE;
+  }
+}
+
 // shared/format.ts
 var MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
 function formatMinutes(totalMin) {
@@ -20466,6 +20554,7 @@ function minutesSince(iso, nowMs) {
 
 // shared/show.ts
 var STATUS = { not_started: "Not started", working: "Working", blocked: "Blocked", done: "Done", skipped: "Skipped" };
+var QUESTION_STATE = { stopped: "agent stopped until the answer", waiting: "waiting for the answer", building: "building with it" };
 function dashboardText(dashboard, nowMs) {
   if (!dashboard.run && !dashboard.tickets.length) return 'No run yet. Start one with: paseo-progress start "<title>"';
   const lines = [];
@@ -20503,7 +20592,7 @@ function dashboardText(dashboard, nowMs) {
   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}` : ""}`);
     }
   }
@@ -20544,10 +20633,13 @@ function imageMimeType(path) {
 }
 
 // server/cli.ts
-import { homedir as homedir2 } from "node:os";
+import { homedir as homedir3 } from "node:os";
 var UsageError = class extends Error {
 };
 var USAGE_NAME = "paseo-progress";
+function modeLine(mode) {
+  return `Question mode: ${QUESTION_MODE_RULES[mode].label}, set by the user in Paseo's Settings. For each question, do what "question ask" prints.`;
+}
 function required2(value, name) {
   if (!value?.trim()) throw new UsageError(`Missing ${name}.`);
   return value.trim();
@@ -20653,11 +20745,12 @@ var commands = {
     usage: `start "<title>" [--subtitle <text>] [--item-label <word>]`,
     summary: "Start a new run. Earlier runs stay in the file but leave the dashboard.",
     options: { subtitle: { type: "string" }, "item-label": { type: "string" } },
-    run({ positionals, values }) {
+    run({ positionals, values, mode }) {
       const title = required2(positionals[0], "run title");
       return {
         event: { type: "run.start", title, subtitle: stringOption(values.subtitle), itemLabel: stringOption(values["item-label"]) },
-        message: `Started run: ${title}`
+        message: `Started run: ${title}
+${modeLine(mode)}`
       };
     }
   },
@@ -20728,17 +20821,18 @@ var commands = {
     }
   },
   "question ask": {
-    usage: `question ask "<short title>" "<question>" [--option "A=<label> | <consequence>" ...] --recommend <letter or word> [--background <text>] [--file <path or http(s) URL>[=<label>] ...] [--raised-by <text>] [--ticket <id>]`,
-    summary: "Ask the user a question. Prints its reference (Q1, Q2, ...). --recommend is the option you would pick. Build no option before the answer: work only on what the question doesn't affect, and if nothing else is left, stop and wait.",
+    usage: `question ask "<short title>" "<question>" [--option "A=<label> | <consequence>" ...] --recommend <letter or word> [--big "<why, in a few plain words>"] [--background <text>] [--file <path or http(s) URL>[=<label>] ...] [--raised-by <text>] [--ticket <id>]`,
+    summary: "Ask the user a question. Prints its reference (Q1, Q2, ...) and what to do until the answer, which depends on the question mode the user picks in Paseo's Settings: Stop (stop all work until an answer), Work around (build nothing the question affects, work on the rest), or Keep building (build your recommendation now, change course if the user picks another). --recommend is the option you would pick. Add --big with the reason when the question is big; it only changes what you do in Keep building, where a big question holds like Work around. A question is big when one of these holds, and only then: (1) building your recommendation before the answer would mean something leaves this computer: pushing, publishing, deploying, changing live data, sending messages, spending money; (2) the answer sets something people or programs outside this repo will rely on: a saved data format, a database schema, a public API, command or setting name, or removing or renaming something people already use; (3) most of the tickets or steps still ahead would be built on the answer. Every other question is small, large code changes included. When you can't name the test it meets, it's small. Name the test in the --big reason.",
     options: {
       option: { type: "string", multiple: true },
       recommend: { type: "string" },
+      big: { type: "string" },
       background: { type: "string" },
       file: { type: "string", multiple: true },
       "raised-by": { type: "string" },
       ticket: { type: "string" }
     },
-    run({ positionals, values, state, cwd, root }) {
+    run({ positionals, values, state, cwd, root, mode }) {
       const title = required2(positionals[0], "short title");
       const ticket = values.ticket === void 0 ? void 0 : existingTicket(state, stringOption(values.ticket));
       const question = required2(positionals[1], "question");
@@ -20754,6 +20848,9 @@ var commands = {
         recommend = recommend.toUpperCase();
       }
       const id = state.nextIds.question;
+      const big = values.big === void 0 ? void 0 : required2(stringOption(values.big), "--big reason (why the question is big)");
+      const rules = QUESTION_MODE_RULES[mode];
+      const rule = `Mode: ${rules.label}. ${rules.askRule({ recommend, big: Boolean(big) })}`;
       return {
         event: {
           type: "question.ask",
@@ -20762,12 +20859,14 @@ var commands = {
           question,
           options: options.length ? options : void 0,
           recommend,
+          mode,
+          big,
           background: stringOption(values.background),
           files: listOption(values.file).length ? listOption(values.file).map((raw) => parseFile(raw, cwd, root)) : void 0,
           raisedBy: stringOption(values["raised-by"]),
           ticket: ticket?.id
         },
-        message: `Asked ${id} (${title}). You recommend ${recommend}. Build no option before the answer: work only on what it doesn't affect, and if nothing else is left, stop and wait.`
+        message: `Asked ${id} (${title}). You recommend ${recommend}. ${rule}`
       };
     }
   },
@@ -20784,9 +20883,11 @@ var commands = {
         if (letters.length && !letters.includes(choice)) throw new UsageError(`${question.id} has options ${letters.join(", ")}, not ${choice}.`);
       }
       const asRecommended = choice.toLowerCase() === question.recommended.toLowerCase();
+      const built = question.state === "building";
+      const next = !built ? "Build it now." : asRecommended ? "Carry on with it." : `Undo the work built on your recommendation and build ${choice} before anything else.`;
       return {
-        event: { type: "question.answer", id: question.id, choice, words: stringOption(values.words) },
-        message: `Answered ${question.id}: ${choice}${asRecommended ? " (as you recommended)" : ` (not your recommendation, ${question.recommended})`}. Build it now.`
+        event: { type: "question.answer", id: question.id, choice, words: stringOption(values.words), changedCourse: built && !asRecommended ? true : void 0 },
+        message: `Answered ${question.id}: ${choice}${asRecommended ? " (as you recommended)" : ` (not your recommendation, ${question.recommended})`}. ${next}`
       };
     }
   },
@@ -20978,11 +21079,12 @@ ${INSTALL_SUMMARY}`);
       const { dashboard } = await readProgress(store.directory, now());
       const added = addedByOthersText(addedByOthers(await readLatestRun(store.directory), dashboard, options.agentId), dashboard);
       out(`Worktree: ${root}
+${modeLine(await readQuestionMode())}
 
 ${dashboardText(dashboard, now().getTime())}${added}`);
       return 0;
     }
-    const target = resolve3(options.cwd, (argv[1] ?? DEFAULT_LAUNCHER).replace(/^~(?=$|\/)/, homedir2()));
+    const target = resolve3(options.cwd, (argv[1] ?? DEFAULT_LAUNCHER).replace(/^~(?=$|\/)/, homedir3()));
     out(await installLauncher(target) ? `Installed the launcher at ${target}` : `The launcher at ${target} is already current`);
     return 0;
   }
@@ -21010,12 +21112,13 @@ ${command.summary}`);
     }
     const root = findRoot(options.cwd);
     const store = await findStore(root);
+    const mode = await readQuestionMode();
     const message = await appendProgress(store.directory, now, (state) => {
       const finished = state.dashboard.run?.finished;
       if (finished && command !== commands.start) {
         throw new UsageError(`The run "${state.dashboard.run.title}" is finished. Start new work with: ${USAGE_NAME} start "<title>"`);
       }
-      const { event, message: message2 } = command.run({ positionals: parsed.positionals, values: parsed.values, state, cwd: options.cwd, root });
+      const { event, message: message2 } = command.run({ positionals: parsed.positionals, values: parsed.values, state, cwd: options.cwd, root, mode });
       const added = command === commands.start ? "" : addedByOthersText(addedByOthers(state.events, state.dashboard, options.agentId), state.dashboard);
       return { event: { ...event, by: options.agentId }, result: `${message2}${added}` };
     }, (text2) => saveRunCopy(root, text2));

package/index.client.tsx

@@ -1,6 +1,9 @@
 import type { PluginClientContext } from "@getpaseo/plugin/client";
 import { ProgressPanel } from "./client/panel";
 import { contributePills, progressPanel } from "./client/pills";
+import { QuestionSettings } from "./client/settings";
+
+const SETTINGS_ID = "settings";
 
 export default function contribute(client: PluginClientContext) {
   const stopPills = contributePills(client);
@@ -11,7 +14,7 @@ export default function contribute(client: PluginClientContext) {
     icon: "ListChecks",
     context: "workspace",
     locations: [panel.location],
-    Component: ProgressPanel,
+    Component: (props) => <ProgressPanel {...props} openSettings={() => client.openSettings(SETTINGS_ID)} />,
   });
   const stopCommand = client.addCommandCenterItem({
     id: "open-progress",
@@ -25,7 +28,15 @@ export default function contribute(client: PluginClientContext) {
     },
   });
 
+  const stopSettings = client.addSettingsScreen({
+    id: SETTINGS_ID,
+    title: "Settings",
+    icon: "Settings",
+    Component: QuestionSettings,
+  });
+
   return () => {
+    void stopSettings();
     void stopPanel();
     void stopCommand();
     stopPills();

package/index.server.ts

@@ -2,8 +2,11 @@ import type { PluginServerContext } from "@getpaseo/plugin/server";
 import { handleGetAttention, handleGetDashboard, handleListFolders, handleMarkPanelOpened, handleSetHistoryFolder } from "./server/dashboard";
 import { handleInstallLauncher, handleLauncherStatus } from "./server/launcher";
 import { handleCanOpenOnHost, handleOpenDeliverable, handlePreviewDeliverable, handleReadDeliverablePiece } from "./server/open";
+import { mirrorQuestionMode } from "./server/question-mode";
 import { handleInstallSkill, handleSkillStatus } from "./server/skill";
-import { canOpenOnHost, getAttention, getDashboard, getLauncherStatus, getSkillStatus, installLauncher, installSkill, listFolders, markPanelOpened, openDeliverable, previewDeliverable, readDeliverablePiece, setHistoryFolder } from "./shared/rpc";
+import { handleDismissWhatsNew, handleGetWhatsNew } from "./server/whats-new";
+import { canOpenOnHost, dismissWhatsNew, getAttention, getDashboard, getLauncherStatus, getSkillStatus, getWhatsNew, installLauncher, installSkill, listFolders, markPanelOpened, openDeliverable, previewDeliverable, readDeliverablePiece, setHistoryFolder } from "./shared/rpc";
+import { questionSettings } from "./shared/settings";
 
 export default function contribute(server: PluginServerContext) {
   server.handle(getDashboard, handleGetDashboard);
@@ -19,5 +22,11 @@ export default function contribute(server: PluginServerContext) {
   server.handle(installSkill, handleInstallSkill);
   server.handle(listFolders, handleListFolders);
   server.handle(setHistoryFolder, handleSetHistoryFolder);
-  return () => {};
+  server.handle(getWhatsNew, handleGetWhatsNew);
+  server.handle(dismissWhatsNew, handleDismissWhatsNew);
+  // Settles a new install before any panel opens. Opening one makes a
+  // worktree folder, which would look like an earlier version's.
+  void handleGetWhatsNew().catch(() => {});
+  const mirror = mirrorQuestionMode(server.registerSettings(questionSettings));
+  return mirror.stop;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stevecastaneda/paseo-progress",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "A live progress dashboard per worktree for Paseo, drawn from a file agents write with the paseo-progress command.",
   "license": "MIT",
   "author": "Steve Castaneda",
@@ -44,6 +44,7 @@
     "test": "node --test \"*/*.test.ts\"",
     "dev": "node ../scripts/dev.mjs",
     "check:install": "node ../scripts/check-install.mjs",
+    "check:windows": "node scripts/windows-check.mjs",
     "build:cli": "rm -rf dist && esbuild server/cli.ts --bundle --platform=node --format=esm --target=node22 --outfile=dist/server/cli.js --log-level=warning",
     "prepack": "npm run build:cli",
     "postpack": "rm -rf dist"

package/paseo-plugin.json

@@ -5,7 +5,8 @@
     "images/1-panel.png",
     "images/2-ticket.png",
     "images/3-question.png",
-    "images/4-pill.png"
+    "images/4-pill.png",
+    "images/5-settings.png"
   ],
   "requirements": {
     "paseo": ">=0.11.0"

package/server/cli.ts

@@ -6,10 +6,12 @@ import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 import { isSettled, type Dashboard, type NextIds, type Ticket } from "../shared/dashboard.ts";
 import { DELIVERABLE_KINDS, TICKET_STATUSES, type FileLink, type ProgressEvent } from "../shared/events.ts";
+import { QUESTION_MODE_RULES, type QuestionMode } from "../shared/question-modes.ts";
 import { appendProgress, InvalidEvent, readLatestRun, readProgress, type EventDraft } from "./progress-file.ts";
 import { findRoot, outside } from "./paths.ts";
 import { installLauncher } from "./launcher.ts";
 import { findStore, saveRunCopy } from "./store.ts";
+import { readQuestionMode } from "./question-mode.ts";
 import { dashboardText } from "../shared/show.ts";
 import { formatMinutes } from "../shared/format.ts";
 import { imageMimeType } from "../shared/attachments.ts";
@@ -34,11 +36,15 @@ interface Command {
   usage: string;
   summary: string;
   options?: Record<string, { type: "string" | "boolean"; multiple?: boolean }>;
-  run(args: { positionals: string[]; values: Record<string, string | boolean | Array<string | boolean> | undefined>; state: State; cwd: string; root: string }): { event: EventDraft; message: string };
+  run(args: { positionals: string[]; values: Record<string, string | boolean | Array<string | boolean> | undefined>; state: State; cwd: string; root: string; mode: QuestionMode }): { event: EventDraft; message: string };
 }
 
 const USAGE_NAME = "paseo-progress";
 
+function modeLine(mode: QuestionMode): string {
+  return `Question mode: ${QUESTION_MODE_RULES[mode].label}, set by the user in Paseo's Settings. For each question, do what "question ask" prints.`;
+}
+
 function required(value: string | undefined, name: string): string {
   if (!value?.trim()) throw new UsageError(`Missing ${name}.`);
   return value.trim();
@@ -168,11 +174,11 @@ const commands: Record<string, Command> = {
     usage: `start "<title>" [--subtitle <text>] [--item-label <word>]`,
     summary: "Start a new run. Earlier runs stay in the file but leave the dashboard.",
     options: { subtitle: { type: "string" }, "item-label": { type: "string" } },
-    run({ positionals, values }) {
+    run({ positionals, values, mode }) {
       const title = required(positionals[0], "run title");
       return {
         event: { type: "run.start", title, subtitle: stringOption(values.subtitle), itemLabel: stringOption(values["item-label"]) },
-        message: `Started run: ${title}`,
+        message: `Started run: ${title}\n${modeLine(mode)}`,
       };
     },
   },
@@ -244,17 +250,18 @@ const commands: Record<string, Command> = {
     },
   },
   "question ask": {
-    usage: `question ask "<short title>" "<question>" [--option "A=<label> | <consequence>" ...] --recommend <letter or word> [--background <text>] [--file <path or http(s) URL>[=<label>] ...] [--raised-by <text>] [--ticket <id>]`,
-    summary: "Ask the user a question. Prints its reference (Q1, Q2, ...). --recommend is the option you would pick. Build no option before the answer: work only on what the question doesn't affect, and if nothing else is left, stop and wait.",
+    usage: `question ask "<short title>" "<question>" [--option "A=<label> | <consequence>" ...] --recommend <letter or word> [--big "<why, in a few plain words>"] [--background <text>] [--file <path or http(s) URL>[=<label>] ...] [--raised-by <text>] [--ticket <id>]`,
+    summary: "Ask the user a question. Prints its reference (Q1, Q2, ...) and what to do until the answer, which depends on the question mode the user picks in Paseo's Settings: Stop (stop all work until an answer), Work around (build nothing the question affects, work on the rest), or Keep building (build your recommendation now, change course if the user picks another). --recommend is the option you would pick. Add --big with the reason when the question is big; it only changes what you do in Keep building, where a big question holds like Work around. A question is big when one of these holds, and only then: (1) building your recommendation before the answer would mean something leaves this computer: pushing, publishing, deploying, changing live data, sending messages, spending money; (2) the answer sets something people or programs outside this repo will rely on: a saved data format, a database schema, a public API, command or setting name, or removing or renaming something people already use; (3) most of the tickets or steps still ahead would be built on the answer. Every other question is small, large code changes included. When you can't name the test it meets, it's small. Name the test in the --big reason.",
     options: {
       option: { type: "string", multiple: true },
       recommend: { type: "string" },
+      big: { type: "string" },
       background: { type: "string" },
       file: { type: "string", multiple: true },
       "raised-by": { type: "string" },
       ticket: { type: "string" },
     },
-    run({ positionals, values, state, cwd, root }) {
+    run({ positionals, values, state, cwd, root, mode }) {
       const title = required(positionals[0], "short title");
       const ticket = values.ticket === undefined ? undefined : existingTicket(state, stringOption(values.ticket));
       const question = required(positionals[1], "question");
@@ -270,6 +277,9 @@ const commands: Record<string, Command> = {
         recommend = recommend.toUpperCase();
       }
       const id = state.nextIds.question;
+      const big = values.big === undefined ? undefined : required(stringOption(values.big), "--big reason (why the question is big)");
+      const rules = QUESTION_MODE_RULES[mode];
+      const rule = `Mode: ${rules.label}. ${rules.askRule({ recommend, big: Boolean(big) })}`;
       return {
         event: {
           type: "question.ask",
@@ -278,12 +288,14 @@ const commands: Record<string, Command> = {
           question,
           options: options.length ? options : undefined,
           recommend,
+          mode,
+          big,
           background: stringOption(values.background),
           files: listOption(values.file).length ? listOption(values.file).map((raw) => parseFile(raw, cwd, root)) : undefined,
           raisedBy: stringOption(values["raised-by"]),
           ticket: ticket?.id,
         },
-        message: `Asked ${id} (${title}). You recommend ${recommend}. Build no option before the answer: work only on what it doesn't affect, and if nothing else is left, stop and wait.`,
+        message: `Asked ${id} (${title}). You recommend ${recommend}. ${rule}`,
       };
     },
   },
@@ -300,9 +312,13 @@ const commands: Record<string, Command> = {
         if (letters.length && !letters.includes(choice)) throw new UsageError(`${question.id} has options ${letters.join(", ")}, not ${choice}.`);
       }
       const asRecommended = choice.toLowerCase() === question.recommended.toLowerCase();
+      const built = question.state === "building";
+      const next = !built ? "Build it now."
+        : asRecommended ? "Carry on with it."
+        : `Undo the work built on your recommendation and build ${choice} before anything else.`;
       return {
-        event: { type: "question.answer", id: question.id, choice, words: stringOption(values.words) },
-        message: `Answered ${question.id}: ${choice}${asRecommended ? " (as you recommended)" : ` (not your recommendation, ${question.recommended})`}. Build it now.`,
+        event: { type: "question.answer", id: question.id, choice, words: stringOption(values.words), changedCourse: built && !asRecommended ? true : undefined },
+        message: `Answered ${question.id}: ${choice}${asRecommended ? " (as you recommended)" : ` (not your recommendation, ${question.recommended})`}. ${next}`,
       };
     },
   },
@@ -496,7 +512,7 @@ export async function runCli(argv: string[], options: CliOptions): Promise<numbe
       const store = await findStore(root);
       const { dashboard } = await readProgress(store.directory, now());
       const added = addedByOthersText(addedByOthers(await readLatestRun(store.directory), dashboard, options.agentId), dashboard);
-      out(`Worktree: ${root}\n\n${dashboardText(dashboard, now().getTime())}${added}`);
+      out(`Worktree: ${root}\n${modeLine(await readQuestionMode())}\n\n${dashboardText(dashboard, now().getTime())}${added}`);
       return 0;
     }
     const target = resolve(options.cwd, (argv[1] ?? DEFAULT_LAUNCHER).replace(/^~(?=$|\/)/, homedir()));
@@ -523,12 +539,13 @@ export async function runCli(argv: string[], options: CliOptions): Promise<numbe
     }
     const root = findRoot(options.cwd);
     const store = await findStore(root);
+    const mode = await readQuestionMode();
     const message = await appendProgress(store.directory, now, (state) => {
       const finished = state.dashboard.run?.finished;
       if (finished && command !== commands.start) {
         throw new UsageError(`The run "${state.dashboard.run!.title}" is finished. Start new work with: ${USAGE_NAME} start "<title>"`);
       }
-      const { event, message } = command.run({ positionals: parsed.positionals, values: parsed.values, state, cwd: options.cwd, root });
+      const { event, message } = command.run({ positionals: parsed.positionals, values: parsed.values, state, cwd: options.cwd, root, mode });
       const added = command === commands.start ? "" : addedByOthersText(addedByOthers(state.events, state.dashboard, options.agentId), state.dashboard);
       return { event: { ...event, by: options.agentId }, result: `${message}${added}` };
     }, (text) => saveRunCopy(root, text));