@selesai/code 0.5.10 → 0.5.12

package/dist/extensions/grep-app/index.ts

@@ -11,6 +11,7 @@ import {
 	type ExtensionAPI,
 	withFileMutationQueue,
 } from "@selesai/code";
+import { Text } from "@earendil-works/pi-tui";
 import { load } from "cheerio";
 import { Type } from "typebox";
 
@@ -165,6 +166,11 @@ export default function grepAppExtension(pi: ExtensionAPI): void {
 				details: { total: response.hits.total, page, resultCount: response.hits.hits.length, fullOutputPath: output.fullOutputPath },
 			};
 		},
+		renderResult(result, _options, theme, context) {
+			if (context.isError) return new Text(theme.fg("error", "✗ grep.app search failed"), 0, 0);
+			const details = result.details as { total?: number; page?: number; resultCount?: number } | undefined;
+			return new Text(theme.fg("success", `✓ grep.app: ${details?.resultCount ?? 0} results · page ${details?.page ?? 1} · ${details?.total ?? 0} total matches`), 0, 0);
+		},
 	});
 
 	pi.registerTool({
@@ -196,5 +202,10 @@ export default function grepAppExtension(pi: ExtensionAPI): void {
 				details: { repo: params.repo, path: params.path, ref: params.ref ?? "HEAD", startLine, endLine, totalLines: allLines.length, fullOutputPath: output.fullOutputPath },
 			};
 		},
+		renderResult(result, _options, theme, context) {
+			if (context.isError) return new Text(theme.fg("error", "✗ GitHub file fetch failed"), 0, 0);
+			const details = result.details as { repo?: string; path?: string; startLine?: number; endLine?: number } | undefined;
+			return new Text(theme.fg("success", `✓ GitHub: ${details?.repo ?? "?"}/${details?.path ?? "?"} · lines ${details?.startLine ?? 1}-${details?.endLine ?? "?"}`), 0, 0);
+		},
 	});
 }

package/dist/extensions/workflow/adapter.ts

@@ -226,8 +226,38 @@ async function resumeController(
   try {
     await persistAfter(controller, before);
     const reconcileBefore = checkpoint(controller);
-    const reconciled = await sm.onArtifactMaybe(controller.deps);
-    await persistAfter(controller, reconcileBefore);
+    let reconciled: WorkflowEffect = { kind: "noOp" };
+    try {
+      reconciled = await sm.onArtifactMaybe(controller.deps);
+      await persistRun(controller);
+      // ponytail: when a resumed run has multiple already-written parent-owned
+      // artifacts, one onArtifactMaybe only advances one phase. Keep reconciling
+      // until we either catch up to the durable file state or hit a blocked/
+      // terminal effect, so resume lands on the furthest valid phase.
+      while (sm.snapshot.active && sm.snapshot.autoArmed) {
+        const further = await sm.onArtifactMaybe(controller.deps);
+        if (
+          further.kind === "noOp" ||
+          further.kind === "blocked" ||
+          further.kind === "terminalNeedsArtifacts"
+        ) break;
+        reconciled = further;
+        await persistRun(controller);
+        if (further.kind === "terminalReady") break;
+      }
+    } catch (error) {
+      // Atomic rollback: on any failure during reconciliation, restore both
+      // in-memory state and durable state to the checkpoint before the whole
+      // reconcile sequence. Do not leave the controller at an intermediate
+      // phase while the run file has already advanced further.
+      restoreCheckpoint(controller, reconcileBefore);
+      try {
+        await persistRun(controller);
+      } catch {
+        // Best-effort rollback failed; still report the original error.
+      }
+      throw error;
+    }
     const current = sm.continueCurrent();
     const terminal = config.phases[config.phases.length - 1];
     const terminalReady = reconciled.kind === "terminalReady" || (sm.snapshot.phase === terminal && !sm.snapshot.autoArmed);
@@ -304,7 +334,7 @@ function makeDeps(pi: ExtensionAPI, config: WorkflowConfig): WorkflowDeps {
 
 // ponytail: the git-based skip predicate shared by both modes today.
 // A mode that wants a different skip rule supplies its own SkipRule.
-async function isEmptyProject(pi: ExtensionAPI): Promise<boolean> {
+async function hasNoGitHistory(pi: ExtensionAPI): Promise<boolean> {
   try {
     const result = await pi.exec("git", ["log", "--oneline", "-1"]);
     return result.code !== 0 || !result.stdout.trim();
@@ -482,7 +512,8 @@ function registerSharedArtifactWriter(pi: ExtensionAPI): void {
         };
       }
       // Most workflows pause at a user-controlled artifact boundary. Task's
-      // plan → loop transition queues the builder/review prompt immediately.
+      // plan → reuse → handoff → loop transitions queue the next phase prompt
+      // immediately when continueAfterArtifact is true.
       const queueNextPhase = controller.config.continueAfterArtifact === true && eff.kind === "advanced";
       applyControllerEffect(controller, ctx, eff, { queuePrompt: queueNextPhase });
       if (eff.kind === "blocked" && eff.reason) {
@@ -519,13 +550,13 @@ export function createWorkflowExtension(
   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
-    // supplies its own skipRules in config and we respect them as-is.
+    // ponytail: default skip rule — reuse is skipped when the project has no
+    // git history. Shared by every mode today; a mode that wants a different
+    // rule supplies its own skipRules in config and we respect them as-is.
     const skipRules = config.skipRules ?? [
       {
         phase: "reuse",
-        shouldSkip: async () => isEmptyProject(pi),
+        shouldSkip: async () => hasNoGitHistory(pi),
       },
     ];
     const sm = new WorkflowStateMachine({ ...config, skipRules });

package/dist/extensions/workflow/modes/task.ts

@@ -4,11 +4,17 @@ import type {
   WorkflowConfig,
   WorkflowModeRegistration,
 } from "../state-machine.ts";
-import { loopCompleteValidator, planValidator } from "../validators.ts";
+import {
+  handoffValidator,
+  loopCompleteValidator,
+  planValidator,
+} from "../validators.ts";
 
-// ponytail: task workflow is only plan → build↔review; the loop's clean marker
-// makes it terminal-ready, and the explicit end tool is the only completion.
-const phases: Phase[] = ["plan", "loop"];
+// ponytail: task workflow is now plan → reuse → handoff → loop. Each parent-
+// owned artifact (plan.md, reuse.md, handoff.md) advances automatically, and
+// the loop's clean marker makes the workflow terminal-ready. The explicit end
+// tool is the only completion.
+const phases: Phase[] = ["plan", "reuse", "handoff", "loop"];
 
 const prompts: Partial<Record<Phase, (ctx: PromptContext) => string>> = {
   plan: ({ artifactDir, userPrompt }) =>
@@ -24,12 +30,38 @@ Call the subagent tool with { agent: "architect", task: "...", output: false } (
 Inspect that result, verify it ends with exactly one machine-readable line on its own:
   WORKFLOW_PLAN_STATUS: ready
 Then immediately call write_workflow_artifact with the complete validated plan as content. Only that parent tool call writes ${artifactDir}/plan.md and advances the workflow.`,
+  reuse: ({ artifactDir }) =>
+    `You are in the REUSE phase of a TASK workflow (optional).
+
+The adapter automatically skips this phase when the project has no git history, so codebase exploration is only useful when commits already exist. Decide whether exploration is still useful; skip if the task creates something wholly new or there is clearly nothing to reuse.
+
+If unsure, ask the user one focused question: "Should I explore the existing codebase for reusable patterns before implementing?" Then follow their answer.
+
+If YES (or user confirms): call the subagent tool with { agent: "explorer", task: "...", output: false } (do NOT pass a model parameter). Craft the task from ${artifactDir}/plan.md pointing it at relevant areas, patterns, and dependencies. It must return the reuse findings inline; do not tell it to write any artifact. Immediately call write_workflow_artifact with those findings as content for ${artifactDir}/reuse.md.
+
+If NO: call write_workflow_artifact with a brief skip note explaining why.
+
+The workflow advances once ${artifactDir}/reuse.md exists.`,
+  handoff: ({ artifactDir }) =>
+    `You are in the HANDOFF phase of a TASK workflow.
+
+Compile a self-contained handoff document so loop-phase sub-agents understand full project context without re-grilling.
+
+Draw from all prior phases:
+- ${artifactDir}/plan.md
+- ${artifactDir}/reuse.md
+
+Call the subagent tool with { agent: "recapper", task: "...", output: false } (do NOT pass a model parameter). Craft the task pointing the recapper at both artifact files and telling it what the task is about. It must return the complete handoff inline; do not tell it to write any artifact.
+
+Inspect that result, verify it ends with exactly one machine-readable line on its own:
+  WORKFLOW_HANDOFF_STATUS: ready
+Then immediately call write_workflow_artifact with the complete validated handoff as content. Only that parent tool call writes ${artifactDir}/handoff.md and advances the workflow.`,
   loop: ({ artifactDir, loopMaxIterations }) =>
     `You are in the LOOP (orchestration) phase of a TASK workflow. The workflow ENGINE owns the implement→review loop — you do NOT track iterations or decide when the loop is clean.
 
-Use read to inspect ${artifactDir}/plan.md. Using that context, GENERATE YOUR OWN delegation prompt:
+Use read to inspect ${artifactDir}/plan.md, ${artifactDir}/reuse.md, and ${artifactDir}/handoff.md. Using that context, GENERATE YOUR OWN delegation prompt:
 
-Call the subagent tool with { agent: "builder", task: "...", output: false } (do NOT pass a model parameter). Give it the plan context, tailored to this task. Instruct it to implement every task in plan.md in order. All code changes go in the workspace, never in ${artifactDir}. The builder must return its completion summary inline.
+Call the subagent tool with { agent: "builder", task: "...", output: false } (do NOT pass a model parameter). Give it plan + reuse + handoff context, tailored to this task. Instruct it to implement every task in plan.md in order. All code changes go in the workspace, never in ${artifactDir}. The builder must return its completion summary inline.
 
 After the builder returns, call the subagent tool with { agent: "commentator", task: "...", output: false }. Craft the review task YOURSELF. The commentator must return its review inline. Each commentator review MUST end with exactly one machine-readable line:
   WORKFLOW_REVIEW_STATUS: clean
@@ -44,19 +76,21 @@ const config: WorkflowConfig = {
   phases,
   phaseArtifacts: {
     plan: "plan.md",
+    reuse: "reuse.md",
+    handoff: "handoff.md",
     loop: "loop-complete.md",
   },
   prompts,
   skipRules: [],
   artifactValidators: {
     plan: planValidator,
+    handoff: handoffValidator,
     loop: loopCompleteValidator,
   },
   closeValidators: { "loop-complete.md": loopCompleteValidator },
   closeArtifacts: ["loop-complete.md"],
   loopMaxIterations: 3,
-  // Task is plan → build. Continue directly into the loop when architect
-  // finishes, rather than requiring a second /workflow-task interaction.
+  // Each parent-owned artifact automatically queues the next phase prompt.
   continueAfterArtifact: true,
   statusKey: "task",
   entryType: "task-phase",
@@ -66,7 +100,8 @@ const config: WorkflowConfig = {
 export const taskMode: WorkflowModeRegistration = {
   config,
   commandName: "workflow-task",
-  commandDescription: "Run the task workflow (plan → build↔review loop)",
+  commandDescription:
+    "Run the task workflow (plan → reuse → handoff → build↔review loop)",
   toolNames: {
     start: "start_task_workflow",
     resume: "resume_task_workflow",

package/docs/workflows.md

@@ -120,17 +120,18 @@ That's it. The loader picks it up at boot (`package.json` loads only `./extensio
 
 ## Built-in modes
 
-### `task` — rapid plan + build/review loop
+### `task` — plan → codebase exploration → handoff → build/review loop
 
-The simplest workflow: an architect subagent produces a validated `plan.md`, then a builder↔commentator review loop runs (max 3 blocking rounds). A clean review makes the workflow terminal-ready; `end_task_workflow` completes it.
+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_task_workflow` completes it.
 
-Lifecycle: `plan → loop (build ↔ review) → terminal-ready → end_task_workflow`
+Lifecycle: `plan → reuse → handoff → loop (build ↔ review) → terminal-ready → end_task_workflow`
 
 - `/workflow-task <goal>` — start a new run
 - `/workflow-task resume` — list and resume active runs
 - `/workflow-task help` — show the lifecycle
-- Its ready plan automatically queues the builder↔review loop
-- No grilling, research, reuse, or handoff phases
+- Valid `plan.md`, `reuse.md`, and `handoff.md` each automatically queue the next phase prompt (the workflow does not pause at those boundaries)
+- No grilling, research, or audit phases
+- `reuse.md` is optional; it is skipped automatically when the project has no git history
 
 ## Config reference
 
@@ -141,11 +142,11 @@ Lifecycle: `plan → loop (build ↔ review) → terminal-ready → end_task_wor
 | `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` on empty projects). |
+| `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`). |
-| `continueAfterArtifact?` | `boolean` | Queue the next phase prompt after the parent writes a valid artifact. `task` enables this for plan → build. |
+| `continueAfterArtifact?` | `boolean` | Queue the next phase prompt after the parent writes a valid artifact. `task` enables this at every parent-owned artifact boundary (plan, reuse, handoff) so the workflow flows automatically into the loop. |
 
 ### Adapter options
 
@@ -169,7 +170,7 @@ Runs are **never** auto-resumed on session start. At most one run can be attache
 - `/workflow-prototype resume`, `/workflow-quick resume`, or `/workflow-task resume` lists active runs (and offers a UI picker when available).
 - `/workflow-prototype help`, `/workflow-quick help`, or `/workflow-task 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. Artifact writes do not inject the next phase prompt or launch the next subagent; they terminate the parent turn and wait for the user to continue. A mode can opt out of that pause after a parent artifact write; `task` does so after `plan.md` so the build loop starts immediately. Corrupt records are skipped during discovery.
+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. Artifact writes do not inject the next phase prompt or launch the next subagent; they terminate the parent turn and wait for the user to continue. A mode can opt out of that pause after a parent artifact write; `task` does so at every parent-owned artifact boundary (`plan.md`, `reuse.md`, `handoff.md`) so the build loop starts immediately after a valid handoff. Corrupt records are skipped during discovery.
 
 A valid terminal artifact makes a workflow **terminal-ready**; it does not complete the run. Call the mode-specific `end_*_workflow` tool to write `status: "completed"`, append the done entry, and terminate. This is the only completion path.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@selesai/code",
-	"version": "0.5.10",
+	"version": "0.5.12",
 	"description": "Selesai coding agent",
 	"type": "module",
 	"piConfig": {