@selesai/code 0.9.3 → 0.9.5

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to `@selesai/code` will be documented in this file.
 
+## [0.9.5] - 2026-08-23
+
+### Added
+- **Questions in non-TUI modes.** The bundled `question` tool now works outside the terminal TUI (e.g. RPC/VS Code hosts): questions are answered through the host's `extension_ui_request` dialogs (`select`/`input`) instead of throwing, mirroring Cline/Kilo. Multi-select questions preserve full multi-selection when the host supports the new `multiselect` UI method, with single-select fallback for older hosts.
+- **`multiselect` extension UI method.** `ExtensionUIContext.multiselect()` prompts for multiple choices and returns `string[] | undefined`. In RPC mode it emits an `extension_ui_request` with `method: "multiselect"` and accepts an `extension_ui_response` with a `values` array.
+
+## [0.9.4] - 2026-08-22
+
+### Changed
+- **Extensible pi-subagents workflows.** The bundled `/workflow-*` extension is now a thin registry-based adapter over pi-subagents orchestration. Modes can use ordered runs, parallel discovery, or scripted conditional loops without adding command plumbing. The prototype workflow now runs external research and codebase exploration in parallel.
+- **Workflow completion contract.** Build/review/fix loops now finish only when the reviewer reports `clean` with no remaining work, preventing a clean review of one slice from ending an incomplete plan.
+- **Workflow documentation.** Replaced stale durable-state-machine documentation with the current pi-subagents launch, recovery, and extension model.
+
 ## [0.9.3] - 2026-08-22
 
 ### Fixed

package/README.md

@@ -81,7 +81,7 @@ DuckDuckGo works as the default search path. Optional first-run onboarding can c
 
 ### Interactive questions
 
-The bundled `question` tool gives the agent a real TUI for decisions instead of forcing every clarification through plain text. It supports:
+The bundled `question` tool gives the agent a real UI for decisions instead of forcing every clarification through plain text. It supports:
 
 - single- and multi-select options
 - descriptions and context summaries

package/dist/core/extensions/types.d.ts

@@ -68,6 +68,8 @@ export type EditorFactory = (tui: TUI, theme: EditorTheme, keybindings: Keybindi
 export interface ExtensionUIContext {
     /** Show a selector and return the user's choice. */
     select(title: string, options: string[], opts?: ExtensionUIDialogOptions): Promise<string | undefined>;
+    /** Show a multi-select dialog and return the user's selections (labels), or undefined if cancelled. */
+    multiselect?(title: string, options: string[], opts?: ExtensionUIDialogOptions): Promise<string[] | undefined>;
     /** Show a confirmation dialog. */
     confirm(title: string, message: string, opts?: ExtensionUIDialogOptions): Promise<boolean>;
     /** Show a text input dialog. */

package/dist/extensions/question/index.ts

@@ -1,6 +1,6 @@
 // Batch-first interactive question tool.
 
-import type { ExtensionAPI, KeybindingsManager, Theme } from "@selesai/code";
+import type { ExtensionAPI, ExtensionUIContext, KeybindingsManager, Theme } from "@selesai/code";
 import {
 	Container,
 	type Component,
@@ -18,6 +18,78 @@ import {
 import { buildQuestionAnswers, prepareQuestions, saveDraftQuestion } from "./batch.ts";
 import { BOX_BORDER_LEFT, BOX_BORDER_OVERHEAD, BOX_BORDER_RIGHT, DISABLED_SHORTCUT, QUESTION_VERSION } from "./constants.ts";
 import { createSelectionResponse, createTextResponse, formatQuestionResponse, formatResponseSummary, oneLine, previewText, trimText } from "./helpers.ts";
+
+/**
+ * Answer a question outside the terminal TUI (e.g. RPC/extension mode) using
+ * the per-mode ExtensionUIContext, which emits extension_ui_request dialogs
+ * (select/input) that the VS Code host renders. Mirrors Cline/Kilo: a pending
+ * question is surfaced in the webview and blocks until the user answers.
+ */
+function answerQuestionViaUi(question: PreparedQuestion, ctx: { ui: ExtensionUIContext }): Promise<QuestionResponse | null> {
+	const title = question.context ? `${question.question}
+
+${question.context}` : question.question;
+	if (question.type === "text") {
+		return ctx.ui.input(title).then((text) => createTextResponse(text));
+	}
+	const optionLabels = new Map(question.options.map((option) => [option.label, option.value] as const));
+	const optionValues = question.options.map((option) => option.value);
+	const labels = question.options.map((option) => option.label);
+	if (question.type === "select") {
+		return ctx.ui
+			.select(title, labels)
+			.then((selected) => {
+				if (selected === undefined) return null;
+				const value = optionLabels.get(selected);
+				const isOther = value === undefined;
+				if (isOther) {
+					if (!question.allowOther) return null;
+					return ctx.ui.input(title).then((text) => createSelectionResponse([], text ?? undefined));
+				}
+				return createSelectionResponse([value]);
+			});
+	}
+	// RPC/webview hosts can preserve true multi-selection. Older hosts fall back to
+	// one choice rather than making the question tool unavailable entirely. When
+	// allowOther is set the host sees an explicit "Other" choice, surfacing a free
+	// text follow-up exactly like the TUI wizard.
+	if (ctx.ui.multiselect) {
+		const other = question.allowOther ? ["Other"] : [];
+		return ctx.ui.multiselect(title, [...labels, ...other]).then((selected) => {
+			if (selected === undefined) return null;
+			const values = selected.filter((label) => label !== "Other").map((label) => optionLabels.get(label)).filter((value): value is string => value !== undefined);
+			if (question.allowOther && selected.includes("Other")) {
+				return ctx.ui.input(title).then((text) => createSelectionResponse(values, text ?? undefined));
+			}
+			return createSelectionResponse(values);
+		});
+	}
+	return ctx.ui.select(title, labels).then((selected) => {
+		if (selected === undefined) return null;
+		const value = optionLabels.get(selected);
+		return value === undefined
+			? question.allowOther ? ctx.ui.input(title).then((text) => createSelectionResponse([], text ?? undefined)) : null
+			: createSelectionResponse([value]);
+	});
+}
+
+/**
+ * Non-TUI fallback that answers each question in sequence via the host UI.
+ * Returns null when the user cancels any question.
+ */
+async function answerQuestionsViaUi(questions: PreparedQuestion[], ctx: { ui: ExtensionUIContext }): Promise<QuestionResponse[] | null> {
+	const answers: QuestionResponse[] = [];
+	for (const question of questions) {
+		const response = await answerQuestionViaUi(question, ctx);
+		if (response === null) return null;
+		answers.push(response);
+	}
+	return answers;
+}
+
+function buildAnswersFromResponses(questions: PreparedQuestion[], responses: QuestionResponse[]): QuestionAnswer[] {
+	return questions.map((question, index) => ({ id: question.id, status: "answered" as const, response: responses[index]! }));
+}
 import { QuestionList } from "./question-list.ts";
 import { MultiSelect, SingleSelect } from "./selection-mode.ts";
 import { QuestionParamsSchema } from "./schemas.ts";
@@ -557,14 +629,17 @@ export default function questionExtension(pi: ExtensionAPI) {
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {
 			const prepared = prepareQuestions(params.questions);
 			if ("error" in prepared) throw new Error(prepared.error);
-			if (ctx.mode !== "tui") throw new Error("Question requires terminal TUI mode.");
 			if (signal?.aborted) return { content: [{ type: "text", text: "Question cancelled" }], details: { status: "cancelled", reason: "user" } satisfies QuestionToolResult };
 
 			onUpdate?.({ content: [{ type: "text", text: `Waiting for answers to ${prepared.questions.length} question${prepared.questions.length === 1 ? "" : "s"}...` }] });
-			const result = await ctx.ui.custom<QuestionToolResult>((tui, theme, keybindings, done) => {
-				if (signal) signal.addEventListener("abort", () => done({ status: "cancelled", reason: "user" }), { once: true });
-				return new BatchQuestionComponent(prepared.questions, tui, theme, keybindings, done);
-			});
+			const result: QuestionToolResult | undefined = ctx.mode === "tui"
+				? await ctx.ui.custom<QuestionToolResult>((tui, theme, keybindings, done) => {
+					if (signal) signal.addEventListener("abort", () => done({ status: "cancelled", reason: "user" }), { once: true });
+					return new BatchQuestionComponent(prepared.questions, tui, theme, keybindings, done);
+				})
+				: await answerQuestionsViaUi(prepared.questions, ctx).then((responses) =>
+					responses ? { status: "submitted" as const, answers: buildAnswersFromResponses(prepared.questions, responses) } : { status: "cancelled" as const, reason: "user" as const },
+				);
 			if (!result) throw new Error("Question TUI did not return a result.");
 
 			if (result.status === "cancelled") {

package/dist/extensions/question/tests/wizard.test.ts

@@ -197,13 +197,29 @@ describe("question wizard", () => {
 		expect(emitted2).toEqual(["question:submitted"]);
 	});
 
-	it("rejects non-TUI modes and invalid params", async () => {
+	it("uses extension UI requests in RPC mode", async () => {
 		let tool: any;
 		questionExtension({ registerTool: (entry: unknown) => (tool = entry), events: { emit() {} } } as any);
+		const result = await tool.execute("call", { questions: [{ type: "select", question: "Choose", options: [{ value: "x", label: "X" }] }] }, undefined, undefined, {
+			mode: "rpc",
+			ui: { select: async () => "X" },
+		} as any);
+		expect(result.details).toEqual({ status: "submitted", answers: [{ id: "q1", status: "answered", response: { kind: "selection", values: ["x"] } }] });
+	});
 
-		await expect(tool.execute("call", { questions: [{ type: "select", question: "Q", options: [{ value: "x", label: "X" }] }] }, undefined, undefined, {
+	it("preserves multiple RPC selections", async () => {
+		let tool: any;
+		questionExtension({ registerTool: (entry: unknown) => (tool = entry), events: { emit() {} } } as any);
+		const result = await tool.execute("call", { questions: [{ type: "multiselect", question: "Choose many", options: [{ value: "a", label: "A" }, { value: "b", label: "B" }] }] }, undefined, undefined, {
 			mode: "rpc",
-		} as any)).rejects.toThrow("Question requires terminal TUI mode.");
+			ui: { multiselect: async () => ["A", "B"] },
+		} as any);
+		expect(result.details).toEqual({ status: "submitted", answers: [{ id: "q1", status: "answered", response: { kind: "selection", values: ["a", "b"] } }] });
+	});
+
+	it("rejects invalid params", async () => {
+		let tool: any;
+		questionExtension({ registerTool: (entry: unknown) => (tool = entry), events: { emit() {} } } as any);
 
 		await expect(tool.execute("call", { questions: [] }, undefined, undefined, {
 			mode: "tui",

package/dist/extensions/workflow/extension.ts

@@ -1,26 +1,26 @@
-// ponytail: thin shell. Registers the four /workflow-* commands and launches
-// each mode's scripted workflow through pi-subagents' launchSlashSubagent.
+// ponytail: thin slash-command adapter for the pi-subagents workflow runtime.
 
 import type { ExtensionAPI } from "@selesai/code";
 import { launchSlashSubagent } from "../pi-subagents/src/slash/slash-commands.ts";
-import { buildLoopScript, buildPrototypeScript, buildQuicktypeScript, buildTaskScript } from "./modes.ts";
+import { WORKFLOW_MODES, type WorkflowMode } from "./modes.ts";
 
 export default function workflowModesExtension(pi: ExtensionAPI): void {
-  const register = (name: string, description: string, build: (goal: string) => string) =>
-    pi.registerCommand(name, {
-      description,
-      handler: async (args, ctx) => {
-        const goal = args.trim();
-        if (!goal) {
-          ctx.ui.notify(`${description}\nUsage: /${name} <goal>`, "info");
-          return;
-        }
-        launchSlashSubagent(pi, ctx, { workflowScript: build(goal), async: true, agentScope: "both", mission: { title: goal } });
-      },
-    });
+	const register = (mode: WorkflowMode) => pi.registerCommand(mode.command, {
+		description: mode.description,
+		handler: async (args, ctx) => {
+			const goal = args.trim();
+			if (!goal) {
+				ctx.ui.notify(`${mode.description}\nUsage: /${mode.command} <goal>`, "info");
+				return;
+			}
+			launchSlashSubagent(pi, ctx, {
+				...mode.launch(goal),
+				async: true,
+				agentScope: "both",
+				mission: { title: goal },
+			});
+		},
+	});
 
-  register("workflow-task", "Run the task workflow (plan → reuse → handoff → auto build→review→fix loop) as a scripted workflow.", buildTaskScript);
-  register("workflow-prototype", "Run the full prototype workflow (research → plan → reuse → handoff → auto loop → audit) as a scripted workflow.", buildPrototypeScript);
-  register("workflow-quicktype", "Run the quicker prototype workflow without research (plan → reuse → handoff → auto loop → audit) as a scripted workflow.", buildQuicktypeScript);
-  register("workflow-loop", "Run a direct auto build→review→fix loop for an already-agreed plan as a scripted workflow.", buildLoopScript);
+	for (const mode of WORKFLOW_MODES) register(mode);
 }

package/dist/extensions/workflow/modes.ts

@@ -1,12 +1,20 @@
-// ponytail: four workflow modes as pi-subagents workflowScript builders.
-// One-shot-and-sleep: phases run as runs.run steps and the build → review → fix
-// round auto-repeats until the reviewer reports clean. A workflowScript has no
-// checkpoints, so there are no human gates.
+// ponytail: workflow mode registry over pi-subagents' public workflowScript seam.
+// A mode returns launch parameters; the extension owns slash-command plumbing.
+
+import type { SubagentParamsLike } from "../pi-subagents/src/runs/foreground/subagent-executor.ts";
+
+export interface WorkflowMode {
+	command: string;
+	description: string;
+	launch(goal: string): Pick<SubagentParamsLike, "workflowScript" | "chain" | "tasks" | "concurrency">;
+}
 
 function js(value: string): string {
-  return JSON.stringify(value);
+	return JSON.stringify(value);
 }
 
+// A loop depends on the previous review's output, so it belongs in pi-subagents'
+// scripted workflow runtime rather than a fixed native chain.
 const AUTO_LOOP = String.raw`
 const autoLoop = async (goal, context, progressFile) => {
   emit({ phase: 'start', goal });
@@ -25,14 +33,15 @@ const autoLoop = async (goal, context, progressFile) => {
         timeoutMs: 15 * 60 * 1000,
         task: 'Independently review the builder work for this round and report concrete evidence (what you inspected and what you ran). Do not modify the workspace.\n\nAcceptance criteria (source of truth):\n' + context + '\n\nProgress file (scope your review to its latest round entry; also re-check the files from the immediately preceding fix entry if one exists; fall back to the full uncommitted diff if it is missing or empty):\n' + progressFile + '\n\nBuilder completion summary:\n' + build.output + '\n\nIf the plan is not yet complete, add a "Remaining work:" section listing the next concrete step(s). End with exactly one line: WORKFLOW_REVIEW_STATUS: clean OR WORKFLOW_REVIEW_STATUS: blocking.',
       });
-      if (/WORKFLOW_REVIEW_STATUS\s*:\s*clean/i.test(review.output)) {
+      const hasRemainingWork = /Remaining work\s*:\s*\S/i.test(review.output);
+      if (/WORKFLOW_REVIEW_STATUS\s*:\s*clean/i.test(review.output) && !hasRemainingWork) {
         return { result: 'clean', rounds: completed + 1 };
       }
       previousReview = review.output;
       await runs.run('fix-' + round, {
         agent: 'builder',
         timeoutMs: 45 * 60 * 1000,
-        task: 'Address ONLY the findings from the review below. The "Remaining work:" section (if present) is for the next round; do not act on it.\n\nProgress ledger: append a "## Round ' + round + ' fix" entry to the progress file at ' + progressFile + ' before finishing. List every file you changed and a short summary of the fixes.\n\nReviewer findings:\n' + review.output,
+        task: 'Address ONLY the findings from the review below. The "Remaining work:" section (if present) is for the next round; do not act on it. If the review is clean but has Remaining work, make no changes and record that fact.\n\nProgress ledger: append a "## Round ' + round + ' fix" entry to the progress file at ' + progressFile + ' before finishing. List every file you changed and a short summary of the fixes.\n\nReviewer findings:\n' + review.output,
       });
       completed += 1;
       round += 1;
@@ -49,13 +58,13 @@ const autoLoop = async (goal, context, progressFile) => {
 const PROGRESS_DIR = ".pi-subagents/progress/";
 
 export function buildLoopScript(goal: string): string {
-  return String.raw`const goal = ${js(goal)};
+	return String.raw`const goal = ${js(goal)};
 ${AUTO_LOOP}
 return await autoLoop(goal, goal, ${js(PROGRESS_DIR + "loop.md")});`;
 }
 
 export function buildTaskScript(goal: string): string {
-  return String.raw`const goal = ${js(goal)};
+	return String.raw`const goal = ${js(goal)};
 const plan = await runs.run('plan', { agent: 'architect', task: 'Produce a concrete implementation plan for: ' + goal + '. Cover what to build, how, in what order, which files and components, and the finished result. Return inline.' });
 const reuse = await runs.run('reuse', { agent: 'explorer', task: 'Explore the codebase for reusable patterns relevant to: ' + plan.output + '. Point at relevant areas and dependencies; skip cleanly if wholly new. Return inline.' });
 const handoff = await runs.run('handoff', { agent: 'recapper', task: 'Compile a self-contained handoff from the plan and reuse findings so fresh agents understand the goal, constraints, and acceptance criteria without re-planning.\n\nPlan:\n' + plan.output + '\n\nReuse findings:\n' + reuse.output + '\n\nReturn inline.' });
@@ -64,10 +73,14 @@ return await autoLoop(goal, handoff.output, ${js(PROGRESS_DIR + "task.md")});`;
 }
 
 export function buildPrototypeScript(goal: string): string {
-  return String.raw`const goal = ${js(goal)};
-const research = await runs.run('research', { agent: 'researcher', task: 'Research the external, fast-changing knowledge this task depends on (libraries, SDKs, APIs, unfamiliar alternatives). Task: ' + goal + '. Synthesize actionable findings with sources. Return inline.' });
-const plan = await runs.run('plan', { agent: 'architect', task: 'Produce a concrete build plan from the research findings.\n\nResearch:\n' + research.output + '\n\nRequest:\n' + goal + '\n\nReturn inline.' });
-const reuse = await runs.run('reuse', { agent: 'explorer', task: 'Explore the codebase for reusable patterns relevant to: ' + plan.output + '. Return inline.' });
+	return String.raw`const goal = ${js(goal)};
+const discovery = await runs.all([
+  { key: 'research', agent: 'researcher', task: 'Research the external, fast-changing knowledge this task depends on (libraries, SDKs, APIs, unfamiliar alternatives). Task: ' + goal + '. Synthesize actionable findings with sources. Return inline.' },
+  { key: 'explore', agent: 'explorer', task: 'Map existing code, dependencies, and reusable patterns relevant to: ' + goal + '. Return inline.' },
+]);
+const research = discovery.find(result => result.key === 'research');
+const reuse = discovery.find(result => result.key === 'explore');
+const plan = await runs.run('plan', { agent: 'architect', task: 'Produce a concrete build plan from the research and codebase findings.\n\nResearch:\n' + research.output + '\n\nCodebase findings:\n' + reuse.output + '\n\nRequest:\n' + goal + '\n\nReturn inline.' });
 const handoff = await runs.run('handoff', { agent: 'recapper', task: 'Compile a self-contained handoff from the plan and reuse findings.\n\nPlan:\n' + plan.output + '\n\nReuse:\n' + reuse.output + '\n\nReturn inline.' });
 ${AUTO_LOOP}
 const loop = await autoLoop(goal, handoff.output, ${js(PROGRESS_DIR + "prototype.md")});
@@ -76,7 +89,7 @@ return { ...loop, audited: true };`;
 }
 
 export function buildQuicktypeScript(goal: string): string {
-  return String.raw`const goal = ${js(goal)};
+	return String.raw`const goal = ${js(goal)};
 const plan = await runs.run('plan', { agent: 'architect', task: 'Produce a concrete build plan for: ' + goal + '. Cover what to build, how, in what order, which components, and the finished result. Return inline.' });
 const reuse = await runs.run('reuse', { agent: 'explorer', task: 'Explore the codebase for reusable patterns relevant to: ' + plan.output + '. Return inline.' });
 const handoff = await runs.run('handoff', { agent: 'recapper', task: 'Compile a self-contained handoff from the plan and reuse findings.\n\nPlan:\n' + plan.output + '\n\nReuse:\n' + reuse.output + '\n\nReturn inline.' });
@@ -85,3 +98,10 @@ const loop = await autoLoop(goal, handoff.output, ${js(PROGRESS_DIR + "quicktype
 const audit = await runs.run('audit', { agent: 'commentator', task: 'Final audit of the uncommitted changes for correctness, plan adherence, and over-engineering (cut bloat, dead flexibility, reinvented stdlib). Plan:\n' + plan.output + '\n\nReport concrete evidence. Do not modify the workspace.' });
 return { ...loop, audited: true };`;
 }
+
+export const WORKFLOW_MODES: readonly WorkflowMode[] = [
+	{ command: "workflow-task", description: "Run the task workflow (plan → reuse → handoff → build/review/fix loop).", launch: (goal) => ({ workflowScript: buildTaskScript(goal) }) },
+	{ command: "workflow-prototype", description: "Run the prototype workflow (parallel research/reuse → plan → handoff → loop → audit).", launch: (goal) => ({ workflowScript: buildPrototypeScript(goal) }) },
+	{ command: "workflow-quicktype", description: "Run the quicker prototype workflow (plan → reuse → handoff → loop → audit).", launch: (goal) => ({ workflowScript: buildQuicktypeScript(goal) }) },
+	{ command: "workflow-loop", description: "Run a direct build/review/fix loop for an already-agreed plan.", launch: (goal) => ({ workflowScript: buildLoopScript(goal) }) },
+];

package/dist/modes/rpc/rpc-mode.js

@@ -81,6 +81,7 @@ export async function runRpcMode(runtimeHost) {
      */
     const createExtensionUIContext = () => ({
         select: (title, options, opts) => createDialogPromise(opts, undefined, { method: "select", title, options, timeout: opts?.timeout }, (r) => "cancelled" in r && r.cancelled ? undefined : "value" in r ? r.value : undefined),
+        multiselect: (title, options, opts) => createDialogPromise(opts, undefined, { method: "multiselect", title, options, timeout: opts?.timeout }, (r) => "cancelled" in r && r.cancelled ? undefined : "values" in r ? r.values : undefined),
         confirm: (title, message, opts) => createDialogPromise(opts, false, { method: "confirm", title, message, timeout: opts?.timeout }, (r) => "cancelled" in r && r.cancelled ? false : "confirmed" in r ? r.confirmed : false),
         input: (title, placeholder, opts) => createDialogPromise(opts, undefined, { method: "input", title, placeholder, timeout: opts?.timeout }, (r) => "cancelled" in r && r.cancelled ? undefined : "value" in r ? r.value : undefined),
         notify(message, type) {

package/dist/modes/rpc/rpc-types.d.ts

@@ -418,6 +418,13 @@ export type RpcExtensionUIRequest = {
     title: string;
     options: string[];
     timeout?: number;
+} | {
+    type: "extension_ui_request";
+    id: string;
+    method: "multiselect";
+    title: string;
+    options: string[];
+    timeout?: number;
 } | {
     type: "extension_ui_request";
     id: string;
@@ -473,6 +480,10 @@ export type RpcExtensionUIResponse = {
     type: "extension_ui_response";
     id: string;
     value: string;
+} | {
+    type: "extension_ui_response";
+    id: string;
+    values: string[];
 } | {
     type: "extension_ui_response";
     id: string;

package/docs/extensions.md

@@ -9,7 +9,7 @@ Extensions are TypeScript modules that extend pi's behavior. They can subscribe
 **Key capabilities:**
 - **Custom tools** - Register tools the LLM can call via `pi.registerTool()`
 - **Event interception** - Block or modify tool calls, inject context, customize compaction
-- **User interaction** - Prompt users via `ctx.ui` (select, confirm, input, notify)
+- **User interaction** - Prompt users via `ctx.ui` (select, multiselect, confirm, input, notify)
 - **Custom UI components** - Full TUI components with keyboard input via `ctx.ui.custom()` for complex interactions
 - **Custom commands** - Register commands like `/mycommand` via `pi.registerCommand()`
 - **Session persistence** - Store state that survives restarts via `pi.appendEntry()`
@@ -2201,6 +2201,9 @@ Extensions can interact with users via `ctx.ui` methods and customize how messag
 // Select from options
 const choice = await ctx.ui.select("Pick one:", ["A", "B", "C"]);
 
+// Multi-select from options (string[] | undefined; optional in hosts that do not support it)
+const choices = await ctx.ui.multiselect?.("Pick many:", ["A", "B", "C"]);
+
 // Confirm dialog
 const ok = await ctx.ui.confirm("Delete?", "This cannot be undone");
 

package/docs/rpc.md

@@ -1008,7 +1008,7 @@ Extensions can request user interaction via `ctx.ui.select()`, `ctx.ui.confirm()
 
 There are two categories of extension UI methods:
 
-- **Dialog methods** (`select`, `confirm`, `input`, `editor`): emit an `extension_ui_request` on stdout and block until the client sends back an `extension_ui_response` on stdin with the matching `id`.
+- **Dialog methods** (`select`, `multiselect`, `confirm`, `input`, `editor`): emit an `extension_ui_request` on stdout and block until the client sends back an `extension_ui_response` on stdin with the matching `id`.
 - **Fire-and-forget methods** (`notify`, `setStatus`, `setWidget`, `setTitle`, `set_editor_text`): emit an `extension_ui_request` on stdout but do not expect a response. The client can display the information or ignore it.
 
 If a dialog method includes a `timeout` field, the agent-side will auto-resolve with a default value when the timeout expires. The client does not need to track timeouts.
@@ -1046,6 +1046,23 @@ Prompt the user to choose from a list. Dialog methods with a `timeout` field inc
 
 Expected response: `extension_ui_response` with `value` (the selected option string) or `cancelled: true`.
 
+#### multiselect
+
+Prompt the user to choose zero or more options from a list. Dialog methods with a `timeout` field include the timeout in milliseconds; the agent auto-resolves with `undefined` if the client doesn't respond in time.
+
+```json
+{
+  "type": "extension_ui_request",
+  "id": "uuid-10",
+  "method": "multiselect",
+  "title": "Which regions?",
+  "options": ["us-east", "eu-west", "ap-southeast"],
+  "timeout": 10000
+}
+```
+
+Expected response: `extension_ui_response` with `values` (the selected option strings) or `cancelled: true`.
+
 #### confirm
 
 Prompt the user for yes/no confirmation.
@@ -1172,7 +1189,7 @@ Set the text in the input editor. Fire-and-forget.
 
 ### Extension UI Responses (stdin)
 
-Responses are sent for dialog methods only (`select`, `confirm`, `input`, `editor`). The `id` must match the request.
+Responses are sent for dialog methods only (`select`, `multiselect`, `confirm`, `input`, `editor`). The `id` must match the request.
 
 #### Value response (select, input, editor)
 
@@ -1180,6 +1197,12 @@ Responses are sent for dialog methods only (`select`, `confirm`, `input`, `edito
 {"type": "extension_ui_response", "id": "uuid-1", "value": "Allow"}
 ```
 
+#### Values response (multiselect)
+
+```json
+{"type": "extension_ui_response", "id": "uuid-10", "values": ["us-east", "ap-southeast"]}
+```
+
 #### Confirmation response (confirm)
 
 ```json
@@ -1188,7 +1211,7 @@ Responses are sent for dialog methods only (`select`, `confirm`, `input`, `edito
 
 #### Cancellation response (any dialog)
 
-Dismiss any dialog method. The extension receives `undefined` (for select/input/editor) or `false` (for confirm).
+Dismiss any dialog method. The extension receives `undefined` (for select/multiselect/input/editor) or `false` (for confirm).
 
 ```json
 {"type": "extension_ui_response", "id": "uuid-3", "cancelled": true}

package/docs/workflows.md

@@ -1,250 +1,57 @@
 # Workflows
 
-Selesai ships a workflow engine under `src/extensions/workflow/`. It powers the built-in `prototype`, `quicktype`, `task`, and `loop` workflows and is designed so you can add a new workflow mode as a thin config file — no engine changes.
+Selesai's built-in workflows are thin slash-command adapters over the **pi-subagents** orchestration runtime. They do not have a separate state machine, artifact protocol, or `workflow.json` format.
 
-## How it fits together
+## Run a workflow
 
+```text
+/workflow-task <goal>
+/workflow-prototype <goal>
+/workflow-quicktype <goal>
+/workflow-loop <goal>
 ```
-src/extensions/workflow/
-  package.json          pi package manifest; loads ./extension.ts as the single entry
-  state-machine.ts      pure phase state machine (no fs, no pi API)
-  adapter.ts            pi wiring: tools, commands, events, fs, durable-state lifecycle
-  run-state.ts          versioned atomic workflow.json load/save/discovery
-  extension.ts          single pi extension that mounts every workflow mode
-  modes/
-    prototype.ts        mode config + registration object (exported as `prototypeMode`)
-    quicktype.ts        mode config + registration object (exported as `quicktypeMode`)
-    task.ts             mode config + registration object (exported as `taskMode`)
-    loop.ts             mode config + registration object (exported as `loopMode`)
-```
-
-- **`state-machine.ts`** is the deep module. It owns the phase graph, artifact gating, skip rules, the terminal close gate, and the reentrancy guard. It imports nothing external — no `node:fs`, no pi API, no `pi-tui`, no `typebox`. Every method returns a `WorkflowEffect` (a discriminated union in domain vocabulary) that the adapter pattern-matches on.
-- **`adapter.ts`** is the thin glue. It owns Pi/fs wiring, durable state, explicit resume, loop review persistence, and the git-based `reuse` skip predicate. Parent-written artifacts advance durable phase state and queue hidden engine continuations; every built-in mode flows automatically.
-- **`workflow.json`** in each artifact directory is the canonical, versioned run record. It is atomically replaced after state changes; session custom entries are only pointers for UI/history and never reconstruct an active run.
-- **`extension.ts`** imports each mode's registration object and calls `createWorkflowExtension(config, options)(pi)` for each. One extension load registers the model-facing artifact writer and `end_workflow` tool. Starting and resuming are user-only actions exposed by each mode's slash command.
-- **A mode file** is pure data: the phase list, per-phase artifact filenames, prompt generators, terminal close artifacts, and command/status/entry identities. Prompts receive `{ artifactDir, userPrompt }`. Each mode exports a `WorkflowModeRegistration` object (e.g. `prototypeMode`, `quicktypeMode`); it does not call `createWorkflowExtension` itself.
-
-## To add a future mode
-
-Copy `modes/quicktype.ts` (the smaller one) and change the config. That's the whole change — the engine never needs editing.
-
-### 1. Create the mode file
-
-`src/extensions/workflow/modes/rigorous.ts`:
-
-```typescript
-import type {
-  Phase,
-  PromptContext,
-  WorkflowConfig,
-  WorkflowModeRegistration,
-} from "../state-machine.ts";
-
-const phases: Phase[] = [
-  "grilling",
-  "spec",      // ← new phase, not in the built-in set
-  "research",
-  "plan",
-  "reuse",
-  "handoff",
-  "loop",
-  "audit",
-  "sign-off",  // ← new terminal phase
-];
-
-const prompts: Partial<Record<Phase, (ctx: PromptContext) => string>> = {
-  grilling: ({ artifactDir, userPrompt }) => `…grilling prompt…`,
-  spec: ({ artifactDir }) => `…spec prompt…`,
-  research: ({ artifactDir }) => `…research prompt…`,
-  plan: ({ artifactDir }) => `…plan prompt…`,
-  reuse: ({ artifactDir }) => `…reuse prompt…`,
-  handoff: ({ artifactDir }) => `…handoff prompt…`,
-  loop: ({ artifactDir }) => `…loop prompt…`,
-  audit: ({ artifactDir }) => `…audit prompt…`,
-  "sign-off": ({ artifactDir }) => `…sign-off prompt…`,
-};
-
-const config: WorkflowConfig = {
-  mode: "rigorous",
-  phases,
-  phaseArtifacts: {
-    grilling: "requirements.md",
-    spec: "spec.md",
-    research: "research.md",
-    plan: "plan.md",
-    reuse: "reuse.md",
-    handoff: "handoff.md",
-    loop: "loop-complete.md",
-    audit: "review.md",
-    "sign-off": "acceptance.md",
-  },
-  prompts,
-  // Files that must exist before end() can close the workflow.
-  // Config-owned — declare whatever your terminal phase requires.
-  closeArtifacts: ["acceptance.md", "sign-off-report.md"],
-  statusKey: "rigorous",
-  entryType: "rigorous-phase",
-  footerLabel: "rigorous",
-};
-
-export const rigorousMode: WorkflowModeRegistration = {
-  config,
-  commandName: "rigorous",
-  commandDescription:
-    "Run the rigorous workflow (grill → spec → research → plan → reuse → handoff → loop → audit → sign-off)",
-};
-
-export default rigorousMode;
-```
-
-### 2. Register it in `extension.ts`
-
-Add the mode to the `MODES` array in `src/extensions/workflow/extension.ts`:
 
-```typescript
-import { rigorousMode } from "./modes/rigorous.ts";
-
-const MODES = [prototypeMode, quicktypeMode, rigorousMode] as const;
-```
-
-That's it. The loader picks it up at boot (`package.json` loads only `./extension.ts`), and the `/rigorous` command is registered automatically. There is no model-facing start/resume or `next` tool — users start and resume through `/rigorous`, phases auto-advance as artifacts land, and only `end_workflow({ mode: "rigorous" })` completes the terminal phase.
+Each command starts an async pi-subagents mission. Recover a completed, paused, or confusing run with the pi-subagents mission and status controls (`/subagents`, `/subagents-doctor`, or the corresponding `subagent` tool actions); there is no `/workflow-* resume` command.
 
 ## Built-in modes
 
-### `prototype` and `quicktype` — full vs. quicker prototype
-
-`quicktype` has the same prototype flow except for research: it goes from grilling directly to planning. Use `prototype` when external research is needed; use `quicktype` when it is not.
-
-- `prototype`: `grilling → research → plan → reuse → handoff → loop → audit`
-- `quicktype`: `grilling → plan → reuse → handoff → loop → audit`
-
-### `task` — plan → codebase exploration → handoff → build/review loop
-
-Task now follows the same phase shape as the other modes, minus grilling/research/audit: an architect subagent produces a validated `plan.md`, an optional explorer subagent produces `reuse.md`, a recapper subagent produces a validated `handoff.md`, and then a builder↔commentator review loop runs (max 3 blocking rounds). A clean review makes the workflow terminal-ready; `end_workflow({ mode: "task" })` completes it.
-
-Lifecycle: `plan → reuse → handoff → loop (build ↔ review) → terminal-ready → end_workflow({ mode: "task" })`
-
-- `/workflow-task <goal>` — start a new run
-- `/workflow-task resume` — list and resume active runs
-- `/workflow-task help` — show the lifecycle
-- Valid phase artifacts automatically queue the next phase prompt (the workflow does not pause at artifact boundaries)
-- No grilling, research, or audit phases
-- `reuse.md` is optional; it is skipped automatically when the project has no git history
-
-### `loop` — direct build/review loop
-
-Use this after the plan was already agreed in the current conversation. It captures the agreed context into a parent-owned `handoff.md` artifact, then runs an engine-owned `loop` phase: builder changes workspace code, commentator independently validates the diff and relevant checks, then blocking feedback returns to the builder (max 3 blocking rounds). A clean review writes `loop-complete.md`, makes the run terminal-ready, and requires explicit completion.
-
-Fresh subagents do not inherit the parent conversation. The parent forks a `recapper` subagent once to synthesize a concise, self-contained handoff document directly from the inherited conversation. The parent validates the handoff marker and writes `handoff.md` via `write_workflow_artifact`. After that, every builder and commentator call reads `handoff.md` instead of relying on the parent conversation. Persisted `loop-review-N.md` files feed blocking fixes back to the builder.
-
-Lifecycle: `handoff → loop (build ↔ review) → terminal-ready → end_workflow({ mode: "loop" })`
-
-- `/workflow-loop <goal>` — start a direct build/review run
-- `/workflow-loop resume` / `/workflow-loop resume <id-or-artifact-dir-or-workflow.json>` — list or resume a run
-- `/workflow-loop help` — show the lifecycle
-
-## Config reference
+| Command | Shape |
+| --- | --- |
+| `/workflow-task` | plan → reuse → handoff → build/review/fix loop |
+| `/workflow-prototype` | parallel research + codebase exploration → plan → handoff → build/review/fix loop → audit |
+| `/workflow-quicktype` | plan → reuse → handoff → build/review/fix loop → audit |
+| `/workflow-loop` | direct build/review/fix loop for an already-agreed plan |
 
-| Field | Type | Description |
-|---|---|---|
-| `mode` | `string` | Mode name, echoed in entry payloads and messages. |
-| `phases` | `Phase[]` | Ordered phase list. `Phase` is `string` — new phase names are allowed. |
-| `phaseArtifacts` | `Partial<Record<Phase, string>>` | The artifact file each phase must produce before advancing. Omit a phase to skip its gate. |
-| `prompts` | `Partial<Record<Phase, (ctx) => string>>` | Prompt generator per phase. `ctx = { artifactDir, userPrompt }`. |
-| `closeArtifacts` | `string[]` | Files that must exist before `end()` succeeds. Config-owned, no built-in default. |
-| `skipRules?` | `{ phase, shouldSkip }[]` | Optional per-phase skip rules. `shouldSkip` is a boolean predicate; when true the engine skips to the next phase. Omit to use the adapter's default (skip `reuse` when the project has no git history). |
-| `statusKey` | `string` | Footer status key. |
-| `entryType` | `string` | Session-history custom-type. It stores a pointer only; `workflow.json` is canonical. |
-| `footerLabel` | `string` | Label shown in the footer (`● label · step/total phase`). |
+The prototype mode uses `runs.all` for its independent research and codebase-exploration work. All modes use `runs.run` for ordered handoffs. The build/review/fix loop uses `workflowScript` because its next step depends on the reviewer result; a blocking review gets a scoped fix round, while `clean` plus no remaining work ends the run.
 
-### Adapter options
+## Extending workflows
 
-The second argument to `createWorkflowExtension`:
+The extension seam is `src/extensions/workflow/modes.ts`.
 
-| Field | Description |
-|---|---|
-| `commandName` | The `/<command>` name users type to kick off the workflow. |
-| `commandDescription` | Description shown in the command list. |
+Add one `WorkflowMode` entry to `WORKFLOW_MODES`:
 
-## Durable runs and explicit resume
-
-Each started workflow receives a UUID artifact directory under `.selesai/artifacts/` and an adjacent `workflow.json`. It stores the mode, phase, armed state, loop round/review path, and timestamps. Writes use a temporary sibling file plus rename, so a crash cannot partially overwrite the canonical record.
-
-Runs are **never** auto-resumed on session start. At most one run can be attached to a Pi instance, but older active runs remain resumable:
-
-- Workflow initiation is user-only: `/workflow-prototype <goal>`, `/workflow-quicktype <goal>`, `/workflow-task <goal>`, or `/workflow-loop <goal>`
-- `/workflow-prototype resume <id-or-artifact-dir-or-workflow.json>` / `/workflow-quicktype resume ...` / `/workflow-task resume ...` / `/workflow-loop resume ...`
-- `/workflow-prototype resume`, `/workflow-quicktype resume`, `/workflow-task resume`, or `/workflow-loop resume` lists active runs (and offers a UI picker when available).
-- `/workflow-prototype help`, `/workflow-quicktype help`, `/workflow-task help`, or `/workflow-loop help` shows the start, resume, continue, and explicit-completion lifecycle.
-
-Resume validates the selected file is under the artifacts base, belongs to that mode, is active, and matches its containing directory. It reconciles the current expected artifact once before emitting the current prompt, covering a crash after `write_workflow_artifact` writes the file but before the phase-state write. Valid artifact writes queue one hidden engine-controlled continuation using `steer` and terminate the current parent turn; invalid writes stay in the current phase and do not terminate. Prompts injected by start, resume, and continue commands are hidden custom messages rather than visible synthetic user messages. Transition-capable calls (`write_workflow_artifact`, loop commentator transitions, and `end_workflow`) must be the sole tool call in their assistant batch; the adapter fails closed when that cannot be proven. Corrupt records are skipped during discovery. Reloads never auto-resume; the user must explicitly resume through a mode's slash command.
-
-A valid terminal artifact makes a workflow **terminal-ready**; it does not complete the run. Call `end_workflow({ mode })` to write `status: "completed"`, append the done entry, and terminate. This is the only completion path.
-
-## Artifact ownership
-
-Workflow artifacts have one writer: the parent session's `write_workflow_artifact` tool. Every workflow child call uses `output: false` and returns inline. In artifact phases (`plan`, `reuse`, `handoff`, and `audit`), the parent inspects that result, validates any required marker, and immediately passes it to `write_workflow_artifact`. Child output paths and fallback persistence are deliberately disabled; a child result alone cannot create an artifact or advance a phase.
-
-The implement/review loop is the explicit exception to parent persistence, not inline return: the engine persists `loop-review-<round>.md` and `loop-complete.md` from commentator results so it can manage review rounds. Builders only change workspace code.
-
-Every state-machine method returns a `WorkflowEffect` — a discriminated union the adapter switches on:
-
-| Effect | Meaning |
-|---|---|
-| `started` | `start()` succeeded; first phase prompt + entry + footer. |
-| `alreadyActive` | `start()` called while a workflow is active. |
-| `advanced` | Phase moved forward (optionally `skipped` a phase). |
-| `blocked` | Current phase's artifact is missing. |
-| `terminalNeedsArtifacts` | At the last phase; a close artifact is missing. |
-| `terminalReady` | At the last phase; all close artifacts present — call `end()`. |
-| `closed` | `end()` succeeded; workflow finished. |
-| `endBlocked` | `end()` called from the wrong phase or with close artifacts missing. |
-| `idle` | No active workflow. |
-| `noOp` | Auto-advance checked, nothing to do (not active, not armed, artifact not present, or already advancing). |
-
-The `tool_result` auto-advance hook is one line:
-
-```typescript
-const eff = await sm.onArtifactMaybe(deps);
-applyEffect(pi, ctx, config, eff);
-```
-
-The reentrancy guard lives inside `onArtifactMaybe` — concurrent calls return `noOp`, so a double `write` in one turn cannot double-advance the phase.
-
-## Skip rules
-
-By default the adapter skips the `reuse` phase when the project has no git history. To override, supply `skipRules` in your config:
-
-```typescript
-skipRules: [
-  { phase: "research", shouldSkip: async () => isWellUnderstoodDomain() },
-  { phase: "reuse", shouldSkip: async () => isEmptyProject() },
-],
+```ts
+{
+  command: "workflow-rigorous",
+  description: "Run the rigorous workflow.",
+  launch: (goal) => ({
+    workflowScript: `const goal = ${JSON.stringify(goal)};
+return runs.run("plan", { agent: "architect", task: "Plan: " + goal });`,
+  }),
+}
 ```
 
-`shouldSkip` is a boolean predicate. When it returns `true`, the engine skips to the next phase in `phases` — the mode owns the transition graph, not the adapter.
-
-## Testing a mode
+`launch(goal)` returns pi-subagents public execution fields. Prefer the native execution shapes where the mode is static:
 
-The state machine is tested directly with in-memory stubs — no filesystem, no pi mock, no events:
+- `chain` for a fixed ordered sequence, including human checkpoints.
+- `tasks` for independent, read-only parallel work.
+- `workflowScript` only when the orchestration is conditional, iterative, needs dynamic fan-out, or combines native run operations.
 
-```typescript
-import { WorkflowStateMachine } from "../extensions/workflow/state-machine.ts";
+`extension.ts` automatically registers every entry in `WORKFLOW_MODES`; no new command plumbing is needed. The mode owns task wording and execution shape. The extension owns only argument validation, async launch, agent scope, and mission creation.
 
-const files = new Set<string>();
-const deps = {
-  async artifactExists(phase, dir) {
-    const file = config.phaseArtifacts[phase];
-    return file ? files.has(`${dir}/${file}`) : true;
-  },
-  async fileExists(path) { return files.has(path); },
-  async mkdirArtifactDir() {},
-  artifactPathFor: (goal) => `/fake/${goal}`,
-};
-
-const sm = new WorkflowStateMachine(config);
-const eff = await sm.start("build X", deps);
-expect(eff.kind).toBe("started");
-```
+## Constraints
 
-See `src/__tests__/state-machine.test.ts` for the full set of transition, skip, terminal, rehydrate, and validation tests.
+- `workflowScript`, `chain`, and `tasks` are alternative top-level pi-subagents execution modes. A mode that needs an auto-loop and preceding/following phases should use `workflowScript` and call `runs.run` / `runs.all` within it.
+- Keep one writer at a time. Parallel lanes should be research or review unless they are isolated in worktrees.
+- Workflow progress ledgers are under `.pi-subagents/progress/` and are local runtime artifacts, not durable workflow state.
+- The outer mission and pi-subagents run artifacts are the recovery record.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@selesai/code",
-	"version": "0.9.3",
+	"version": "0.9.5",
 	"description": "Maintained, extension-first Pi coding agent with built-in workflows, subagents, web research, questions, skills, and an enhanced terminal UI.",
 	"type": "module",
 	"repository": {