@selesai/code 0.9.3 → 0.9.4

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to `@selesai/code` will be documented in this file.
 
+## [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/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/docs/research/kilo-vscode-and-selesai-integration.md

@@ -0,0 +1,319 @@
+# Kilo Code VS Code Architecture and Selesai Integration Feasibility
+
+**Research date:** 2026-08-20  
+**Repositories:** [Kilo Code](https://github.com/Kilo-Org/kilocode), this Selesai Code repository  
+**Question:** Does Kilo use RPA or another integration mechanism, and can Selesai provide a similar or better VS Code extension?
+
+## Executive conclusion
+
+Kilo Code is **not primarily an RPA application** and its core is not an LSP client/server. It is a layered VS Code product:
+
+1. A normal VS Code extension host (`packages/kilo-vscode`) activated through `vscode` APIs.
+2. Webview-based UI surfaces (sidebar, panels, agent manager, settings, diffs).
+3. A lazily spawned local Kilo CLI backend (`kilo serve --port 0`).
+4. An SDK/client connection from the extension host to that backend over authenticated local HTTP APIs and SSE event streaming.
+5. Separate WebSocket paths for selected features such as PTY terminal streaming and cloud event service.
+6. MCP client transports for tool/server integration: local stdio subprocesses and remote HTTP/SSE transports.
+
+The important correction to a simplistic “Webview only” description is that **Webview `postMessage` is only the UI bridge**. In the current Kilo repository, the extension also connects to a local backend server. The extension spawns the backend, discovers its ephemeral port from stdout, gives it a generated password, and uses an SDK plus HTTP/SSE with Basic authentication.
+
+Selesai can absolutely support a comparable VS Code extension. The shortest path is a VS Code extension-host backend that starts `selesai --mode rpc` and adapts the existing strict JSONL RPC client/events into a Webview. The best long-term path is probably a two-tier design:
+
+- **MVP:** local child process + existing Selesai RPC over private stdin/stdout.
+- **Better product integration:** a small authenticated local HTTP/SSE or WebSocket server facade, or direct in-process SDK use where safe, with a stable VS Code-oriented protocol.
+
+Selesai already has unusually strong agent/session/extension primitives. Its main missing pieces for Kilo-level VS Code integration are a polished VS Code package, a durable UI protocol/adapter, explicit trust UX, and (if remote or multi-client use is desired) authenticated network transport.
+
+## 1. What Kilo actually uses
+
+### 1.1 VS Code extension activation
+
+Kilo's extension is a conventional TypeScript VS Code extension. The activation function accepts `vscode.ExtensionContext`, constructs shared services, and registers views/providers through the VS Code API:
+
+- [`packages/kilo-vscode/src/extension.ts`](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/extension.ts#L45-L61) — `activate(context)` and shared `KiloConnectionService`.
+- [`packages/kilo-vscode/src/extension.ts`](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/extension.ts#L131-L143) — creates `KiloProvider` and calls `vscode.window.registerWebviewViewProvider(...)`.
+- The extension manifest/build configuration is in [`packages/kilo-vscode/package.json`](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/package.json) and the repository root package configuration.
+
+This is ordinary VS Code extension-host architecture, not RPA automation of the VS Code UI.
+
+### 1.2 Webview UI bridge
+
+Kilo's chat and panels use Webviews. The extension host attaches a Webview and receives structured messages with `webview.onDidReceiveMessage`; it sends state, stream, and command results back using `webview.postMessage`:
+
+- [`KiloProvider.ts`](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/KiloProvider.ts#L987-L1019) — `attachToWebview`, handler setup, interception, and routing.
+- [`KiloProvider.ts`](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/KiloProvider.ts#L1013-L1040) — inbound message handling and dispatch.
+- [`extension.ts`](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/extension.ts#L137-L143) — sidebar Webview registration.
+
+The Webview bridge is **structured local message passing across the VS Code extension/Webview boundary**. It is not HTTP RPC, LSP, or RPA.
+
+### 1.3 The extension spawns a local backend
+
+The current code explicitly documents that the CLI backend starts lazily rather than during extension activation:
+
+> “The CLI backend is NOT spawned here; it starts lazily when a webview connects or when ensureBackendForAutocomplete() triggers it.”
+
+Source: [`packages/kilo-vscode/src/extension.ts`](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/extension.ts#L45-L49).
+
+The server manager starts a local CLI process with an ephemeral port:
+
+- [`server-manager.ts`](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/services/cli-backend/server-manager.ts#L92-L120) — spawns `cliPath serve --port 0` with a workspace-derived cwd.
+- [`server-manager.ts`](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/services/cli-backend/server-manager.ts#L118-L161) — passes environment, including `KILO_SERVER_PASSWORD`, parent PID, VS Code metadata, and `stdio: ["ignore", "pipe", "pipe"]`.
+- [`server-manager.ts`](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/services/cli-backend/server-manager.ts#L167-L177) — reads child stdout and parses the selected port.
+
+This is a **local child process plus local server** architecture. It is RPC-like in the broad sense, but it is not RPA.
+
+### 1.4 HTTP/API client and SSE events
+
+`KiloConnectionService` owns one backend manager, one Kilo SDK client, and one SSE adapter for multiple UI providers:
+
+- [`connection-service.ts`](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/services/cli-backend/connection-service.ts#L80-L99) — describes and declares the shared service, client, and SSE adapter.
+- [`connection-service.ts`](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/services/cli-backend/connection-service.ts#L149-L150) — lazy startup/connection entrypoint.
+- [`types.ts`](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/services/cli-backend/types.ts#L1-L20) — server configuration includes `baseUrl` and `password`.
+
+The extension checks backend health over HTTP with Basic authentication:
+
+- [`connection-service.ts`](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/services/cli-backend/connection-service.ts#L733-L777) — periodic `GET ${baseUrl}/global/health`, `Authorization: Basic ...`, and reconnect behavior.
+
+Thus the current Kilo architecture is more accurately:
+
+```text
+VS Code Webview
+   │ postMessage / onDidReceiveMessage
+   ▼
+Kilo extension host
+   │ Kilo SDK over authenticated localhost HTTP
+   │ SSE event stream
+   ▼
+local `kilo serve --port 0` process
+   │
+   ├─ model/provider APIs
+   ├─ sessions/tools/filesystem
+   └─ MCP clients
+```
+
+### 1.5 WebSockets are feature-specific, not the basic UI bridge
+
+The repository has WebSocket use for feature-specific paths. For example, the Agent Manager terminal routes PTY bytes over a WebSocket rather than through Webview messages:
+
+- [`terminal-manager.ts`](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/agent-manager/terminal-manager.ts#L1-L10) — describes PTY output over `/pty/:id/connect` WebSocket.
+- [`terminal-routing.ts`](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/agent-manager/terminal-routing.ts#L242-L248) — builds an authenticated loopback WebSocket URL with `auth_token`.
+- [`event-service-client.ts`](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/kiloclaw/event-service-client.ts#L1-L10) — cloud event-service ticket flow and WebSocket subprotocol.
+
+This demonstrates that Kilo chooses transport by use case: Webview messages for UI commands/state, HTTP/SSE for backend API/events, and WebSocket for high-volume or cloud event paths.
+
+### 1.6 MCP is an integration protocol, not the extension connection
+
+Kilo's MCP code imports multiple official MCP SDK transports:
+
+- [`packages/opencode/src/mcp/index.ts`](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/mcp/index.ts#L15-L19) — `StreamableHTTPClientTransport`, `SSEClientTransport`, and `StdioClientTransport`.
+- [`packages/opencode/src/mcp/index.ts`](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/mcp/index.ts#L369-L389) — local MCP config launches a command using `StdioClientTransport` with cwd/environment.
+
+MCP lets the coding agent connect to tools/resources exposed by configured MCP servers. It does **not** appear to be the protocol connecting Kilo's VS Code Webview to its extension host. Those are separate layers.
+
+## 2. Is it RPA, LSP, RPC, or something else?
+
+| Technology | Kilo role | Conclusion |
+|---|---|---|
+| RPA (Robotic Process Automation) | None identified as a framework/protocol | No. Agentic file/terminal/browser automation is not conventional RPA architecture. |
+| VS Code Extension API | Activation, commands, views, workspace, terminals, Webviews | Yes; foundational. |
+| Webview message bridge | UI ↔ extension host messages | Yes; local structured messaging. |
+| Local child process | Extension starts `kilo serve` | Yes. |
+| HTTP | Extension ↔ local backend API and health checks | Yes; authenticated localhost API. |
+| SSE | Backend event stream to extension | Yes. |
+| WebSocket | PTY and selected cloud/event paths | Yes, feature-specific. |
+| MCP | Agent ↔ configured external tools/resources | Yes; separate integration layer. |
+| LSP | Language server/client lifecycle | No evidence of core LSP architecture. |
+| JSON-RPC | Not the main current VS Code connection identified in Kilo | Do not assume this is Kilo's transport. |
+
+## 3. What Selesai already provides
+
+### 3.1 Existing RPC mode
+
+Selesai RPC is a headless JSONL protocol over a child process:
+
+- [`docs/rpc.md`](../rpc.md) — protocol, commands, event stream, extension UI protocol, framing, and client examples.
+- [`src/modes/rpc/rpc-mode.ts`](../../src/modes/rpc/rpc-mode.ts) — server implementation over stdin/stdout.
+- [`src/modes/rpc/rpc-types.ts`](../../src/modes/rpc/rpc-types.ts) — typed commands, responses, events, and extension UI messages.
+- [`src/modes/rpc/rpc-client.ts`](../../src/modes/rpc/rpc-client.ts) — typed subprocess client and request correlation.
+- [`src/rpc-entry.ts`](../../src/rpc-entry.ts) — RPC executable entrypoint.
+
+The transport is strict LF-delimited JSONL. It has request IDs for responses and asynchronous events for streaming output/tool lifecycle. A VS Code extension can spawn:
+
+```text
+selesai --mode rpc --cwd <workspace> [other options]
+```
+
+(or spawn the packaged Node CLI with equivalent arguments), then:
+
+1. Write one JSON object plus `\n` to stdin.
+2. Parse stdout one LF record at a time.
+3. Correlate `type: "response"` records by `id`.
+4. Render `message_update`, `tool_execution_*`, and lifecycle events.
+5. Wait for `agent_settled`/`agent_end`, not merely prompt acceptance.
+6. Answer `extension_ui_request` records when an extension asks for a dialog.
+
+This is sufficient for a local VS Code extension MVP.
+
+### 3.2 Direct SDK option
+
+Selesai also exports a direct TypeScript/Node SDK:
+
+- [`docs/sdk.md`](../sdk.md) — `createAgentSession`, `createAgentSessionRuntime`, event subscription, tools, sessions, cwd, auth, and resources.
+- [`src/core/sdk.ts`](../../src/core/sdk.ts) — SDK options and construction.
+- [`src/index.ts`](../../src/index.ts) — public exports.
+
+A VS Code extension host is itself Node-based, so it can potentially use `createAgentSession()` in-process. Advantages are lower latency, no JSON serialization, direct typed events, and custom tool/resource integration. Disadvantages are tighter coupling, more difficult fault isolation, extension-host memory/lifecycle risk, and the need to manage session replacement and extension binding carefully.
+
+### 3.3 Existing extension system and RPC UI support
+
+Selesai extensions can register tools, commands, event handlers, and UI operations. In RPC mode, dialog and notification UI is translated into an explicit request/response protocol:
+
+- [`docs/extensions.md`](../extensions.md) — extension API and security model.
+- [`docs/rpc.md`](../rpc.md) — `select`, `confirm`, `input`, `editor`, `notify`, status, widget, title, and editor-text requests.
+
+This is a useful foundation for mapping agent permission questions to VS Code dialogs, status bar items, notifications, and editor input.
+
+## 4. Selesai versus Kilo: capability comparison
+
+| Capability | Kilo current approach | Selesai current position | Assessment |
+|---|---|---|---|
+| VS Code package | Dedicated `packages/kilo-vscode` extension | No dedicated VS Code extension found in this repository | Kilo leads on product packaging. |
+| Main UI | Multiple Webviews/panels/providers | RPC UI protocol can feed a new Webview | Selesai has protocol primitives; Kilo has finished UI. |
+| Agent backend isolation | Spawned local CLI server | Spawned local RPC process | Both isolate backend; Selesai MVP is simpler. |
+| Backend network API | Authenticated localhost HTTP + SSE | No TCP/HTTP RPC server; stdin/stdout JSONL | Kilo leads for multi-client/network-capable architecture. |
+| Transport auth | Generated password; Basic/loopback auth | No RPC auth handshake; private pipes only | Selesai needs auth before exposing network transport. |
+| Streaming | SSE and WebSocket for relevant paths | JSONL event stream | Both support streaming; Selesai JSONL is easy to adapt. |
+| Sessions | Backend session APIs and shared connection service | Rich RPC/SDK session lifecycle and tree operations | Selesai is strong at protocol-level session control. |
+| Extensions/plugins | Agent/runtime extensions and Kilo services | Extension-first tools/events/UI; RPC-compatible UI | Selesai is potentially more extensible, but needs VS Code UX. |
+| MCP | Local stdio and remote transports | Extension/tool ecosystem exists; MCP parity should be audited separately | Kilo has explicit MCP transport integration. |
+| Terminal/PTy | Dedicated terminal manager and WebSocket streaming | RPC bash exists; no Kilo-equivalent VS Code PTY bridge identified | Kilo leads for native terminal UX. |
+| Trust/security | Backend password and process lifecycle controls | Explicit extension trust exists, but RPC has no auth | Selesai needs a dedicated integration security model. |
+| In-process embedding | Backend/client architecture | First-class SDK | Selesai may be better for tightly integrated custom clients. |
+
+## 5. Feasibility: how to build a Selesai VS Code extension
+
+### Phase 1 — local MVP (recommended first)
+
+Build a conventional VS Code extension with:
+
+```text
+VS Code Webview UI
+       │ vscode.postMessage
+       ▼
+Extension host controller
+       │ child_process / existing RpcClient
+       ▼
+selesai --mode rpc (private stdin/stdout)
+```
+
+Minimum components:
+
+- `ExtensionHostController`: owns one Selesai process per workspace/session.
+- `RpcClientAdapter`: wraps the existing `RpcClient`; add or expose extension UI request handling if the current public client does not already do so.
+- `WorkspaceManager`: resolves workspace cwd, session directory, and project trust.
+- `EventStore`: maps streamed events into Webview state, with bounded history and reconnection handling.
+- `WebviewProvider`: chat, streaming text, tool calls, approval questions, model picker, session picker.
+- `Command` registrations: open sidebar, new session, abort, steer, follow-up, model selection.
+- `dispose()` handling: send shutdown/EOF, wait briefly, terminate if necessary.
+
+This does **not** need RPA, LSP, MCP, or a network server.
+
+### Phase 2 — native VS Code experience
+
+Add the features that make an extension feel better than a terminal wrapper:
+
+- Inline editor selection/context actions (“Ask Selesai about this”, “Fix this”).
+- Diff-aware edit review using VS Code `WorkspaceEdit` or controlled file edits.
+- Native permission prompts for writes, shell commands, and external tools.
+- Diagnostics/code actions where agent output can be represented safely.
+- Native terminal/task integration and cancellation.
+- Status bar progress, notifications, output channel, and session restoration.
+- Workspace-specific context files and explicit trust prompts.
+- Webview state restoration and multiple workspace/session routing.
+
+### Phase 3 — Kilo-like backend facade (only if needed)
+
+If Selesai needs multiple clients, remote control, or richer WebSocket/SSE behavior, add an authenticated local server mode rather than exposing raw stdin/stdout through an ad-hoc bridge.
+
+Suggested shape:
+
+```text
+VS Code extension ── authenticated HTTP/SSE or WebSocket ── Selesai server
+```
+
+Requirements before shipping:
+
+- Bind to loopback by default, never `0.0.0.0` by accident.
+- Generate a high-entropy per-process secret.
+- Require authentication on every endpoint/stream.
+- Scope sessions and cwd to the requesting workspace/client.
+- Validate origin and reject cross-workspace access.
+- Provide process parent watchdog and graceful shutdown.
+- Avoid leaking session paths, API keys, prompts, or tool output in logs.
+- Define protocol versioning and event replay/reconnect semantics.
+- Add rate limits and explicit authorization for destructive operations.
+
+## 6. Key risks and design decisions
+
+### Security
+
+Selesai's RPC stdin/stdout is relatively safe because it is private to the spawned child process. It has no token, handshake, or authorization layer. It must **not** simply be put behind a TCP port. A Kilo-like server facade needs authentication, loopback binding, workspace isolation, and process lifecycle controls.
+
+Selesai extensions execute with full system permissions, as documented in [`docs/extensions.md`](../extensions.md). The VS Code extension should not silently enable untrusted project-local extensions or resources. Mirror VS Code's workspace trust decision in the agent startup path.
+
+### Prompt completion versus acceptance
+
+RPC prompt acceptance is not completion. The UI must track the asynchronous event stream and mark a run complete only on the settled/end lifecycle event. This is essential for streaming text, tool progress, approval prompts, and cancellation.
+
+### RPC UI limitations
+
+RPC mode supports dialogs and simple status/widget notifications but not all TUI capabilities. A VS Code adapter needs to decide how to map or replace unsupported methods such as custom TUI components, terminal raw input, and theme-specific rendering.
+
+### Process versus in-process SDK
+
+Use RPC first when reliability and isolation matter. Use the SDK when the extension needs deep typed access and can own the agent lifecycle. A hybrid is possible: keep the default backend out-of-process, offer an in-process mode for development/advanced integrations.
+
+### Multi-root workspaces
+
+Both resource discovery and tool paths depend on cwd. The extension must choose and persist a workspace root/session mapping rather than relying on the extension host's process cwd. For multi-root workspaces, each session should carry an explicit workspace directory.
+
+## 7. Recommended product strategy
+
+Selesai can be “similar or better than Kilo” if it focuses on its existing strengths instead of copying every transport immediately:
+
+1. **Ship a focused Webview extension over existing RPC.** This delivers value quickly and preserves process isolation.
+2. **Use Selesai's extension-first model as the differentiator:** custom tools, lifecycle hooks, prompt/context injection, subagents, workflows, and provider customization.
+3. **Provide native approvals and diffs**, rather than exposing a terminal transcript inside a Webview.
+4. **Add robust session restoration and workspace routing.** Selesai's RPC/session APIs already provide a good base.
+5. **Add an authenticated HTTP/SSE server only when remote/multi-client requirements justify it.** Do not introduce a network daemon solely to imitate Kilo.
+6. **Add MCP transport parity deliberately** if tool-server interoperability is a product requirement; keep MCP separate from the VS Code UI protocol.
+
+### Final answer to the user's questions
+
+- **Did Kilo connect using RPA?** No evidence. It uses VS Code APIs, Webview messages, a spawned local CLI backend, authenticated localhost HTTP/SSE, feature-specific WebSockets, and MCP for external tools.
+- **Can Selesai connect through RPC?** Yes. Existing Selesai RPC is a strong local integration seam: strict JSONL over a private child process with typed commands/events and extension UI requests.
+- **Can Selesai have a similar or better VS Code extension?** Yes. A local RPC-backed extension is straightforward and likely the right MVP. Selesai can exceed Kilo in extensibility and session/workflow customization, while Kilo currently has an advantage in mature VS Code UX, native terminal/PTY integration, backend HTTP/SSE, and polished multi-provider UI.
+
+## Primary-source references
+
+### Kilo Code
+
+- [Extension activation](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/extension.ts)
+- [Kilo Webview provider](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/KiloProvider.ts)
+- [CLI server manager](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/services/cli-backend/server-manager.ts)
+- [Shared backend connection service](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/services/cli-backend/connection-service.ts)
+- [Backend server config](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/services/cli-backend/types.ts)
+- [MCP transports](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/mcp/index.ts)
+- [PTY WebSocket routing](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/agent-manager/terminal-routing.ts)
+- [PTY WebSocket manager](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/agent-manager/terminal-manager.ts)
+
+### Selesai Code
+
+- [`docs/rpc.md`](../rpc.md)
+- [`docs/sdk.md`](../sdk.md)
+- [`docs/extensions.md`](../extensions.md)
+- [`src/modes/rpc/rpc-mode.ts`](../../src/modes/rpc/rpc-mode.ts)
+- [`src/modes/rpc/rpc-types.ts`](../../src/modes/rpc/rpc-types.ts)
+- [`src/modes/rpc/rpc-client.ts`](../../src/modes/rpc/rpc-client.ts)
+- [`src/core/sdk.ts`](../../src/core/sdk.ts)
+- [`src/index.ts`](../../src/index.ts)

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.4",
 	"description": "Maintained, extension-first Pi coding agent with built-in workflows, subagents, web research, questions, skills, and an enhanced terminal UI.",
 	"type": "module",
 	"repository": {