@selesai/code 0.9.2 → 0.9.4

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 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
+- **Token-In model identifiers.** Replace the provider's removed `auto`/`auto-premium` identifiers with the bundled `celestial-pro`, `celestial-max`, and `celestial-ultra` models, and point factory defaults and model-specific prompt injection at the supported Celestial IDs.
+
 ## [0.9.2] - 2026-08-20
 
 ### Fixed

package/dist/defaults/models.json

@@ -11,8 +11,8 @@
       },
       "models": [
         {
-          "id": "auto",
-          "name": "Auto",
+          "id": "celestial-pro",
+          "name": "Celestial Pro",
           "reasoning": true,
           "input": ["text"],
           "contextWindow": 393216,
@@ -27,8 +27,24 @@
           }
         },
         {
-          "id": "auto-premium",
-          "name": "Auto",
+          "id": "celestial-max",
+          "name": "Celestial Max",
+          "reasoning": true,
+          "input": ["text"],
+          "contextWindow": 393216,
+          "maxTokens": 64000,
+          "thinkingLevelMap": {
+            "minimal": null,
+            "low": null,
+            "medium": null,
+            "high": null,
+            "xhigh": null,
+            "max": "max"
+          }
+        },
+        {
+          "id": "celestial-ultra",
+          "name": "Celestial Ultra",
           "reasoning": true,
           "input": ["text"],
           "contextWindow": 393216,

package/dist/defaults/settings.json

@@ -9,7 +9,7 @@
     "keepRecentTokens": 32000,
     "reserveTokens": 64000
   },
-  "defaultModel": "auto",
+  "defaultModel": "celestial-pro",
   "defaultProvider": "tokenin",
   "defaultThinkingLevel": "max",
   "doubleEscapeAction": "tree",
@@ -44,22 +44,22 @@
   "subagents": {
     "agentOverrides": {
       "architect": {
-        "model": "tokenin/auto:max"
+        "model": "tokenin/celestial-pro:max"
       },
       "builder": {
-        "model": "tokenin/auto:max"
+        "model": "tokenin/celestial-pro:max"
       },
       "commentator": {
-        "model": "tokenin/auto:max"
+        "model": "tokenin/celestial-pro:max"
       },
       "explorer": {
-        "model": "tokenin/auto:max"
+        "model": "tokenin/celestial-pro:max"
       },
       "recapper": {
-        "model": "tokenin/auto:max"
+        "model": "tokenin/celestial-pro:max"
       },
       "researcher": {
-        "model": "tokenin/auto:max"
+        "model": "tokenin/celestial-pro:max"
       }
     }
   },

package/dist/extensions/model-prompt-injector/config.json

@@ -7,7 +7,7 @@
       "enabled": true
     },
     {
-      "match": ["auto"],
+      "match": ["celestial-*"],
       "mode": "prepend",
       "prompt": "text: You are a helpful software engineer assistant.\n\ndescription: Bootstrap with shell/read, then expose the full Standard tool catalog after the first durable tool call.\n\nwhen you thought, start with `we need...`",
       "enabled": true

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/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.2",
+	"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": {