feat(api): phase(name, { title }, body) overload for static titles

When the title is known at phase-creation time (which is most of the
time — harness code almost always knows what a phase does upfront), the
runtime setTitle path from 0.1.12 is overkill. New overload:

  await phase('pipeline', { title: 'Ingest & transform' }, async () => { … });

Engine's stage() signature accepts either (id, body) or (id, opts, body),
opts = { title?: string }. The stage-enter event carries the static
title, so the TUI renders it on the node's very first frame without
waiting for a follow-up stage-title event. Runtime ctx.setTitle() still
works — if both are used, the dynamic override wins.

Backward compat: every existing `phase(name, body)` keeps working.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: AbhiShake1

CHANGELOG.md

@@ -5,6 +5,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.13] - 2026-04-19
+
+### Added
+- `phase(name, { title }, body)` overload — static title at phase-creation time. Use when you know the title upfront; cleaner than the runtime `setTitle` path. Runtime `ctx.setTitle(...)` still works and overrides the static title. `stage-enter` event now carries an optional `title` field so the TUI sees the title on its first render.
+
 ## [0.1.12] - 2026-04-19
 
 ### Added

api/index.ts

@@ -117,6 +117,14 @@ export interface PhaseCtx {
   setTitle: (title: string) => void;
 }
 
+export interface PhaseOpts {
+  /**
+   * Display title known at phase-creation time. Rendered in the TUI instead
+   * of the stripped id. Runtime `setTitle(...)` from the body overrides this.
+   */
+  title?: string;
+}
+
 export interface RunCtx {
   /**
    * Wraps `engineStage()` around the provided async body. The body's return
@@ -125,6 +133,10 @@ export interface RunCtx {
    * use to call `setTitle(...)` after some setup work.
    */
   phase<T>(name: string, body: (ctx: PhaseCtx) => Promise<T>): Promise<T>;
+  /**
+   * Overload: static title passed at phase-creation time.
+   */
+  phase<T>(name: string, opts: PhaseOpts, body: (ctx: PhaseCtx) => Promise<T>): Promise<T>;
 
   /**
    * Invoke one agent session. Returns a promise that resolves to the LLM's
@@ -271,9 +283,15 @@ export function taskflow(name: string): TaskflowBuilder {
 
       return engineHarness(name, harnessOpts, async (h) => {
         const ctx: RunCtx = {
-          async phase<T>(phaseName: string, phaseBody: (ctx: PhaseCtx) => Promise<T>): Promise<T> {
+          async phase<T>(
+            phaseName: string,
+            optsOrBody: PhaseOpts | ((ctx: PhaseCtx) => Promise<T>),
+            maybeBody?: (ctx: PhaseCtx) => Promise<T>,
+          ): Promise<T> {
+            const phaseBody = typeof optsOrBody === 'function' ? optsOrBody : maybeBody!;
+            const opts: PhaseOpts = typeof optsOrBody === 'function' ? {} : optsOrBody;
             let result!: T;
-            await engineStage(h, phaseName, async (stageCtx) => {
+            await engineStage(h, phaseName, opts, async (stageCtx) => {
               result = await phaseBody({ setTitle: stageCtx.setTitle });
             });
             return result;

core/index.ts

@@ -227,7 +227,24 @@ export interface StageCtx {
   setTitle: (title: string) => void;
 }
 
-export async function stage(h: Ctx, id: string, body: (ctx: StageCtx) => Promise<void> | (() => Promise<void>)): Promise<void> {
+export interface StageOpts {
+  /**
+   * Display title for the TUI, known at phase-creation time. When provided,
+   * rendered in place of the stripped id. Runtime-set `setTitle(...)` calls
+   * from the body override this if both are used.
+   */
+  title?: string;
+}
+
+export async function stage(
+  h: Ctx,
+  id: string,
+  optsOrBody: StageOpts | ((ctx: StageCtx) => Promise<void>),
+  maybeBody?: (ctx: StageCtx) => Promise<void>,
+): Promise<void> {
+  const body = typeof optsOrBody === 'function' ? optsOrBody : maybeBody!;
+  const opts: StageOpts = typeof optsOrBody === 'function' ? {} : optsOrBody;
+
   const parentId = h.stageStack[h.stageStack.length - 1];
   h.stageStack.push(id);
   h._stageOrder.push(id);
@@ -239,7 +256,14 @@ export async function stage(h: Ctx, id: string, body: (ctx: StageCtx) => Promise
   if (fireBefore) {
     await hooks!.fire('beforePhase', buildHookCtx(h, { hookName: 'beforePhase', phaseScope: { id, stack: h.stageStack.slice() } }), { phaseId: id, parentId });
   }
-  h.bus.publish({ t: 'stage-enter', stageId: id, parentId, ts: Date.now() });
+  const enterEvent: { t: 'stage-enter'; stageId: string; parentId?: string; title?: string; ts: number } = {
+    t: 'stage-enter',
+    stageId: id,
+    parentId,
+    ts: Date.now(),
+  };
+  if (opts.title !== undefined) enterEvent.title = opts.title;
+  h.bus.publish(enterEvent);
 
   const stageCtx: StageCtx = {
     setTitle: (title: string) => {

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "taskflow-sdk",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "Multi-agent orchestration harness for AI coding agents (claude-code, codex, cursor, opencode, pi). Async-await TypeScript API; lifecycle hooks; auto-todos with verify-loop.",
   "keywords": [
     "ai",

package.json

@@ -108,6 +108,7 @@ export function createTuiStore(
             startedAt: ev.ts,
             children: [],
             leafEvents: [],
+            ...(ev.title !== undefined ? { title: ev.title } : {}),
           };
           nodes[ev.stageId] = node;
           if (parentId && nodes[parentId]) {