@selesai/code 0.3.10 → 0.5.0

package/dist/extensions/workflow/adapter.ts

@@ -12,7 +12,8 @@ import type {
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { access, mkdir, readFile, writeFile } from "node:fs/promises";
-import { isAbsolute, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+import { basename, resolve } from "node:path";
 
 import {
   WorkflowStateMachine,
@@ -21,31 +22,25 @@ import {
   type WorkflowEffect,
   type WorkflowEntry,
   type FooterState,
-  type Phase,
+  type WorkflowSnapshot,
 } from "./state-machine.ts";
+import {
+  WORKFLOW_STATE_FILENAME,
+  type LoopState,
+  type PersistedWorkflowRun,
+  type WorkflowModes,
+  listResumableWorkflowRuns,
+  resolveWorkflowRun,
+  saveWorkflowRun,
+} from "./run-state.ts";
 import { MARKERS } from "./validators.ts";
 
-function slugify(s: string): string {
-  const slug = s
-    .toLowerCase()
-    // ponytail: u-flag so Unicode chars (Chinese, emoji, etc.) are also
-    // treated as non-alphanumeric and replaced with dashes — without /u,
-    // JS’s \W shorthand only matches ASCII, leaving Unicode in paths
-    // which confuses agents and tools.
-    .replace(/[^a-z0-9]+/ug, "-")
-    .replace(/^-+|-+$/g, "")
-    .slice(0, 40);
-  return slug || "workflow";
-}
-
-function timestamp(): string {
-  const d = new Date();
-  const p = (n: number) => String(n).padStart(2, "0");
-  return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
+function defaultArtifactPathFor(_goal: string, base: string): string {
+  return resolve(base, randomUUID());
 }
 
-function defaultArtifactPathFor(goal: string, base: string): string {
-  return `${base}/${timestamp()}-${slugify(goal)}`;
+function artifactsBaseFor(config: WorkflowConfig): string {
+  return resolve(config.artifactsBase ?? "./.selesai/artifacts");
 }
 
 async function realFileExists(path: string): Promise<boolean> {
@@ -57,18 +52,6 @@ async function realFileExists(path: string): Promise<boolean> {
   }
 }
 
-// ponytail: phases where one spawned subagent owns the phase artifact. Force
-// the child `output` path; child processes do not share the parent's workflow
-// state, so the parent-scoped write_workflow_artifact tool cannot help there.
-// Plan 5: these are also the single-owner phases — parallel/chain calls are
-// blocked here because one agent must own plan.md / reuse.md / handoff.md /
-// review.md. Loop is engine-owned (Plan 3) and may fan out.
-const FORCE_OUTPUT_PHASES = new Set<Phase>(["plan", "reuse", "handoff", "audit"]);
-
-// ponytail: phases where the parent can save subagent text as the artifact
-// when the child did not write the file itself (dumb/local models).
-const SUBAGENT_FALLBACK_PHASES = new Set<Phase>(["plan", "reuse", "handoff", "audit"]);
-
 function textFromToolResultContent(content: unknown): string | undefined {
   if (!Array.isArray(content)) return undefined;
   const parts: string[] = [];
@@ -81,75 +64,23 @@ function textFromToolResultContent(content: unknown): string | undefined {
   return joined || undefined;
 }
 
-function validatorForPhaseArtifact(config: WorkflowConfig, phase: Phase) {
-  const phaseValidator = config.artifactValidators?.[phase];
-  if (phaseValidator) return phaseValidator;
-  const file = config.phaseArtifacts[phase];
-  if (!file) return undefined;
-  const isTerminal = config.phases[config.phases.length - 1] === phase;
-  if (!isTerminal || !config.closeArtifacts.includes(file)) return undefined;
-  return config.closeValidators?.[file];
-}
-
-function shouldReplaceInvalidArtifact(
-  config: WorkflowConfig,
-  phase: Phase,
-  currentContent: string,
-  fallbackContent: string,
-): boolean {
-  const validator = validatorForPhaseArtifact(config, phase);
-  if (!validator) return false;
-  return !validator(currentContent).ok && validator(fallbackContent).ok;
-}
-
-// ponytail: rewrite the subagent tool input so the child writes its output
-// directly to ${artifactDir}/${file} as an absolute path. Absolute paths pass
-// through resolveSingleOutputPath verbatim, so injectOutputPathSystemPrompt
-// then forces the child to the correct location instead of repo root.
-// Mutates `input` in place (tool_call handlers can patch event.input).
-// No-op unless the workflow is active, in a force-output phase, and the call
-// targets the `subagent` tool. Respects an explicit absolute caller output.
-function forceSubagentOutputToArtifactDir(
-  input: Record<string, unknown>,
-  artifactDir: string,
-  file: string,
-  onlyAgents?: Set<string>,
-): void {
-  const dest = resolve(artifactDir, file);
-  const shouldForce = (agent: string) => !onlyAgents || onlyAgents.has(agent);
-  // Single-agent call: { agent, task, output?, ... }
-  if (typeof input.agent === "string") {
-    if (!shouldForce(input.agent)) return;
-    const existing = input.output;
-    if (typeof existing === "string" && isAbsolute(existing)) return; // caller pinned it
-    input.output = dest;
-    return;
-  }
-  // Top-level parallel: { tasks: [{ agent, output? }, ...] }
+// Mutates a workflow subagent invocation to suppress both its configured
+// default output and any caller-provided child output path. `output: false`
+// preserves the normal inline result, which the parent must write explicitly.
+function disableSubagentOutput(input: Record<string, unknown>): void {
+  if (typeof input.agent === "string") input.output = false;
   if (Array.isArray(input.tasks)) {
     for (const task of input.tasks) {
-      if (task && typeof task === "object" && typeof task.agent === "string" && shouldForce(task.agent)) {
-        const ex = task.output;
-        if (typeof ex === "string" && isAbsolute(ex)) continue;
-        task.output = dest;
-      }
+      if (task && typeof task === "object") task.output = false;
     }
-    return;
   }
-  // Chain: { chain: [{ agent, output?, parallel: [{ agent, output? }] }] }
   if (Array.isArray(input.chain)) {
     for (const step of input.chain) {
       if (!step || typeof step !== "object") continue;
-      if (typeof step.agent === "string" && shouldForce(step.agent)) {
-        const ex = step.output;
-        if (!(typeof ex === "string" && isAbsolute(ex))) step.output = dest;
-      }
+      step.output = false;
       if (Array.isArray(step.parallel)) {
         for (const task of step.parallel) {
-          if (task && typeof task === "object" && typeof task.agent === "string" && shouldForce(task.agent)) {
-            const ex = task.output;
-            if (!(typeof ex === "string" && isAbsolute(ex))) task.output = dest;
-          }
+          if (task && typeof task === "object") task.output = false;
         }
       }
     }
@@ -157,8 +88,8 @@ function forceSubagentOutputToArtifactDir(
 }
 
 export interface WorkflowAdapterOptions {
-  toolNames: { start: string; end: string };
-  toolLabels: { start: string; end: string };
+  toolNames: { start: string; resume: string; end: string };
+  toolLabels: { start: string; resume: string; end: string };
   commandName: string;
   commandDescription: string;
 }
@@ -168,26 +99,14 @@ interface WorkflowController {
   config: WorkflowConfig;
   sm: WorkflowStateMachine;
   deps: WorkflowDeps;
-  // ponytail: Plan 3 — engine-owned loop state. Lives on the controller, not
-  // the state machine: the SM only cares "does loop-complete.md exist →
-  // advance"; the adapter owns iteration counting + marker parsing + driving
-  // the next subagent call. Cleared when the phase leaves "loop".
-  // Ceiling: not persisted across session restart — a restart re-runs the
-  // loop from round 0. Acceptable for a prototype workflow.
+  // The state machine stays pure; the adapter persists this orchestration
+  // detail alongside the state-machine snapshot.
   loopState?: LoopState;
+  run?: PersistedWorkflowRun;
   seenToolCallIds: Set<string>;
   lastBlockedKey?: string;
 }
 
-// ponytail: Plan 3 — loop orchestration state. The parent model does not
-// remember iterations; the adapter counts review rounds, parses the
-// commentator's WORKFLOW_REVIEW_STATUS marker, and drives the next step.
-interface LoopState {
-  reviewRound: number;
-  maxIterations: number;
-  stage: "building" | "reviewing" | "clean" | "maxed";
-}
-
 const WORKFLOW_ARTIFACT_TOOL = "write_workflow_artifact";
 // ponytail: shared across all module copies so prototype + quick registration
 // can race. Module-level state alone is not enough when the loader runs each
@@ -210,6 +129,141 @@ function activeControllersFor(pi: ExtensionAPI): WorkflowController[] {
   return registry.controllers.filter((c) => c.pi === pi && c.sm.snapshot.active);
 }
 
+function isRegisteredController(controller: WorkflowController): boolean {
+  return registry.controllers.includes(controller);
+}
+
+// Extension reload can reuse the same ExtensionAPI object while this module's
+// global registry survives. Replace a mode's old controller so its active,
+// pre-reload state cannot handle new tool results without a persisted run.
+function replaceControllerFor(pi: ExtensionAPI, mode: string): void {
+  for (let i = registry.controllers.length - 1; i >= 0; i--) {
+    const controller = registry.controllers[i]!;
+    if (controller.pi === pi && controller.config.mode === mode) {
+      registry.controllers.splice(i, 1);
+    }
+  }
+}
+
+function modesFor(config: WorkflowConfig): WorkflowModes {
+  return { [config.mode]: config.phases };
+}
+
+function snapshotRun(controller: WorkflowController): PersistedWorkflowRun {
+  if (!controller.run) throw new Error("No workflow run is attached.");
+  const snapshot = controller.sm.snapshot;
+  return {
+    ...controller.run,
+    status: snapshot.active ? "active" : "completed",
+    goal: snapshot.userPrompt,
+    artifactDir: snapshot.artifactDir,
+    phase: snapshot.phase,
+    autoArmed: snapshot.autoArmed,
+    loopState: controller.loopState,
+    updatedAt: new Date().toISOString(),
+  };
+}
+
+async function persistRun(controller: WorkflowController): Promise<void> {
+  const run = snapshotRun(controller);
+  await saveWorkflowRun(run);
+  controller.run = run;
+}
+
+interface ControllerCheckpoint {
+  snapshot: WorkflowSnapshot;
+  loopState?: LoopState;
+  run?: PersistedWorkflowRun;
+}
+
+function checkpoint(controller: WorkflowController): ControllerCheckpoint {
+  return {
+    snapshot: controller.sm.snapshot,
+    loopState: controller.loopState && { ...controller.loopState },
+    run: controller.run && { ...controller.run, loopState: controller.run.loopState && { ...controller.run.loopState } },
+  };
+}
+
+function restoreCheckpoint(controller: WorkflowController, before: ControllerCheckpoint): void {
+  controller.sm.rehydrate(before.snapshot);
+  controller.loopState = before.loopState;
+  controller.run = before.run;
+}
+
+async function persistAfter(controller: WorkflowController, before: ControllerCheckpoint): Promise<void> {
+  try {
+    await persistRun(controller);
+  } catch (error) {
+    restoreCheckpoint(controller, before);
+    throw error;
+  }
+}
+
+async function resumeController(
+  controller: WorkflowController,
+  ctx: ExtensionContext,
+  selector: string,
+  endTool: string,
+): Promise<any> {
+  const { pi, config, sm } = controller;
+  if (activeControllersFor(pi).length) {
+    return { content: [{ type: "text", text: "A workflow is already active. End it before resuming another run." }], details: { alreadyActive: true } };
+  }
+  let selected;
+  try {
+    selected = await resolveWorkflowRun(selector, artifactsBaseFor(config), modesFor(config));
+    if (selected.run.status !== "active") throw new Error("Completed workflow runs cannot be resumed.");
+    if (selected.run.mode !== config.mode) throw new Error(`This is a ${selected.run.mode} run, not ${config.mode}.`);
+  } catch (error) {
+    return { content: [{ type: "text", text: `Cannot resume workflow: ${error instanceof Error ? error.message : String(error)}` }], details: { rejected: true } };
+  }
+  const before = checkpoint(controller);
+  sm.rehydrate({ active: true, phase: selected.run.phase, userPrompt: selected.run.goal, artifactDir: selected.run.artifactDir, autoArmed: selected.run.autoArmed });
+  controller.run = selected.run;
+  controller.loopState = selected.run.loopState;
+  controller.seenToolCallIds.clear();
+  controller.lastBlockedKey = undefined;
+  try {
+    await persistAfter(controller, before);
+    const reconcileBefore = checkpoint(controller);
+    const reconciled = await sm.onArtifactMaybe(controller.deps);
+    await persistAfter(controller, reconcileBefore);
+    const current = sm.continueCurrent();
+    const terminal = config.phases[config.phases.length - 1];
+    const terminalReady = reconciled.kind === "terminalReady" || (sm.snapshot.phase === terminal && !sm.snapshot.autoArmed);
+    if (terminalReady) {
+      if (current.kind === "advanced") {
+        applyFooter(ctx, current.footer);
+        applyEntry(pi, config, current.entry, controller.run);
+      }
+      continueAgent(pi, ctx, `Workflow is terminal-ready. Verify ${sm.snapshot.artifactDir} and call ${endTool} to complete it.`);
+    } else if (sm.snapshot.phase === "loop" && controller.loopState?.stage === "maxed") {
+      if (current.kind === "advanced") {
+        applyFooter(ctx, current.footer);
+        applyEntry(pi, config, current.entry, controller.run);
+      }
+      ctx.ui.notify(`Workflow loop is paused after ${controller.loopState.reviewRound}/${controller.loopState.maxIterations} blocking review rounds. Inspect ${sm.snapshot.artifactDir}/${controller.loopState.reviewPath ?? "loop-review-<round>.md"} before continuing.`, "warning");
+    } else if (sm.snapshot.phase === "loop" && controller.loopState) {
+      if (current.kind === "advanced") {
+        applyFooter(ctx, current.footer);
+        applyEntry(pi, config, current.entry, controller.run);
+      }
+      const ls = controller.loopState;
+      continueAgent(pi, ctx, ls.stage === "reviewing"
+        ? `Resume the loop at review round ${ls.reviewRound + 1}: call the subagent tool now with { agent: "commentator", task: "..." } to review the builder's uncommitted diff against ${sm.snapshot.artifactDir}/plan.md. End the review with WORKFLOW_REVIEW_STATUS: clean or WORKFLOW_REVIEW_STATUS: blocking.`
+        : `Resume the loop at review round ${ls.reviewRound}: call the subagent tool now with { agent: "builder", task: "..." } to address the feedback in ${sm.snapshot.artifactDir}/${ls.reviewPath ?? "loop-review-<round>.md"}.`);
+    } else {
+      applyControllerEffect(controller, ctx, current);
+    }
+  } catch (error) {
+    return { content: [{ type: "text", text: `Cannot resume workflow: state could not be persisted: ${error instanceof Error ? error.message : String(error)}` }], details: { persistenceError: true } };
+  }
+  return {
+    content: [{ type: "text", text: `Resumed ${config.mode} workflow ${controller.run!.id} at ${sm.snapshot.phase}. Artifacts: ${selected.statePath}` }],
+    details: { runId: controller.run!.id, statePath: selected.statePath, phase: sm.snapshot.phase },
+  };
+}
+
 // ponytail: builds the deps bundle the adapter injects into the state machine.
 // The skip predicate wraps pi.exec("git"...) — the only true-external seam.
 function makeDeps(pi: ExtensionAPI, config: WorkflowConfig): WorkflowDeps {
@@ -276,8 +330,11 @@ function footerText(footer: FooterState, ctx: ExtensionContext): string | undefi
   return ctx.ui.theme.fg("warning", footer.text);
 }
 
-function applyEntry(pi: ExtensionAPI, config: WorkflowConfig, entry: WorkflowEntry): void {
-  pi.appendEntry(config.entryType, entry);
+function applyEntry(pi: ExtensionAPI, config: WorkflowConfig, entry: WorkflowEntry, run?: PersistedWorkflowRun): void {
+  pi.appendEntry(config.entryType, {
+    ...entry,
+    ...(run ? { workflowStatePath: resolve(run.artifactDir, WORKFLOW_STATE_FILENAME), runId: run.id } : {}),
+  });
 }
 
 function applyFooter(ctx: ExtensionContext, footer: FooterState): void {
@@ -304,16 +361,18 @@ function applyEffect(
   ctx: ExtensionContext,
   config: WorkflowConfig,
   eff: WorkflowEffect,
+  run?: PersistedWorkflowRun,
+  queuePrompt = true,
 ): void {
   switch (eff.kind) {
     case "started":
     case "advanced":
-      if ("entry" in eff) applyEntry(pi, config, eff.entry);
+      if ("entry" in eff) applyEntry(pi, config, eff.entry, run);
       if ("footer" in eff) applyFooter(ctx, eff.footer);
-      if (eff.prompt) continueAgent(pi, ctx, eff.prompt);
+      if (queuePrompt && eff.prompt) continueAgent(pi, ctx, eff.prompt);
       return;
     case "closed":
-      if ("entry" in eff) applyEntry(pi, config, eff.entry);
+      if ("entry" in eff) applyEntry(pi, config, eff.entry, run);
       if ("footer" in eff) applyFooter(ctx, eff.footer);
       ctx.ui.notify(
         `${config.footerLabel} workflow complete. Artifacts: ${eff.artifactDir}`,
@@ -321,17 +380,16 @@ function applyEffect(
       );
       return;
     case "terminalNeedsArtifacts":
-      if (eff.promptToQueue) continueAgent(pi, ctx, eff.promptToQueue);
+      if (queuePrompt && eff.promptToQueue) continueAgent(pi, ctx, eff.promptToQueue);
       return;
     case "blocked":
-      // ponytail: Plan 4 — surface the semantic reason so a subagent-driven
-      // phase (plan/handoff/audit) learns which marker is missing instead of
-      // the workflow appearing to stall after the artifact was written.
-      if (eff.reason) {
+      if (queuePrompt && eff.reason) {
         continueAgent(pi, ctx, `Phase ${eff.phase} artifact exists but is not approved: ${eff.reason}. Edit it via write_workflow_artifact to add the required marker, then the workflow will advance.`);
       }
       return;
     case "terminalReady":
+      if (queuePrompt) continueAgent(pi, ctx, `Terminal artifacts are ready. Call the explicit end workflow tool to complete this run.`);
+      return;
     case "endBlocked":
     case "idle":
     case "noOp":
@@ -349,6 +407,7 @@ function applyControllerEffect(
   controller: WorkflowController,
   ctx: ExtensionContext,
   eff: WorkflowEffect,
+  options: { queuePrompt?: boolean } = {},
 ): void {
   const blockedKey = blockedKeyFor(eff);
   if (blockedKey) {
@@ -357,13 +416,25 @@ function applyControllerEffect(
   } else if (eff.kind !== "noOp") {
     controller.lastBlockedKey = undefined;
   }
-  applyEffect(controller.pi, ctx, controller.config, eff);
+  applyEffect(controller.pi, ctx, controller.config, eff, controller.run, options.queuePrompt);
 }
 
 function isSubagentManagementAction(input: Record<string, unknown> | undefined): boolean {
   return typeof input?.action === "string";
 }
 
+function commandHelp(config: WorkflowConfig, options: WorkflowAdapterOptions): string {
+  const command = `/${options.commandName}`;
+  return [
+    `${config.footerLabel} workflow`,
+    `${command} <goal> — start a new durable run.`,
+    `${command} resume — list resumable runs.`,
+    `${command} resume <run-id|artifact-dir|workflow.json> — explicitly resume one.`,
+    `Phases advance when their artifacts are written. Runs never auto-resume after reload.`,
+    `Only one run may be attached; ${options.toolNames.end} explicitly completes a terminal-ready run.`,
+  ].join("\n");
+}
+
 function registerSharedArtifactWriter(pi: ExtensionAPI): void {
   if (registry.writerRegisteredFor.has(pi)) return;
   registry.writerRegisteredFor.add(pi);
@@ -399,17 +470,38 @@ function registerSharedArtifactWriter(pi: ExtensionAPI): void {
       const path = resolve(snap.artifactDir, file);
       await mkdir(snap.artifactDir, { recursive: true });
       await writeFile(path, params.content, "utf8");
-      const eff = await controller.sm.onArtifactMaybe(controller.deps);
-      applyControllerEffect(controller, ctx, eff);
+      const before = checkpoint(controller);
+      let eff: WorkflowEffect;
+      try {
+        eff = await controller.sm.onArtifactMaybe(controller.deps);
+        await persistAfter(controller, before);
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: `Wrote ${path}, but could not persist workflow state: ${error instanceof Error ? error.message : String(error)}` }],
+          details: { mode: controller.config.mode, phase: snap.phase, path, persistenceError: true },
+        };
+      }
+      // Most workflows pause at a user-controlled artifact boundary. Task's
+      // plan → loop transition queues the builder/review prompt immediately.
+      const queueNextPhase = controller.config.continueAfterArtifact === true && eff.kind === "advanced";
+      applyControllerEffect(controller, ctx, eff, { queuePrompt: queueNextPhase });
       if (eff.kind === "blocked" && eff.reason) {
         return {
           content: [{ type: "text", text: `Wrote ${path}, but it is not approved: ${eff.reason}. Re-write it via write_workflow_artifact to add the required marker.` }],
           details: { mode: controller.config.mode, phase: snap.phase, path, file, blocked: true, reason: eff.reason },
         };
       }
+      const advanced = eff.kind === "advanced";
       return {
-        content: [{ type: "text", text: `Wrote ${path}.` }],
-        details: { mode: controller.config.mode, phase: snap.phase, path, file },
+        content: [{ type: "text", text: advanced
+          ? queueNextPhase
+            ? `Wrote ${path}. Phase advanced to ${eff.phase}; the next workflow phase is queued.`
+            : `Wrote ${path}. Phase advanced to ${eff.phase}; wait for the user to continue the workflow.`
+          : `Wrote ${path}.` }],
+        details: { mode: controller.config.mode, phase: snap.phase, path, file, advanced },
+        // Stop only at user-controlled boundaries. Task deliberately queues
+        // its loop prompt, so terminating here would discard that continuation.
+        terminate: advanced && !queueNextPhase,
       };
     },
     renderResult(result, _options, theme) {
@@ -425,6 +517,7 @@ export function createWorkflowExtension(
   options: WorkflowAdapterOptions,
 ): (pi: ExtensionAPI) => void {
   return function workflowExtension(pi: ExtensionAPI): void {
+    replaceControllerFor(pi, config.mode);
     const deps = makeDeps(pi, config);
     // ponytail: default skip rule — reuse is skipped on empty projects (no git
     // commits). Shared by every mode today; a mode that wants a different rule
@@ -439,14 +532,14 @@ export function createWorkflowExtension(
     const controller: WorkflowController = { pi, config, sm, deps, seenToolCallIds: new Set() };
     registry.controllers.push(controller);
     registerSharedArtifactWriter(pi);
-    const { start, end } = options.toolNames;
+    const { start, resume, end } = options.toolNames;
     const { mode, footerLabel } = config;
 
     // ── start tool ──
     pi.registerTool({
       name: start,
       label: options.toolLabels.start,
-      description: `Start the ${mode} workflow for the given goal. Sets up grilling as the first phase and returns the grilling prompt. Do not call if a workflow is already active.`,
+      description: `Start the ${mode} workflow for the given goal. Sets up ${config.phases[0]} as the first phase and returns its prompt. Do not call if a workflow is already active.`,
       promptSnippet: `${start}(goal) - start the ${mode} workflow; goal is what the user wants to build.`,
       promptGuidelines: [
         `Call ${start} only when the user explicitly asks to start a ${mode} workflow and none is active.`,
@@ -465,12 +558,35 @@ export function createWorkflowExtension(
             details: { phase: other.sm.snapshot.phase, alreadyActive: true },
           };
         }
+        const before = checkpoint(controller);
         const eff = await sm.start(params.goal, deps);
         if (eff.kind === "started") {
+          controller.run = {
+            version: 1,
+            id: basename(sm.snapshot.artifactDir),
+            mode,
+            status: "active",
+            goal: sm.snapshot.userPrompt,
+            artifactDir: sm.snapshot.artifactDir,
+            phase: sm.snapshot.phase,
+            autoArmed: sm.snapshot.autoArmed,
+            createdAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+          };
+          try {
+            await persistAfter(controller, before);
+          } catch (error) {
+            return {
+              content: [{ type: "text", text: `Could not start durable workflow: ${error instanceof Error ? error.message : String(error)}` }],
+              details: { persistenceError: true },
+            };
+          }
           controller.seenToolCallIds.clear();
           controller.lastBlockedKey = undefined;
         }
-        applyControllerEffect(controller, ctx, eff);
+        // The start tool result already contains the grilling prompt. Queueing
+        // it again creates a duplicate autonomous turn.
+        applyControllerEffect(controller, ctx, eff, { queuePrompt: false });
         if (eff.kind === "alreadyActive") {
           return {
             content: [
@@ -498,6 +614,27 @@ export function createWorkflowExtension(
       },
     } satisfies ToolDefinition);
 
+    // ── explicit resume tool ──
+    pi.registerTool({
+      name: resume,
+      label: options.toolLabels.resume,
+      description: `Resume an explicitly selected ${mode} workflow run. Pass a run id, artifact directory, or workflow.json path.`,
+      promptSnippet: `${resume}(run) - resume an explicit ${mode} workflow run; run is its id, artifact directory, or workflow.json path.`,
+      promptGuidelines: [
+        `Call ${resume} only when the user explicitly selects a ${mode} workflow run.`,
+        "Workflow runs never resume automatically after reload.",
+      ],
+      parameters: Type.Object({ run: Type.String({ description: "Run id, artifact directory, or workflow.json path." }) }),
+      async execute(_id, params, _signal, _onUpdate, ctx) {
+        return resumeController(controller, ctx, params.run, end);
+      },
+      renderResult(result, _options, theme) {
+        const d = result.details as { rejected?: boolean; persistenceError?: boolean; phase?: string };
+        const failed = d.rejected || d.persistenceError;
+        return new Text(theme.fg(failed ? "warning" : "success", failed ? "○ workflow resume rejected" : `✓ workflow resumed · ${d.phase}`), 0, 0);
+      },
+    } satisfies ToolDefinition);
+
     // ── end tool ──
     pi.registerTool({
       name: end,
@@ -509,7 +646,18 @@ export function createWorkflowExtension(
       ],
       parameters: Type.Object({}),
       async execute(_id, _params, _signal, _onUpdate, ctx) {
+        const before = checkpoint(controller);
         const eff = await sm.end(deps);
+        if (eff.kind === "closed") {
+          try {
+            await persistAfter(controller, before);
+          } catch (error) {
+            return {
+              content: [{ type: "text", text: `Cannot end: workflow state could not be persisted: ${error instanceof Error ? error.message : String(error)}` }],
+              details: { persistenceError: true },
+            };
+          }
+        }
         applyControllerEffect(controller, ctx, eff);
         if (eff.kind === "closed") {
           controller.seenToolCallIds.clear();
@@ -563,162 +711,66 @@ export function createWorkflowExtension(
       },
     } satisfies ToolDefinition);
 
-    // ── session_start: restore state from persisted entries ──
+    // ── session_start: disk state is never auto-attached. A session entry is
+    // merely a convenience pointer for rendering a stale-but-useful footer. ──
     pi.on("session_start", async (_event: any, ctx: ExtensionContext) => {
+      if (!isRegisteredController(controller)) return;
       const entries = ctx.sessionManager.getEntries();
       for (let i = entries.length - 1; i >= 0; i--) {
-        const e = entries[i] as { type: string; customType?: string; data?: any };
-        if (e.type === "custom" && e.customType === config.entryType && e.data) {
-          if (e.data.done) {
-            sm.rehydrate({
-              active: false,
-              phase: e.data.phase as Phase,
-              userPrompt: e.data.userPrompt ?? "",
-              artifactDir: e.data.artifactDir ?? "",
-              autoArmed: false,
-            });
-          } else {
-            sm.rehydrate({
-              active: true,
-              phase: e.data.phase as Phase,
-              userPrompt: e.data.userPrompt ?? "",
-              artifactDir: e.data.artifactDir ?? "",
-              autoArmed: true,
-            });
-          }
-          // ponytail: re-render footer from snapshot without advancing.
-          if (sm.snapshot.active) {
-            ctx.ui.setStatus(
-              config.statusKey,
-              ctx.ui.theme.fg(
-                "warning",
-                `● ${config.footerLabel} · ${config.phases.indexOf(sm.snapshot.phase) + 1}/${config.phases.length} ${sm.snapshot.phase}`,
-              ),
-            );
-          } else {
-            ctx.ui.setStatus(config.statusKey, undefined);
+        const entry = entries[i] as { type: string; customType?: string; data?: any };
+        const data = entry.data;
+        if (entry.type !== "custom" || entry.customType !== config.entryType || !data || data.mode !== mode || typeof data.workflowStatePath !== "string") continue;
+        try {
+          const { run } = await resolveWorkflowRun(data.workflowStatePath, artifactsBaseFor(config), modesFor(config));
+          if (run.status === "active") {
+            ctx.ui.setStatus(config.statusKey, ctx.ui.theme.fg(
+              "warning",
+              `● ${config.footerLabel} · ${config.phases.indexOf(run.phase) + 1}/${config.phases.length} ${run.phase} (resume required)`,
+            ));
           }
-          break;
+        } catch {
+          // Old/custom entries are intentionally non-authoritative.
         }
+        break;
       }
     });
 
-    // ── tool_call: enforce workflow boundaries. ──
+    // ── tool_call: enforce parent-owned artifact boundaries. ──
     pi.on("tool_call", (event: any, _ctx: ExtensionContext) => {
+      if (!isRegisteredController(controller)) return;
       const tool = event.toolName;
       if (tool !== "subagent" && tool !== "write" && tool !== "edit") return;
       const snap = sm.snapshot;
       if (!snap.active) return;
-      if (tool === "subagent" && isSubagentManagementAction(event.input)) return;
-      const file = config.phaseArtifacts[snap.phase];
       if (tool === "write" || tool === "edit") {
         return {
           block: true,
           reason: `Workflow is active (${mode}/${snap.phase}). Use ${WORKFLOW_ARTIFACT_TOOL} for workflow artifacts; workspace edits must be delegated to subagents.`,
         };
       }
-      if (!file || !event.input || !FORCE_OUTPUT_PHASES.has(snap.phase)) return;
-      // ponytail: Plan 5 — single-owner phases reject parallel/chain. One agent
-      // must own the artifact; tasks/chain split ownership and the output
-      // injector cannot pin one file per agent. Loop is exempt (engine-owned).
-      if (Array.isArray(event.input.tasks) || Array.isArray(event.input.chain)) {
-        return {
-          block: true,
-          reason: `Workflow phase ${snap.phase} expects one subagent owner for ${file}; use a single { agent, task } call, not tasks/chain.`,
-        };
-      }
-      // ponytail: Plan 5 — workflow-spawned subagents run fresh by default so
-      // no hidden parent context leaks into the phase owner. Only override
-      // when the caller explicitly pins a context.
-      if (typeof event.input.context !== "string") {
-        event.input.context = "fresh";
-      }
-      // ponytail: Plan 5 — ban model override on workflow-owned phases. The
-      // workflow, not the parent model, picks the agent; a model pin would
-      // silently change cost/quality without the workflow knowing.
-      if (typeof event.input.model === "string") {
-        return {
-          block: true,
-          reason: `Workflow phase ${snap.phase} does not allow a model override on subagent calls; remove the model parameter.`,
-        };
+      if (!isSubagentManagementAction(event.input) && event.input) {
+        // All child results return inline. The parent persists normal phase
+        // artifacts; the loop engine persists its own review files/marker.
+        disableSubagentOutput(event.input);
       }
-      const onlyAgents = snap.phase === "audit" ? new Set(["commentator", "reviewer"]) : undefined;
-      forceSubagentOutputToArtifactDir(event.input, snap.artifactDir, file, onlyAgents);
     });
 
-    // ── tool_result: auto-advance after subagent/bash artifacts. ──
+    // ── tool_result: only the engine-owned loop persists subagent output. ──
     pi.on("tool_result", async (event: any, ctx: ExtensionContext) => {
-      if (event.toolName !== "bash" && event.toolName !== "subagent") return;
-      if (sm.snapshot.active && typeof event.toolCallId === "string") {
+      if (!isRegisteredController(controller)) return;
+      if (event.toolName !== "subagent" || event.isError) return;
+      // Parent-owned phases intentionally do nothing here: the main agent must
+      // inspect the inline child result and call write_workflow_artifact.
+      if (!sm.snapshot.active || sm.snapshot.phase !== "loop" || isSubagentManagementAction(event.input)) return;
+      const eventBefore = checkpoint(controller);
+      if (typeof event.toolCallId === "string") {
         if (controller.seenToolCallIds.has(event.toolCallId)) return;
         controller.seenToolCallIds.add(event.toolCallId);
       }
-      // ponytail: a failed phase-owner tool used to leave the workflow quiet
-      // until the user manually typed /prototype or /quick continue. Re-check
-      // first (in case the tool wrote the artifact before failing), then if
-      // nothing advanced, re-queue the current phase prompt automatically.
-      if (event.isError && sm.snapshot.active) {
-        if (event.toolName === "subagent" && isSubagentManagementAction(event.input)) return;
-        const eff = await sm.onArtifactMaybe(deps);
-        applyControllerEffect(controller, ctx, eff);
-        if (eff.kind === "noOp") {
-          const retry = sm.continueCurrent();
-          continueAgent(
-            pi,
-            ctx,
-            `The previous ${event.toolName} call failed during the ${retry.phase} phase. Stay in this phase and try again.\n\n${retry.prompt}`,
-          );
-        }
-        if (sm.snapshot.phase !== "loop") {
-          controller.loopState = undefined;
-        }
-        return;
-      }
-      // ponytail: if a subagent returned text but did not write the expected
-      // artifact (common with dumb/local models), save the returned text as
-      // the artifact so the workflow can still advance.
-      if (event.toolName === "subagent" && sm.snapshot.active && SUBAGENT_FALLBACK_PHASES.has(sm.snapshot.phase)) {
-        const phase = sm.snapshot.phase;
-        const file = config.phaseArtifacts[phase];
-        if (file) {
-          // ponytail: management actions (list/get/models/doctor/status/...)
-          // return text but are NOT the architect/recapper/... execution
-          // result. Writing their text to plan.md would advance the workflow
-          // on agent-listing output (the `subagent list` result is plain
-          // text). Execution calls set `agent`/`chain`/`tasks`; management
-          // calls set `action`. Only fall back for execution calls.
-          if (!isSubagentManagementAction(event.input)) {
-            const expectedPath = resolve(sm.snapshot.artifactDir, file);
-            const text = textFromToolResultContent(event.content);
-            if (text) {
-              const validator = validatorForPhaseArtifact(config, phase);
-              let shouldWrite = false;
-              if (!(await realFileExists(expectedPath))) {
-                shouldWrite = !validator || validator(text).ok;
-              } else {
-                try {
-                  const current = await readFile(expectedPath, "utf8");
-                  shouldWrite = shouldReplaceInvalidArtifact(config, phase, current, text);
-                } catch {
-                  shouldWrite = false;
-                }
-              }
-              if (shouldWrite) {
-                await mkdir(sm.snapshot.artifactDir, { recursive: true });
-                await writeFile(expectedPath, text, "utf8");
-              }
-            }
-          }
-        }
-      }
-      // ponytail: Plan 3 — engine-owned loop orchestration. The parent model
-      // does NOT track iterations; the adapter counts review rounds, parses the
-      // commentator's WORKFLOW_REVIEW_STATUS marker, and drives the next step
-      // via followUp. Ceiling: there is no pi.callTool() API, so the engine
-      // cannot invoke the subagent tool directly — it sends a followUp the
-      // model is expected to act on. If the model deviates, the loop stalls
-      // until the next tool_result nudges again. loopState is cleared when the
-      // phase leaves "loop" (below).
+      // The adapter owns durable loop state; the normal subagent tool-result
+      // continuation lets the parent choose the next builder/commentator call.
+      // No synthetic follow-up chat is queued. loopState clears when the phase
+      // leaves "loop" (below).
       if (event.toolName === "subagent" && sm.snapshot.active && sm.snapshot.phase === "loop") {
         const dir = sm.snapshot.artifactDir;
         const maxIt = config.loopMaxIterations ?? 3;
@@ -729,15 +781,20 @@ export function createWorkflowExtension(
         const agent = event.input?.agent;
 
         if (agent === "builder") {
-          // Build step done → drive the commentator review.
+          // The normal subagent result resumes the parent turn; record the
+          // next loop stage but do not inject a duplicate follow-up message.
           ls.stage = "reviewing";
-          continueAgent(pi, ctx, `Builder finished. Call the subagent tool now with { agent: "commentator", task: "..." } to review the builder's uncommitted diff against ${dir}/plan.md. Craft the review task yourself based on what matters for this task. End the review with exactly one line on its own:
-  WORKFLOW_REVIEW_STATUS: clean
-or
-  WORKFLOW_REVIEW_STATUS: blocking`);
         } else if (agent === "commentator") {
-          ls.reviewRound += 1;
-          const status = parseLoopReviewStatus(textFromToolResultContent(event.content));
+          const reviewRound = ls.reviewRound + 1;
+          const reviewText = textFromToolResultContent(event.content);
+          if (reviewText) {
+            const reviewPath = `loop-review-${reviewRound}.md`;
+            await mkdir(dir, { recursive: true });
+            await writeFile(resolve(dir, reviewPath), reviewText, "utf8");
+            ls.reviewPath = reviewPath;
+          }
+          ls.reviewRound = reviewRound;
+          const status = parseLoopReviewStatus(reviewText);
           if (status === "clean") {
             ls.stage = "clean";
             await mkdir(dir, { recursive: true });
@@ -756,29 +813,40 @@ or
             // A genuine clean review on a later round still advances — the
             // clean branch above runs first.
           } else {
-            // Blocking (or no marker) → drive a builder fix round.
+            // Blocking (or no marker) → the parent continues with a builder
+            // fix round from the normal subagent result, without a queued chat.
             ls.stage = "building";
-            const reason = status === "blocking"
-              ? "the blocking issues listed in the review"
-              : "the review (no WORKFLOW_REVIEW_STATUS: clean|blocking marker was found)";
-            continueAgent(pi, ctx, `Review round ${ls.reviewRound} was blocking. Call the subagent tool now with { agent: "builder", task: "..." } to fix ${reason}. Give the builder the review feedback and the relevant artifact paths. After the builder returns, the workflow will drive the next review automatically.`);
           }
         }
         // Non-builder/commentator subagent calls in loop fall through to
         // onArtifactMaybe (a no-op unless loop-complete.md exists).
       }
       const eff = await sm.onArtifactMaybe(deps);
-      applyControllerEffect(controller, ctx, eff);
       // Clear loop state once we have left the loop phase (advanced to audit).
       if (sm.snapshot.phase !== "loop") {
         controller.loopState = undefined;
       }
+      try {
+        await persistAfter(controller, eventBefore);
+      } catch (error) {
+        ctx.ui.notify(`Workflow state was not saved: ${error instanceof Error ? error.message : String(error)}`, "warning");
+        return;
+      }
+      // The only artifact written in this handler is loop-complete.md, which
+      // is engine-owned. Parent-written phase artifacts advance inside
+      // write_workflow_artifact instead.
+      applyControllerEffect(controller, ctx, eff);
     });
 
     // ── /<command> ──
     pi.registerCommand(options.commandName, {
       description: options.commandDescription,
       handler: async (args: string, ctx: ExtensionCommandContext) => {
+        const trimmed = args.trim();
+        if (trimmed === "help") {
+          ctx.ui.notify(commandHelp(config, options), "info");
+          return;
+        }
         if (!ctx.isIdle()) {
           ctx.ui.notify(
             `Agent is busy. Wait for it to finish before calling /${options.commandName}.`,
@@ -787,6 +855,36 @@ or
           return;
         }
 
+        if (trimmed === "resume" || trimmed.startsWith("resume ")) {
+          if (sm.snapshot.active) {
+            ctx.ui.notify("A workflow is already active. End it before resuming another run.", "warning");
+            return;
+          }
+          const selector = trimmed.slice("resume".length).trim();
+          if (!selector) {
+            const runs = await listResumableWorkflowRuns(artifactsBaseFor(config), modesFor(config));
+            if (!runs.length) {
+              ctx.ui.notify(`No resumable ${mode} workflows found.`, "info");
+              return;
+            }
+            if (!ctx.hasUI) {
+              ctx.ui.notify(runs.map(({ run }) => `/${options.commandName} resume ${run.id}  # ${run.phase}, ${run.goal}, ${run.updatedAt}`).join("\n"), "info");
+              return;
+            }
+            const labels = runs.map(({ run }) => `${run.id} · ${run.phase} · ${run.goal} · ${run.updatedAt}`);
+            const choice = await ctx.ui.select(`Resume ${mode} workflow`, labels);
+            if (choice === undefined) return;
+            const index = labels.indexOf(choice);
+            if (index < 0) return;
+            const result = await resumeController(controller, ctx, runs[index]!.run.id, end);
+            ctx.ui.notify(result.content[0].text, result.details.rejected || result.details.persistenceError ? "warning" : "info");
+            return;
+          }
+          const result = await resumeController(controller, ctx, selector, end);
+          ctx.ui.notify(result.content[0].text, result.details.rejected || result.details.persistenceError ? "warning" : "info");
+          return;
+        }
+
         if (sm.snapshot.active) {
           let goal = args.trim();
           const choice = ctx.hasUI
@@ -801,7 +899,8 @@ or
           if (choice === undefined) return;
           if (choice.startsWith("Continue")) {
             const eff = sm.continueCurrent();
-            applyControllerEffect(controller, ctx, eff);
+            // The explicit Continue action below sends exactly one prompt.
+            applyControllerEffect(controller, ctx, eff, { queuePrompt: false });
             if (eff.kind === "advanced" && eff.prompt) {
               // continueCurrent already applied footer+entry; send the prompt.
               continueAgent(pi, ctx, eff.prompt);
@@ -820,12 +919,14 @@ or
           }
           const closed = sm.closeCurrent();
           if (closed) {
-            applyEntry(pi, config, closed);
-            ctx.ui.notify(`Closed ${mode} workflow at ${closed.artifactDir}.`, "info");
+            // Detach only: the on-disk active record remains resumable. Only
+            // end_*_workflow writes status: completed.
+            applyEntry(pi, config, { ...closed, done: false }, controller.run);
+            ctx.ui.notify(`Detached ${mode} workflow at ${closed.artifactDir}; it remains resumable.`, "info");
           }
           args = goal;
         } else if (!args.trim()) {
-          ctx.ui.notify(`Usage: /${options.commandName} <what to build>`, "warning");
+          ctx.ui.notify(commandHelp(config, options), "info");
           return;
         }
 
@@ -837,8 +938,27 @@ or
           );
           return;
         }
+        const before = checkpoint(controller);
         const eff = await sm.start(args, deps);
         if (eff.kind === "started") {
+          controller.run = {
+            version: 1,
+            id: basename(sm.snapshot.artifactDir),
+            mode,
+            status: "active",
+            goal: sm.snapshot.userPrompt,
+            artifactDir: sm.snapshot.artifactDir,
+            phase: sm.snapshot.phase,
+            autoArmed: sm.snapshot.autoArmed,
+            createdAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+          };
+          try {
+            await persistAfter(controller, before);
+          } catch (error) {
+            ctx.ui.notify(`Could not start durable workflow: ${error instanceof Error ? error.message : String(error)}`, "warning");
+            return;
+          }
           controller.seenToolCallIds.clear();
           controller.lastBlockedKey = undefined;
         }