@stevecastaneda/paseo-progress 0.2.1 → 0.3.0

package/server/cli.ts

@@ -4,9 +4,9 @@ import { realpathSync, statSync } from "node:fs";
 import { relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
-import { isSettled, type Dashboard, type NextIds } from "../shared/dashboard.ts";
-import { DELIVERABLE_KINDS, TICKET_STATUSES } from "../shared/events.ts";
-import { appendProgress, InvalidEvent, readProgress, type EventDraft } from "./progress-file.ts";
+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 { 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";
@@ -18,6 +18,8 @@ export interface CliOptions {
   cwd: string;
   now?: () => Date;
   out?: (line: string) => void;
+  // The Paseo agent running the command, recorded on each event it writes.
+  agentId?: string;
 }
 
 class UsageError extends Error {}
@@ -136,6 +138,30 @@ function unfinishedWork(dashboard: Dashboard): string[] {
   ].filter(Boolean);
 }
 
+// Tickets another session added since this agent last wrote to the run, still
+// to do. Nothing until the agent has written to the run: it reads `show` first.
+function addedByOthers(events: ProgressEvent[], dashboard: Dashboard, agentId: string | undefined): Ticket[] {
+  if (!agentId) return [];
+  const since = events.findLastIndex((event) => event.by === agentId);
+  if (since === -1) return [];
+  const added = new Set(events.slice(since + 1).flatMap((event) => (event.type === "ticket.add" && event.by !== agentId ? [event.id] : [])));
+  return dashboard.tickets.filter((ticket) => added.has(ticket.id) && !isSettled(ticket));
+}
+
+function addedByOthersText(tickets: Ticket[], dashboard: Dashboard): string {
+  if (!tickets.length) return "";
+  const label = (dashboard.run?.itemLabel ?? "Ticket").toLowerCase();
+  const one = tickets.length === 1;
+  // Starts with a blank line, to follow the command's own output.
+  return [
+    "",
+    "",
+    `Another session added ${one ? `a ${label}` : `${tickets.length} ${label}s`} since your last update:`,
+    ...tickets.map((ticket) => `  ${ticket.id}  ${ticket.title}`),
+    `${one ? "It is" : "They are"} part of this run: work ${one ? "it" : "them"} in order after your current ${label}.`,
+  ].join("\n");
+}
+
 const commands: Record<string, Command> = {
   start: {
     usage: `start "<title>" [--subtitle <text>] [--item-label <word>]`,
@@ -161,26 +187,27 @@ const commands: Record<string, Command> = {
     },
   },
   "ticket add": {
-    usage: `ticket add "<title>" --estimate <minutes> [--status <status>] [--waits-for <id>]`,
-    summary: "Add a ticket. Prints its id (T01, T02, ...). --waits-for names a ticket it can't start before; that is the order of work, not a blocker.",
-    options: { estimate: { type: "string" }, status: { type: "string" }, "waits-for": { type: "string" } },
-    run({ positionals, values, state }) {
+    usage: `ticket add "<title>" --estimate <minutes> [--status <status>] [--waits-for <id>] [--source <path or http(s) URL>[=<label>]]`,
+    summary: "Add a ticket. Prints its id (T01, T02, ...). --waits-for names a ticket it can't start before; that is the order of work, not a blocker. --source is where the ticket is written up, like its spec file or issue link.",
+    options: { estimate: { type: "string" }, status: { type: "string" }, "waits-for": { type: "string" }, source: { type: "string" } },
+    run({ positionals, values, state, cwd, root }) {
       const waitsFor = values["waits-for"] === undefined ? undefined : existingTicket(state, stringOption(values["waits-for"])).id;
       const title = required(positionals[0], "ticket title");
       const estimateMin = minutesOption(values.estimate, "estimate");
       if (estimateMin === undefined) throw new UsageError("Missing --estimate <minutes>.");
+      const source = values.source === undefined ? undefined : parseFile(String(values.source), cwd, root);
       const id = state.nextIds.ticket;
       return {
-        event: { type: "ticket.add", id, title, estimateMin, status: statusOption(values.status), waitsFor },
-        message: `Added ${id}: ${title} (${estimateMin} min)${waitsFor ? `, waits for ${waitsFor}` : ""}`,
+        event: { type: "ticket.add", id, title, estimateMin, status: statusOption(values.status), waitsFor, source },
+        message: `Added ${id}: ${title} (${estimateMin} min)${waitsFor ? `, waits for ${waitsFor}` : ""}${source ? `, source ${source.path ?? source.url}` : ""}`,
       };
     },
   },
   "ticket update": {
-    usage: `ticket update <id> [--status <status>] [--stage <name>] [--title <text>] [--estimate <minutes>] [--note <text>] [--waits-for <id>]`,
-    summary: `Change a ticket. Statuses: ${TICKET_STATUSES.join(", ")}. --stage names the step in progress, like Build or Fixes ("" clears it). --waits-for names a ticket it can't start before ("" clears it); waiting is not stuck, so don't mark it blocked for that.`,
-    options: { status: { type: "string" }, stage: { type: "string" }, title: { type: "string" }, estimate: { type: "string" }, note: { type: "string" }, "waits-for": { type: "string" } },
-    run({ positionals, values, state }) {
+    usage: `ticket update <id> [--status <status>] [--stage <name>] [--title <text>] [--estimate <minutes>] [--note <text>] [--waits-for <id>] [--source <path or http(s) URL>[=<label>]]`,
+    summary: `Change a ticket. Statuses: ${TICKET_STATUSES.join(", ")}. --stage names the step in progress, like Build or Fixes ("" clears it). --waits-for names a ticket it can't start before ("" clears it); waiting is not stuck, so don't mark it blocked for that. --source is where the ticket is written up ("" clears it).`,
+    options: { status: { type: "string" }, stage: { type: "string" }, title: { type: "string" }, estimate: { type: "string" }, note: { type: "string" }, "waits-for": { type: "string" }, source: { type: "string" } },
+    run({ positionals, values, state, cwd, root }) {
       const ticket = existingTicket(state, positionals[0]);
       const rawWaitsFor = values["waits-for"] === undefined ? undefined : String(values["waits-for"]).trim();
       const waitsFor = rawWaitsFor === undefined || rawWaitsFor === "" ? rawWaitsFor : existingTicket(state, rawWaitsFor).id;
@@ -199,10 +226,12 @@ const commands: Record<string, Command> = {
         stage: stringOption(values.stage),
         note: stringOption(values.note),
         waitsFor,
+        source: values.source === undefined ? undefined : String(values.source).trim() === "" ? "" as const : parseFile(String(values.source), cwd, root),
       };
       const changes = Object.entries(event).filter(([key, value]) => key !== "type" && key !== "id" && value !== undefined);
-      if (!changes.length) throw new UsageError("Nothing to change. Pass --status, --stage, --title, --estimate, --note, or --waits-for.");
-      return { event, message: `Updated ${ticket.id}: ${changes.map(([key, value]) => `${key} ${value}`).join(", ")}` };
+      if (!changes.length) throw new UsageError("Nothing to change. Pass --status, --stage, --title, --estimate, --note, --waits-for, or --source.");
+      const shown = (value: unknown) => (typeof value === "object" ? (value as FileLink).path ?? (value as FileLink).url : value);
+      return { event, message: `Updated ${ticket.id}: ${changes.map(([key, value]) => `${key} ${shown(value)}`).join(", ")}` };
     },
   },
   "ticket remove": {
@@ -214,12 +243,11 @@ const commands: Record<string, Command> = {
     },
   },
   "question ask": {
-    usage: `question ask "<short title>" "<question>" [--option "A=<label> | <consequence>" ...] --default <letter or word> [--waits] [--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, ...). Keep working on the default until it is answered, unless --waits: then the default is only a suggestion and you wait.",
+    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.",
     options: {
       option: { type: "string", multiple: true },
-      default: { type: "string" },
-      waits: { type: "boolean" },
+      recommend: { type: "string" },
       background: { type: "string" },
       file: { type: "string", multiple: true },
       "raised-by": { type: "string" },
@@ -233,12 +261,12 @@ const commands: Record<string, Command> = {
       const letters = options.map((option) => option.letter);
       const duplicate = letters.find((letter, index) => letters.indexOf(letter) !== index);
       if (duplicate) throw new UsageError(`Option ${duplicate} is given twice.`);
-      let fallback = required(stringOption(values.default), "--default");
+      let recommend = required(stringOption(values.recommend), "--recommend (the option you would pick)");
       if (options.length) {
-        if (!/^[A-Za-z]$/.test(fallback) || !letters.includes(fallback.toUpperCase())) {
-          throw new UsageError(`--default must be one of the option letters: ${letters.join(", ")}.`);
+        if (!/^[A-Za-z]$/.test(recommend) || !letters.includes(recommend.toUpperCase())) {
+          throw new UsageError(`--recommend must be one of the option letters: ${letters.join(", ")}.`);
         }
-        fallback = fallback.toUpperCase();
+        recommend = recommend.toUpperCase();
       }
       const id = state.nextIds.question;
       return {
@@ -248,14 +276,13 @@ const commands: Record<string, Command> = {
           title,
           question,
           options: options.length ? options : undefined,
-          default: fallback,
-          waits: values.waits === true ? true : undefined,
+          recommend,
           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}). Default: ${fallback}${values.waits === true ? " (waiting for the answer)" : ""}`,
+        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.`,
       };
     },
   },
@@ -271,10 +298,10 @@ const commands: Record<string, Command> = {
         choice = choice.toUpperCase();
         if (letters.length && !letters.includes(choice)) throw new UsageError(`${question.id} has options ${letters.join(", ")}, not ${choice}.`);
       }
-      const changedCourse = choice.toLowerCase() !== question.default.toLowerCase();
+      const asRecommended = choice.toLowerCase() === question.recommended.toLowerCase();
       return {
-        event: { type: "question.answer", id: question.id, choice, words: stringOption(values.words), changedCourse },
-        message: `Answered ${question.id}: ${choice}${changedCourse ? ` (differs from default ${question.default}: change course)` : " (same as the default)"}`,
+        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.`,
       };
     },
   },
@@ -466,7 +493,9 @@ export async function runCli(argv: string[], options: CliOptions): Promise<numbe
     if (first === "show") {
       const root = findRoot(options.cwd);
       const store = await findStore(root);
-      out(`Worktree: ${root}\n\n${dashboardText((await readProgress(store.directory, now())).dashboard, now().getTime())}`);
+      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}`);
       return 0;
     }
     const target = resolve(options.cwd, (argv[1] ?? DEFAULT_LAUNCHER).replace(/^~(?=$|\/)/, homedir()));
@@ -499,7 +528,8 @@ export async function runCli(argv: string[], options: CliOptions): Promise<numbe
         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 });
-      return { event, result: message };
+      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));
     out(message);
     return 0;
@@ -522,7 +552,7 @@ function isMain(): boolean {
 }
 
 if (isMain()) {
-  runCli(process.argv.slice(2), { cwd: process.cwd() }).then(
+  runCli(process.argv.slice(2), { cwd: process.cwd(), agentId: process.env.PASEO_AGENT_ID || undefined }).then(
     (code) => { process.exitCode = code; },
     (error) => {
       console.error(error instanceof Error ? error.message : error);

package/server/progress-file.ts

@@ -4,7 +4,7 @@
 // the panel's RPC handlers go through here, so they agree on how they're read.
 import { access, appendFile, mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { EMPTY_DASHBOARD, parseProgress, reduceProgress, type Dashboard, type NextIds } from "../shared/dashboard.ts";
+import { EMPTY_DASHBOARD, latestRun, parseProgress, reduceProgress, type Dashboard, type NextIds } from "../shared/dashboard.ts";
 import { EVENT_VERSION, eventSchema, PANEL_OPENED_NAME, PROGRESS_FILE_NAME, type ProgressEvent } from "../shared/events.ts";
 import { withLock } from "./lock.ts";
 
@@ -47,21 +47,28 @@ export async function readProgress(directory: string, now = new Date()): Promise
   return { configured: true, dashboard: cached.dashboard, panelOpened };
 }
 
+// The events of the latest run, oldest first.
+export async function readLatestRun(directory: string): Promise<ProgressEvent[]> {
+  return latestRun((await readParsed(directory))?.events ?? []).map(({ event }) => event);
+}
+
 // Appends the one event `write` builds from the file as it is now. Commands
 // that run at once take turns, so each sees the others' events and no two hand
 // out the same id. `write` may throw to append nothing.
 export async function appendProgress<T>(
   directory: string,
   now: () => Date,
-  write: (state: { dashboard: Dashboard; nextIds: NextIds }) => { event: EventDraft; result: T },
+  // `events` is the latest run as it is now, oldest first.
+  write: (state: { dashboard: Dashboard; nextIds: NextIds; events: ProgressEvent[] }) => { event: EventDraft; result: T },
   // Runs before the lock is released, with the whole file as it now is.
   after?: (text: string) => Promise<void>,
 ): Promise<T> {
   await mkdir(directory, { recursive: true });
   return withLock(join(directory, LOCK_NAME), async () => {
     const text = (await readText(directory)) ?? "";
-    const { dashboard, nextIds } = reduceProgress(parseProgress(text), now());
-    const { event, result } = write({ dashboard, nextIds });
+    const parsed = parseProgress(text);
+    const { dashboard, nextIds } = reduceProgress(parsed, now());
+    const { event, result } = write({ dashboard, nextIds, events: latestRun(parsed.events).map((line) => line.event) });
     const checked = eventSchema.safeParse({ v: EVENT_VERSION, ts: now().toISOString(), ...withoutUndefined(event) });
     if (!checked.success) {
       throw new InvalidEvent(checked.error.issues.map((issue) => `${issue.path.join(".") || "value"}: ${issue.message}`).join("; "));

package/shared/attachments.ts

@@ -1,14 +1,16 @@
-// Anything the user can open from the dashboard: a deliverable ("D3") or a
-// file on a question ("Q7.2", counting from 1). The panel lists them and the
-// server finds them by the same reference, so both read it from here.
-import type { Dashboard, Deliverable, Question } from "./dashboard.ts";
+// Anything the user can open from the dashboard: a deliverable ("D3"), a file
+// on a question ("Q7.2", counting from 1), or a ticket's source ("T03.source").
+// The panel lists them and the server finds them by the same reference, so both
+// read it from here.
+import type { Dashboard, Deliverable, Question, Ticket } from "./dashboard.ts";
+import type { FileLink } from "./events.ts";
 
 export interface Attachment {
   ref: string;
   title: string;
   path?: string;
   url?: string;
-  // What the agent said a deliverable is. Question files don't have one.
+  // What the agent said a deliverable is. Other attachments don't have one.
   kind?: Deliverable["kind"];
 }
 
@@ -16,13 +18,16 @@ export function deliverableAttachment(deliverable: Deliverable): Attachment {
   return { ref: deliverable.id, title: deliverable.title, path: deliverable.path, url: deliverable.url, kind: deliverable.kind };
 }
 
+function fileAttachment(ref: string, file: FileLink): Attachment {
+  return { ref, title: file.label ?? (file.path ?? file.url ?? "").replace(/[\\/]+$/, "").split(/[\\/]/).pop() ?? "", path: file.path, url: file.url };
+}
+
 export function questionAttachments(question: Question): Attachment[] {
-  return question.files.map((file, index) => ({
-    ref: `${question.id}.${index + 1}`,
-    title: file.label ?? (file.path ?? file.url ?? "").replace(/[\\/]+$/, "").split(/[\\/]/).pop() ?? "",
-    path: file.path,
-    url: file.url,
-  }));
+  return question.files.map((file, index) => fileAttachment(`${question.id}.${index + 1}`, file));
+}
+
+export function ticketSourceAttachment(ticket: Ticket): Attachment | null {
+  return ticket.source ? fileAttachment(`${ticket.id}.source`, ticket.source) : null;
 }
 
 // The attachment a reference names, or null when it names nothing.
@@ -32,6 +37,11 @@ export function findAttachment(dashboard: Dashboard, ref: string): Attachment |
     const found = [...dashboard.questions.open, ...dashboard.questions.answered].find((candidate) => candidate.id === question[1]);
     return (found && questionAttachments(found).find((attachment) => attachment.ref === ref)) ?? null;
   }
+  const ticket = ref.match(/^(.+)\.source$/);
+  if (ticket) {
+    const found = dashboard.tickets.find((candidate) => candidate.id === ticket[1]);
+    return found ? ticketSourceAttachment(found) : null;
+  }
   const deliverable = dashboard.deliverables.find((candidate) => candidate.id === ref);
   return deliverable ? deliverableAttachment(deliverable) : null;
 }

package/shared/dashboard.ts

@@ -24,6 +24,10 @@ export interface Ticket {
   // Waiting is the order of work, not a problem, so it never counts as stuck.
   waitingFor?: { id: string; title: string };
   waitsFor?: string;
+  // Where the ticket is written up: a spec file or an issue link.
+  source?: FileLink;
+  // The Paseo agent that last added or updated it, when written from Paseo.
+  agentId?: string;
   // Every status, stage and note change, starting with when it was added.
   history: TicketChange[];
 }
@@ -39,14 +43,15 @@ export interface Question {
   title: string;
   question: string;
   options: QuestionOption[];
-  default: string;
-  waits: boolean;
+  // The option the agent leans toward. Nothing is built until the user answers.
+  recommended: string;
   background?: string;
   files: FileLink[];
   raisedBy?: string;
   ticketId?: string;
   askedAt: string;
-  answer?: { choice: string; words?: string; changedCourse: boolean; at: string };
+  // `changedCourse` only on older answers, from when agents built a default before asking.
+  answer?: { choice: string; words?: string; changedCourse?: boolean; at: string };
 }
 
 export interface Deliverable {
@@ -109,7 +114,8 @@ export interface Dashboard {
   deliverables: Deliverable[];
   // Newest first.
   activity: Activity[];
-  ticker: { text: string; since: string } | null;
+  // `by` is the Paseo agent that set it, when set from Paseo.
+  ticker: { text: string; since: string; by?: string } | null;
   // Share of estimated minutes in done tickets. Skipped tickets are left out.
   // `tookMin`: once every counted ticket is done, the real time from the run's
   // start to the last one finishing.
@@ -189,16 +195,18 @@ export function isSettled(ticket: Ticket): boolean {
   return ticket.status === "done" || ticket.status === "skipped";
 }
 
+// The events from the last `run.start` on; earlier runs are ignored.
+export function latestRun(events: ParsedLine[]): ParsedLine[] {
+  const start = events.findLastIndex(({ event }) => event.type === "run.start");
+  return events.slice(Math.max(start, 0));
+}
+
 // Folds the events of the latest run into what the panel shows at `now`, how
 // long that stays true while the events don't change, and the ids new items get.
 // Everything before the last `run.start` belongs to earlier runs and is ignored.
 export function reduceProgress(parsed: { events: ParsedLine[]; issues: FileIssue[] }, now: Date): { dashboard: Dashboard; validUntil: number; nextIds: NextIds } {
   const time = clock(now);
-  let start = 0;
-  parsed.events.forEach(({ event }, index) => {
-    if (event.type === "run.start") start = index;
-  });
-  const events = parsed.events.slice(start);
+  const events = latestRun(parsed.events);
   const issues = [...parsed.issues];
   let run: Dashboard["run"] = null;
   const tickets = new Map<string, Ticket>();
@@ -229,6 +237,8 @@ export function reduceProgress(parsed: { events: ParsedLine[]; issues: FileIssue
           workingSince: event.status === "working" ? event.ts : undefined,
           history: [{ at: event.ts, status: event.status ?? "not_started" }],
           waitsFor: event.waitsFor,
+          source: event.source,
+          agentId: event.by,
         });
         break;
       case "ticket.update": {
@@ -255,6 +265,8 @@ export function reduceProgress(parsed: { events: ParsedLine[]; issues: FileIssue
         }
         if (event.note !== undefined) ticket.note = event.note || undefined;
         if (event.waitsFor !== undefined) ticket.waitsFor = event.waitsFor || undefined;
+        if (event.source !== undefined) ticket.source = event.source || undefined;
+        if (event.by) ticket.agentId = event.by;
         break;
       }
       case "ticket.remove":
@@ -266,8 +278,7 @@ export function reduceProgress(parsed: { events: ParsedLine[]; issues: FileIssue
           title: event.title,
           question: event.question,
           options: event.options ?? [],
-          default: event.default,
-          waits: event.waits ?? false,
+          recommended: event.recommend ?? event.default ?? "",
           background: event.background,
           files: event.files ?? [],
           raisedBy: event.raisedBy,
@@ -322,7 +333,7 @@ export function reduceProgress(parsed: { events: ParsedLine[]; issues: FileIssue
         if (!activity.delete(event.id)) issues.push({ line, reason: `unknown activity ${event.id}` });
         break;
       case "ticker.set":
-        ticker = { text: event.text, since: event.ts };
+        ticker = { text: event.text, since: event.ts, ...(event.by ? { by: event.by } : {}) };
         break;
       case "ticker.clear":
         ticker = null;

package/shared/events.ts

@@ -16,7 +16,8 @@ export type TicketStatus = z.infer<typeof ticketStatusSchema>;
 
 const text = z.string().trim().min(1);
 const minutes = z.number().int().positive().max(100_000);
-const base = { v: z.literal(EVENT_VERSION), ts: z.iso.datetime() };
+// `by` is the Paseo agent that wrote the event, absent when run outside Paseo.
+const base = { v: z.literal(EVENT_VERSION), ts: z.iso.datetime(), by: text.optional() };
 
 export const questionOptionSchema = z.object({
   letter: z.string().regex(/^[A-Z]$/),
@@ -54,6 +55,8 @@ export const eventSchema = z.discriminatedUnion("type", [
     status: ticketStatusSchema.optional(),
     // Another ticket in the run this one can't start until it's done.
     waitsFor: text.optional(),
+    // Where the ticket is written up: a spec file or an issue link.
+    source: fileLinkSchema.optional(),
   }),
   z.object({
     ...base,
@@ -67,12 +70,16 @@ export const eventSchema = z.discriminatedUnion("type", [
     note: z.string().trim().optional(),
     // Empty clears it.
     waitsFor: z.string().trim().optional(),
+    // Empty clears it.
+    source: z.union([fileLinkSchema, z.literal("")]).optional(),
   }),
   z.object({ ...base, type: z.literal("ticket.remove"), id: text }),
   // 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, picks `default`, and keeps working on it until answered.
+  // 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.
   z.object({
     ...base,
     type: z.literal("question.ask"),
@@ -80,9 +87,9 @@ export const eventSchema = z.discriminatedUnion("type", [
     title: text,
     question: text,
     options: z.array(questionOptionSchema).max(26).optional(),
-    // An option letter, or a word such as "Your check" when there are no options.
-    default: text,
-    // True when the agent will not act on the default and waits for the answer.
+    // The agent's pick: an option letter, or a word such as "Looks right" when there are no options.
+    recommend: text.optional(),
+    default: text.optional(),
     waits: z.boolean().optional(),
     background: text.optional(),
     files: z.array(fileLinkSchema).optional(),
@@ -97,7 +104,8 @@ export const eventSchema = z.discriminatedUnion("type", [
     choice: text,
     // The user's own words, quoted under the answer.
     words: text.optional(),
-    changedCourse: z.boolean(),
+    // Older answers: true when the agent had to undo work built on its default.
+    changedCourse: z.boolean().optional(),
   }),
   // Adds detail to an open question; its reference and default stay.
   z.object({

package/shared/format.ts

@@ -36,6 +36,13 @@ export function formatClock(iso: string): string {
   return `${MONTHS[date.getMonth()]} ${date.getDate()}, ${hours % 12 || 12}:${minutes} ${hours < 12 ? "AM" : "PM"}`;
 }
 
+// Just the time, "2:08 AM", when it falls on the same day as `nowMs`; the full
+// clock time otherwise.
+export function formatTimeOfDay(iso: string, nowMs: number): string {
+  const full = formatClock(iso);
+  return new Date(iso).toDateString() === new Date(nowMs).toDateString() ? full.slice(full.indexOf(", ") + 2) : full;
+}
+
 export function formatAgo(iso: string, nowMs: number): string {
   const minutes = (nowMs - Date.parse(iso)) / 60_000;
   return minutes < 1 ? "just now" : `${formatMinutes(minutes)} ago`;

package/shared/show.ts

@@ -39,11 +39,12 @@ export function dashboardText(dashboard: Dashboard, nowMs: number): string {
     const stage = ticket.status === "working" && ticket.stage ? `, ${ticket.stage} stage` : "";
     const status = ticket.waitingFor ? `Waiting for ${ticket.waitingFor.id}` : STATUS[ticket.status];
     lines.push(`  ${ticket.id}  ${status}${stage}  ${formatEstimate(ticket.estimateMin)}  ${ticket.title}`);
+    if (ticket.source) lines.push(`      Source: ${ticket.source.path ?? ticket.source.url}${ticket.source.label ? ` (${ticket.source.label})` : ""}`);
   }
   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} Default ${question.default}${question.waits ? ", waiting for the answer" : ""}`);
+      lines.push(`  ${question.id} ${question.ticketId ? `[${question.ticketId}] ` : ""}(${question.title}): ${question.question} You recommended ${question.recommended}`);
       for (const option of question.options) lines.push(`      ${option.letter}) ${option.label}${option.consequence ? `: ${option.consequence}` : ""}`);
     }
   }

package/shared/write-up.ts

@@ -0,0 +1,92 @@
+// A ticket's write-up (its Markdown source file) as simple blocks the dialog
+// can draw without a Markdown renderer: headings, paragraphs, list items and
+// code. Inline marks are kept as spans: `code` stays code, **bold** and
+// _emphasis_ lose their markers, and [links](url) keep only their text.
+
+export type Span = { text: string; code?: boolean };
+
+export type Block =
+  | { kind: "heading"; level: number; spans: Span[] }
+  | { kind: "paragraph"; spans: Span[] }
+  // `marker` is "•" for bullets, "1." and so on for numbered items, "☐"/"☑" for tasks.
+  | { kind: "item"; marker: string; depth: number; spans: Span[] }
+  | { kind: "code"; text: string };
+
+export function spans(text: string): Span[] {
+  const result: Span[] = [];
+  text.split(/(`[^`]+`)/).forEach((part) => {
+    if (!part) return;
+    if (/^`[^`]+`$/.test(part)) {
+      result.push({ text: part.slice(1, -1), code: true });
+      return;
+    }
+    const plain = part
+      .replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1")
+      .replace(/(\*\*|__)(.+?)\1/g, "$2")
+      .replace(/(^|[\s(])[*_](\S(?:.*?\S)?)[*_](?=[\s).,;:!?]|$)/g, "$1$2");
+    result.push({ text: plain });
+  });
+  return result;
+}
+
+export function parseWriteUp(markdown: string): Block[] {
+  const blocks: Block[] = [];
+  let paragraph: string[] = [];
+  let fence: string[] | null = null;
+  const flush = () => {
+    if (paragraph.length) blocks.push({ kind: "paragraph", spans: spans(paragraph.join(" ")) });
+    paragraph = [];
+  };
+  for (const raw of markdown.replace(/\r\n?/g, "\n").split("\n")) {
+    if (fence) {
+      if (/^\s*(```|~~~)/.test(raw)) {
+        blocks.push({ kind: "code", text: fence.join("\n") });
+        fence = null;
+      } else fence.push(raw);
+      continue;
+    }
+    if (/^\s*(```|~~~)/.test(raw)) {
+      flush();
+      fence = [];
+      continue;
+    }
+    const line = raw.trimEnd();
+    const heading = /^(#{1,6})\s+(.*?)\s*#*$/.exec(line);
+    const item = /^(\s*)([-*+]|\d+[.)])\s+(?:\[([ xX])\]\s+)?(.*)$/.exec(line);
+    if (!line.trim() || /^\s*([-*_])(\s*\1){2,}\s*$/.test(line)) flush();
+    else if (heading) {
+      flush();
+      blocks.push({ kind: "heading", level: heading[1].length, spans: spans(heading[2]) });
+    } else if (item) {
+      flush();
+      const marker = item[3] !== undefined ? (item[3] === " " ? "☐" : "☑") : /\d/.test(item[2]) ? item[2].replace(")", ".") : "•";
+      blocks.push({ kind: "item", marker, depth: Math.floor(item[1].replace(/\t/g, "  ").length / 2), spans: spans(item[4]) });
+    } else if (/^\s{2,}\S/.test(line) && blocks.at(-1)?.kind === "item" && !paragraph.length) {
+      // A wrapped list item continues on an indented line.
+      const last = blocks.at(-1) as Extract<Block, { kind: "item" }>;
+      last.spans = [...last.spans, ...spans(` ${line.trim()}`)];
+    } else paragraph.push(line.trim().replace(/^>\s?/, ""));
+  }
+  flush();
+  if (fence) blocks.push({ kind: "code", text: fence.join("\n") });
+  return blocks;
+}
+
+// The write-up without a leading top heading, which only repeats the ticket's title.
+export function withoutTitle(blocks: Block[]): Block[] {
+  return blocks[0]?.kind === "heading" && blocks[0].level === 1 ? blocks.slice(1) : blocks;
+}
+
+// The first blocks of the write-up, up to about `maxChars` of text, for the excerpt.
+export function writeUpExcerpt(blocks: Block[], maxChars = 420): { blocks: Block[]; more: boolean } {
+  const body = withoutTitle(blocks);
+  const shown: Block[] = [];
+  let chars = 0;
+  for (const block of body) {
+    const length = block.kind === "code" ? block.text.length : block.spans.reduce((sum, span) => sum + span.text.length, 0);
+    if (shown.length && chars + length > maxChars) break;
+    shown.push(block);
+    chars += length;
+  }
+  return { blocks: shown, more: shown.length < body.length };
+}

package/skills/paseo-progress/SKILL.md

@@ -14,7 +14,7 @@ The user answers questions by reference ("Q7 A") and reads everything else at a
 Run `paseo-progress show`. When it shows an open run for this job, continue it. A run marked Finished is closed, even if it looks like your job; start a new one. Otherwise:
 
 1. `paseo-progress start "<job title>"`, with `--subtitle` naming the spec or ticket folder.
-2. Add every ticket in order with `paseo-progress ticket add "Ticket 01: <title>" --estimate <minutes>`, with `--waits-for T02` on any that can't start before another finishes. Keep the "Ticket NN:" prefix: the dashboard shortens titles to it. For a job without tickets, add its steps instead and pass `--item-label Step` to `start`.
+2. Add every ticket in order with `paseo-progress ticket add "Ticket 01: <title>" --estimate <minutes>`, with `--waits-for T02` on any that can't start before another finishes. Keep the "Ticket NN:" prefix: the dashboard shortens titles to it. When a ticket is written up somewhere, a spec file or an issue, pass `--source <path or link>` so the user can open it from the ticket. For a job without tickets, add its steps instead and pass `--item-label Step` to `start`; give a step `--source` only when it has a write-up.
 3. `paseo-progress activity add "<one line: what this run will do>"`.
 
 Done when `show` lists every ticket with an estimate.
@@ -35,24 +35,27 @@ Record each change as it happens, on the ticket's id from `show` (T01, T02, ...)
 
 Pass `--ticket` on every activity, deliverable and question that belongs to a ticket. The user presses a ticket to see its story: each stage and how long it took, with the activity, deliverables and questions tagged to it. Leave it off only for run-wide notes. Stage changes and notes are timed from your `ticket update` calls, so make them when the change happens.
 
+Other sessions may add tickets (or steps) to the same run. When a command's output says another session added one, it is part of the plan: work it in order after your current one, the same as the ones you added.
+
 A working ticket turns stuck on its own once it goes longer than its estimate without an update: a status, stage or note change, or activity tagged to it. When a ticket will run long, keep updating its stage, or raise its estimate with `--estimate`.
 
-## 3. Ask questions without stopping
+## 3. Ask questions, and work around them
 
-When a decision belongs to the user, ask it and keep working:
+When a decision belongs to the user, ask it, then park everything the answer affects:
 
 ```sh
 paseo-progress question ask "<short title>" "<the question, in one or two sentences>" \
   --option "A=<choice> | <what happens if they pick it>" \
   --option "B=<choice> | <what happens if they pick it>" \
-  --default <letter> --ticket T03 --raised-by "Ticket 03 design review" \
+  --recommend <letter> --ticket T03 --raised-by "Ticket 03 design review" \
   [--background "<what they need to decide without opening the worktree>"] \
   [--file <path or http(s) URL>=<what it shows>]
 ```
 
-- The default is the safest choice. Carry on with it straight away.
-- Add `--waits` when acting on any choice needs the user's yes: purchases, production, live vendor calls, commits. Then work on something else until they answer.
-- When the user replies ("Q7 A", or in their own words), run `question answer Q7 A --words "<their words>"`. The command reports whether the answer differs from the default; when it does, change course before anything else.
+- `--recommend` is the option you would pick, so the user knows which way to lean.
+- Build no option before the user answers, not even the one you recommend. The point of asking is that the user decides before the work is done.
+- Keep working on whatever the question doesn't affect: other tickets, or other parts of this one. If nothing else is left, stop, tell the user in chat which questions you're waiting on, and leave the run open.
+- When the user replies ("Q7 A", or in their own words), run `question answer Q7 A --words "<their words>"`, then build what they chose.
 - When a question is about how something looks, attach the screenshot, mockup or preview link with `--file`. The user opens it from the question: images preview in Paseo, links open in its browser. Add more later with `question update Q7 --file <path>=<what it shows>`.
 - When the user asks about a question, answer in chat and also put the explanation on the question with `question update Q7 --background "<text>"`, so the dashboard carries it too.
 - `question remove Q7` withdraws a question that no longer applies.