@stevecastaneda/paseo-progress 1.3.1 → 1.5.0

package/dist/server/cli.js

@@ -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,
@@ -20351,11 +20382,11 @@ async function installLauncher(path, platform = process.platform) {
 
 // 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 as basename2, 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";
@@ -20377,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 {
@@ -20384,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", `${basename2(real)}-${hash2}`);
+  return join4(stateRoot(home), `${basename2(real)}-${hash2}`);
 }
 var trackedLegacy = /* @__PURE__ */ new Map();
 async function legacyTracked(root, mtimeMs) {
@@ -20474,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) {
@@ -20504,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 = [];
@@ -20541,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}` : ""}`);
     }
   }
@@ -20582,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();
@@ -20691,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)}`
       };
     }
   },
@@ -20766,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");
@@ -20792,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",
@@ -20800,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}`
       };
     }
   },
@@ -20822,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}`
       };
     }
   },
@@ -21016,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;
   }
@@ -21048,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,10 @@
 import type { PluginClientContext } from "@getpaseo/plugin/client";
 import { ProgressPanel } from "./client/panel";
 import { contributePills, progressPanel } from "./client/pills";
+import { QuestionSettings } from "./client/settings";
+import { ProgressLanguageProvider } from "./client/language";
+
+const SETTINGS_ID = "settings";
 
 export default function contribute(client: PluginClientContext) {
   const stopPills = contributePills(client);
@@ -11,7 +15,7 @@ export default function contribute(client: PluginClientContext) {
     icon: "ListChecks",
     context: "workspace",
     locations: [panel.location],
-    Component: ProgressPanel,
+    Component: (props) => <ProgressLanguageProvider><ProgressPanel {...props} openSettings={() => client.openSettings(SETTINGS_ID)} /></ProgressLanguageProvider>,
   });
   const stopCommand = client.addCommandCenterItem({
     id: "open-progress",
@@ -25,7 +29,15 @@ export default function contribute(client: PluginClientContext) {
     },
   });
 
+  const stopSettings = client.addSettingsScreen({
+    id: SETTINGS_ID,
+    title: "Settings",
+    icon: "Settings",
+    Component: (props) => <ProgressLanguageProvider><QuestionSettings {...props} /></ProgressLanguageProvider>,
+  });
+
   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 { displaySettings, questionSettings } from "./shared/settings";
 
 export default function contribute(server: PluginServerContext) {
   server.handle(getDashboard, handleGetDashboard);
@@ -19,5 +22,12 @@ 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(() => {});
+  server.registerSettings(displaySettings);
+  const mirror = mirrorQuestionMode(server.registerSettings(questionSettings));
+  return mirror.stop;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stevecastaneda/paseo-progress",
-  "version": "1.3.1",
+  "version": "1.5.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",

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));

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/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.