pi-taskflow 0.0.14 → 0.0.16

package/extensions/agents.ts

@@ -10,6 +10,59 @@ import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
 
 export type AgentScope = "user" | "project" | "both";
 
+export interface TaskflowSettings {
+	/** Whether taskflow's package-local built-in agents are available to flows. */
+	builtInAgents: boolean;
+	/** Whether package-local built-ins are copied into the current project's .pi/agents/. */
+	syncBuiltinAgentsToProject: boolean;
+	/** Maximum completed/failed runs to keep. 0 disables cleanup. */
+	maxKeptRuns: number;
+	/** Maximum age (days) for completed/failed runs. 0 disables age cleanup. */
+	maxRunAgeDays: number;
+}
+
+import { DEFAULT_KEPT_RUNS, DEFAULT_RUN_AGE_DAYS } from "./store.ts";
+
+export const DEFAULT_TASKFLOW_SETTINGS: TaskflowSettings = {
+	builtInAgents: true,
+	syncBuiltinAgentsToProject: false,
+	maxKeptRuns: DEFAULT_KEPT_RUNS,
+	maxRunAgeDays: DEFAULT_RUN_AGE_DAYS,
+};
+
+export function normalizeTaskflowSettings(raw: unknown): TaskflowSettings {
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+		return { ...DEFAULT_TASKFLOW_SETTINGS };
+	}
+	const rec = raw as Record<string, unknown>;
+	return {
+		builtInAgents:
+			typeof rec.builtInAgents === "boolean"
+				? rec.builtInAgents
+				: DEFAULT_TASKFLOW_SETTINGS.builtInAgents,
+		syncBuiltinAgentsToProject:
+			typeof rec.syncBuiltinAgentsToProject === "boolean"
+				? rec.syncBuiltinAgentsToProject
+				: DEFAULT_TASKFLOW_SETTINGS.syncBuiltinAgentsToProject,
+		maxKeptRuns:
+			typeof rec.maxKeptRuns === "number" && rec.maxKeptRuns >= 0 && Number.isInteger(rec.maxKeptRuns)
+				? rec.maxKeptRuns
+				: DEFAULT_TASKFLOW_SETTINGS.maxKeptRuns,
+		maxRunAgeDays:
+			typeof rec.maxRunAgeDays === "number" && rec.maxRunAgeDays >= 0 && Number.isInteger(rec.maxRunAgeDays)
+				? rec.maxRunAgeDays
+				: DEFAULT_TASKFLOW_SETTINGS.maxRunAgeDays,
+	};
+}
+
+export function shouldLoadBuiltinAgents(settings: TaskflowSettings = DEFAULT_TASKFLOW_SETTINGS): boolean {
+	return settings.builtInAgents;
+}
+
+export function shouldSyncBuiltinAgentsToProject(settings: TaskflowSettings = DEFAULT_TASKFLOW_SETTINGS): boolean {
+	return settings.builtInAgents && settings.syncBuiltinAgentsToProject;
+}
+
 export interface AgentOverride {
 	model?: string;
 	thinking?: string;
@@ -122,12 +175,14 @@ export function discoverAgents(
 	scope: AgentScope,
 	overrides?: Record<string, AgentOverride>,
 	modelRoles?: Record<string, string>,
+	taskflowSettings: TaskflowSettings = DEFAULT_TASKFLOW_SETTINGS,
 ): AgentDiscoveryResult {
-	// Built-in agents ship with the package (extensions/agents/*.md)
-	// PI_TASKFLOW_BUILTIN_AGENTS_DIR allows tests to override or disable (empty = skip)
+	// Built-in agents ship with the package (extensions/agents/*.md).
+	// PI_TASKFLOW_BUILTIN_AGENTS_DIR is kept as a test hook only; user-facing
+	// enable/disable lives in settings.json under `taskflow.builtInAgents`.
 	const builtInDirEnv = process.env.PI_TASKFLOW_BUILTIN_AGENTS_DIR;
 	const builtInDir = builtInDirEnv ? builtInDirEnv : builtInDirEnv === undefined ? path.resolve(import.meta.dirname, "agents") : "";
-	const builtInAgents = builtInDir ? loadAgentsFromDir(builtInDir, "built-in") : [];
+	const builtInAgents = shouldLoadBuiltinAgents(taskflowSettings) && builtInDir ? loadAgentsFromDir(builtInDir, "built-in") : [];
 
 	const userDir = path.join(getAgentDir(), "agents");
 	const projectAgentsDir = findNearestProjectAgentsDir(cwd);
@@ -165,10 +220,15 @@ export function discoverAgents(
 	}
 
 	// Resolve {{role}} model references (e.g. {{fast}} → openrouter/deepseek/v4-flash)
+	// Clone before mutating, consistent with the overrides block above.
 	if (modelRoles) {
-		for (const agent of agentMap.values()) {
+		for (const [name, agent] of agentMap.entries()) {
 			const resolved = resolveModelRole(agent.model, modelRoles);
-			if (resolved !== agent.model) agent.model = resolved;
+			if (resolved !== agent.model) {
+				const mutated: AgentConfig = { ...agent };
+				mutated.model = resolved;
+				agentMap.set(name, mutated);
+			}
 		}
 	}
 
@@ -179,6 +239,7 @@ export interface SubagentSettings {
 	agentOverrides?: Record<string, AgentOverride>;
 	globalThinking?: string;
 	modelRoles?: Record<string, string>;
+	taskflow: TaskflowSettings;
 }
 
 /**
@@ -197,14 +258,62 @@ export function resolveModelRole(model: string | undefined, roles?: Record<strin
 export function readSubagentSettings(): SubagentSettings {
 	try {
 		const settingsPath = path.join(getAgentDir(), "settings.json");
-		if (!fs.existsSync(settingsPath)) return {};
+		if (!fs.existsSync(settingsPath)) return { taskflow: { ...DEFAULT_TASKFLOW_SETTINGS } };
 		const raw = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
 		return {
 			agentOverrides: raw.subagents?.agentOverrides,
 			globalThinking: raw.subagents?.globalThinking ?? raw.defaultThinkingLevel,
 			modelRoles: raw.modelRoles,
+			taskflow: normalizeTaskflowSettings(raw.taskflow),
 		};
 	} catch {
-		return {};
+		return { taskflow: { ...DEFAULT_TASKFLOW_SETTINGS } };
+	}
+}
+
+/**
+ * Copy the 18 built-in agents from extensions/agents/*.md into the project's
+ * .pi/agents/ directory so Pi's native subagent tool (and any other extension)
+ * can discover them. taskflow's own discoverAgents() already reads from this
+ * directory with lower priority than built-in, so the copy is a no-op for
+ * taskflow phases — it only matters for Pi's native agent discovery.
+ *
+ * Idempotent: only copies agents whose built-in source is newer than the
+ * project copy (or that don't exist yet).
+ */
+export function syncBuiltinAgentsToProject(cwd: string): void {
+	const builtInDir = path.resolve(import.meta.dirname, "agents");
+	if (!fs.existsSync(builtInDir)) return;
+
+	const projectAgentsDir = path.join(cwd, ".pi", "agents");
+	fs.mkdirSync(projectAgentsDir, { recursive: true });
+
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(builtInDir, { withFileTypes: true });
+	} catch {
+		return;
+	}
+
+	for (const entry of entries) {
+		if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+		const src = path.join(builtInDir, entry.name);
+		const dst = path.join(projectAgentsDir, entry.name);
+
+		let srcMtime = 0;
+		try { srcMtime = fs.statSync(src).mtimeMs; } catch { continue; }
+
+		let dstMtime = 0;
+		try { dstMtime = fs.statSync(dst).mtimeMs; } catch { /* dst doesn't exist yet */ }
+
+		// Only copy when the source is newer (or the destination is missing).
+		if (srcMtime <= dstMtime) continue;
+
+		try {
+			const content = fs.readFileSync(src, "utf-8");
+			fs.writeFileSync(dst, content, "utf-8");
+		} catch {
+			// Best-effort: a locked file must not block the sync.
+		}
 	}
 }

package/extensions/index.ts

@@ -24,7 +24,7 @@ import {
 	runInteractiveInit,
 } from "./init.ts";
 import { Type } from "typebox";
-import { type AgentScope, discoverAgents, readSubagentSettings } from "./agents.ts";
+import { type AgentScope, discoverAgents, readSubagentSettings, shouldSyncBuiltinAgentsToProject, syncBuiltinAgentsToProject } from "./agents.ts";
 import { renderRunResult, summarizeRun } from "./render.ts";
 import { RunHistoryComponent, type RunHistoryResult } from "./runs-view.ts";
 import { executeTaskflow, type ApprovalDecision, type ApprovalRequest, type RuntimeResult } from "./runtime.ts";
@@ -38,6 +38,8 @@ import {
 	type RunState,
 	saveFlow,
 	saveRun,
+	DEFAULT_KEPT_RUNS,
+	DEFAULT_RUN_AGE_DAYS,
 } from "./store.ts";
 import { CacheStore } from "./cache.ts";
 
@@ -142,11 +144,12 @@ async function runFlow(
 
 	// Throttled persistence: avoid disk writes on every sub-item event.
 	let lastPersist = 0;
+	const cleanupConfig = { maxKeep: DEFAULT_KEPT_RUNS, maxAgeDays: DEFAULT_RUN_AGE_DAYS };
 	const persistThrottled = (s: RunState) => {
 		const now = Date.now();
 		if (now - lastPersist >= 1000) {
 			lastPersist = now;
-			saveRun(s);
+			saveRun(s, cleanupConfig);
 		}
 	};
 
@@ -189,8 +192,10 @@ async function runFlow(
 		// discoverAgents or readSubagentSettings (F-001) is caught and
 		// the heartbeat timer is cleared by the finally block below.
 		const settings = readSubagentSettings();
+		cleanupConfig.maxKeep = settings.taskflow.maxKeptRuns;
+		cleanupConfig.maxAgeDays = settings.taskflow.maxRunAgeDays;
 		const scope: AgentScope = def.agentScope ?? "user";
-		const { agents } = discoverAgents(ctx.cwd, scope, settings.agentOverrides, settings.modelRoles);
+		const { agents } = discoverAgents(ctx.cwd, scope, settings.agentOverrides, settings.modelRoles, settings.taskflow);
 
 		// Hint: if any agent still has unresolved {{role}} references, suggest configuring modelRoles
 		const unresolvedRoles = agents
@@ -225,7 +230,7 @@ async function runFlow(
 		return result;
 	} finally {
 		if (heartbeat) clearInterval(heartbeat);
-		saveRun(state); // force-persist terminal state
+		saveRun(state, cleanupConfig); // force-persist terminal state
 		emit(state); // final render reflecting terminal state
 	}
 }
@@ -255,6 +260,44 @@ export default function (pi: ExtensionAPI) {
 	pi.on("session_start", async (_e, ctx) => {
 		registerSavedFlowCommands(ctx);
 
+		// Optional: copy built-in agents into .pi/agents/ so Pi's native
+		// subagent tool (and other extensions) can discover them. This is
+		// disabled by default to avoid surprising project file creation.
+		try {
+			const settings = readSubagentSettings();
+			if (shouldSyncBuiltinAgentsToProject(settings.taskflow)) {
+				syncBuiltinAgentsToProject(ctx.cwd);
+			}
+		} catch {
+			// Best-effort: a locked or readonly .pi/ directory must not block
+			// session startup.
+		}
+
+		// Upgrade hint: if the project already has .pi/agents/ with agent
+		// files but no explicit taskflow settings, the user is upgrading
+		// from the old default (sync=true) and may be surprised that sync
+		// is now disabled by default.
+		try {
+			const raw = readSettings();
+			if (!("taskflow" in raw)) {
+				const fs = await import("node:fs");
+				const path = await import("node:path");
+				const projectAgentsDir = path.join(ctx.cwd, ".pi", "agents");
+				try {
+					const entries = fs.readdirSync(projectAgentsDir).filter((e: string) => e.endsWith(".md"));
+					if (entries.length > 0) {
+						console.warn(
+							`[taskflow] Note: built-in agents are no longer synced to .pi/agents/ by default. ` +
+							`If you rely on this, run /tf init → 'Configure taskflow preferences' to re-enable. ` +
+							`(This is a one-time upgrade hint.)`,
+						);
+					}
+				} catch { /* .pi/agents/ doesn't exist — no hint needed */ }
+			}
+		} catch {
+			// Best-effort: settings.json missing or unreadable is not an error.
+		}
+
 		// Hint: prompt to configure model roles if not set
 		try {
 			const settings = readSubagentSettings();
@@ -272,20 +315,19 @@ export default function (pi: ExtensionAPI) {
 		name: "taskflow",
 		label: "Taskflow",
 		description: [
-			"Orchestrate a multi-phase workflow of subagents from a declarative definition.",
-			"Phases (agent, parallel, map, gate, reduce, approval, flow) form a DAG; intermediate outputs stay out of your context — only the final phase output is returned.",
-			"Use action=run with an inline `define` (you write the DSL) or a saved `name`.",
-			"For simple non-DAG delegations (like the subagent tool) skip the DSL: pass `task` (+optional `agent`) for one task, `tasks:[{task,agent?}]` to run in parallel, or `chain:[{task,agent?}]` to run sequentially (reference the prior step with {previous.output}).",
-			"Use action=save to persist a definition as a reusable /tf:<name> command. action=resume continues a paused run. action=list shows saved flows. Use action=agents to list available agents — do NOT invent agent names; either use an agent from that list or omit the 'agent' field to auto-select the default agent.",
-			"DSL: {name, args?, concurrency?, budget?:{maxUSD,maxTokens}, phases:[{id, type, agent, task, dependsOn?, join?:'all'|'any', when?, retry?:{max,backoffMs,factor}, over?(map), as?(map), branches?(parallel), from?(reduce), use?(flow), with?(flow), output?:'json', final?}]}.",
-			"Phase types: agent (one subagent), parallel (static branches), map (dynamic fan-out over an array), gate (VERDICT: PASS/BLOCK quality gate), reduce (aggregate from N phases), approval (human-in-the-loop pause), flow (run a saved sub-flow), loop (re-run a task until 'until' is truthy / converged / maxIterations; body reads {loop.iteration} and {loop.lastOutput}), tournament (spawn N variants of 'task' — or distinct 'branches' — then a judge picks the best / aggregates; mode:'best'|'aggregate'). join:'any' is an OR-join; when is a conditional guard; retry adds backoff; budget caps run cost.",
+			"IMPORTANT: Before using this tool for the first time in a session, invoke skill_load('taskflow') to read the full documentation (DSL syntax, examples, best practices). This tool description is a reference, not a tutorial.",
+			"Shorthand (same API as subagent): pass `task` (+optional `agent`) for one task, `tasks:[{task,agent?}]` for parallel, or `chain:[{task,agent?}]` for sequential (use {previous.output}).",
+			"DSL: use action=run with an inline `define` (you write the DAG) or a saved `name`. Phases (agent, parallel, map, gate, reduce, approval, flow, loop, tournament) form a DAG; intermediate outputs stay out of your context — only the final phase output is returned.",
+			"Every delegation is tracked (runId), resumable across sessions, and saveable as /tf:<name> via action=save.",
+			"Use action=agents to list the 18 built-in agents (executor, scout, planner, analyst, critic, reviewer, risk-reviewer, security-reviewer, plan-arbiter, final-arbiter, test-engineer, doc-writer, executor-code, executor-fast, executor-ui, recover, verifier, visual-explorer). Do NOT invent agent names.",
+			"Phase types: agent, parallel (static branches), map (dynamic fan-out over array), gate (VERDICT: PASS/BLOCK), reduce (aggregate from N), approval (human-in-the-loop), flow (run saved sub-flow), loop (iterate until condition/convergence/cap), tournament (N variants, judge picks best/aggregate).",
 			"Interpolation: {args.X}, {steps.ID.output}, {steps.ID.json}, {item} (map), {previous.output}.",
 		].join(" "),
 		parameters: TaskflowParams,
-		promptSnippet: "Orchestrate many subagents over a whole codebase/many items (declarative DAG with map fan-out)",
+		promptSnippet: "Orchestrate subagents — single, parallel, chain, or DAG — with tracking, resume, and context isolation. Replaces the subagent tool.",
 		promptGuidelines: [
-			"Prefer taskflow whenever a request spans a whole project/codebase or many items — e.g. 'explore / 探索 / 审计 / analyze the project', auditing endpoints, reviewing or migrating many files/modules, or cross-checked research. It fans out to many subagents across phases and aggregates the result, keeping intermediate work out of your context.",
-			"Choose taskflow over ad-hoc parallel subagents when the work has multiple phases (discover → work → review → report), needs dynamic fan-out over a discovered list, or should be saved and rerun. For simple single/parallel/chain delegations use the shorthand `task`/`tasks`/`chain` (no DSL) when you want the run tracked, resumable, or saveable; otherwise the plain subagent tool is fine.",
+			"BEFORE FIRST USE: invoke skill_load('taskflow') to read the full skill documentation (DSL syntax, phase types, examples, best practices). This tool description is a condensed reference only — the skill is the authoritative guide.\n\nUse taskflow for ALL delegation — single tasks, parallel, chain, or full DAG orchestration. It fully replaces the subagent tool: every delegation is tracked with a runId, resumable across sessions, context-isolated (only final output returns), and saveable as /tf:<name>. Do NOT call the subagent tool directly; use taskflow shorthand (task/tasks/chain) for simple cases instead.",
+			"For complex multi-phase work (explore / 审计 / analyze the project, auditing endpoints, reviewing or migrating many files/modules, cross-checked research), use the full DSL with phases. For taskflow map phases, have the upstream phase emit a JSON array and set output:'json'.",
 			"For taskflow map phases, have the upstream phase emit a JSON array and set output:'json'.",
 		],
 
@@ -361,6 +403,7 @@ export default function (pi: ExtensionAPI) {
 						modelRegistry: ctx.modelRegistry,
 						modelList,
 						currentRoles: current,
+						currentTaskflowSettings: readSubagentSettings().taskflow,
 					});
 					const text = formatFlowResult(result);
 					return { content: [{ type: "text", text }], details: { action } satisfies TaskflowDetails };
@@ -373,7 +416,7 @@ export default function (pi: ExtensionAPI) {
 			if (action === "agents") {
 				const scope = params.scope ?? "both";
 				const settings2 = readSubagentSettings();
-				const { agents } = discoverAgents(ctx.cwd, scope as AgentScope, undefined, settings2.modelRoles);
+				const { agents } = discoverAgents(ctx.cwd, scope as AgentScope, undefined, settings2.modelRoles, settings2.taskflow);
 				const text = agents.length
 					? agents
 							.map(
@@ -704,17 +747,13 @@ export default function (pi: ExtensionAPI) {
 					modelRegistry: ctx.modelRegistry,
 					modelList,
 					currentRoles,
+					currentTaskflowSettings: readSubagentSettings().taskflow,
 				});
-				ctx.ui.notify(
-					result.kind === "saved"
-						? `Saved model roles to ${result.savedPath}:\n${Object.entries(result.chosen)
-								.map(([k, v]) => `  ${k.padEnd(10)} → ${v}`)
-								.join("\n")}`
-						: result.kind === "no-change"
-							? "No changes made."
-							: "Init cancelled.",
-					result.kind === "saved" ? "info" : "info",
-				);
+				if (result.kind === "cancelled") {
+					ctx.ui.notify("Init cancelled.", "info");
+				} else {
+					ctx.ui.notify(formatFlowResult(result), "info");
+				}
 				return;
 			}
 

package/extensions/init.ts

@@ -17,6 +17,7 @@ import * as path from "node:path";
 import type { Api, Model } from "@earendil-works/pi-ai";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import type { ExtensionContext, ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import { DEFAULT_TASKFLOW_SETTINGS, normalizeTaskflowSettings, type TaskflowSettings } from "./agents.ts";
 import { writeFileAtomic } from "./store.ts";
 
 // ---------------------------------------------------------------------------
@@ -330,8 +331,23 @@ export function formatDiffReport(
 	return lines.join("\n");
 }
 
+export function formatTaskflowSettingsReport(settings: TaskflowSettings): string {
+	return [
+		"Taskflow preferences:",
+		`  Built-in agents: ${settings.builtInAgents ? "enabled" : "disabled"}`,
+		`  Sync built-ins to project .pi/agents: ${settings.syncBuiltinAgentsToProject ? "enabled" : "disabled"}`,
+	].join("\n");
+}
+
 export function formatFlowResult(result: InitFlowResult): string {
 	if (result.kind === "cancelled") return "Init cancelled.";
+	if (result.kind === "preferences-no-change") {
+		return "No changes.\n" + formatTaskflowSettingsReport(result.settings);
+	}
+	if (result.kind === "preferences-saved") {
+		const savedPath = formatSettingsPath(result.savedPath);
+		return `Saved taskflow preferences to ${savedPath}:\n` + formatTaskflowSettingsReport(result.settings);
+	}
 	if (result.kind === "no-change") {
 		return (
 			"No changes.\n" +
@@ -357,6 +373,8 @@ export function formatFlowResult(result: InitFlowResult): string {
 export type InitFlowResult =
 	| { kind: "saved"; chosen: Record<string, string>; savedPath: string }
 	| { kind: "no-change"; chosen: Record<string, string> }
+	| { kind: "preferences-saved"; settings: TaskflowSettings; savedPath: string }
+	| { kind: "preferences-no-change"; settings: TaskflowSettings }
 	| { kind: "cancelled" };
 
 export async function runInteractiveInit(ctx: {
@@ -366,6 +384,7 @@ export async function runInteractiveInit(ctx: {
 	modelRegistry: ExtensionContext["modelRegistry"];
 	modelList: Model<Api>[];
 	currentRoles: Record<string, string>;
+	currentTaskflowSettings?: TaskflowSettings;
 }): Promise<InitFlowResult> {
 	if (!ctx.hasUI) {
 		throw new Error("runInteractiveInit requires an interactive session (hasUI=true).");
@@ -373,6 +392,7 @@ export async function runInteractiveInit(ctx: {
 
 	const recommended = RECOMMENDED_DEFAULTS;
 	const current = ctx.currentRoles;
+	const currentTaskflowSettings = ctx.currentTaskflowSettings ?? normalizeTaskflowSettings(readSettings().taskflow);
 	const hasCurrent = Object.keys(current).length > 0;
 
 	// ---- Action menu ----
@@ -381,10 +401,11 @@ export async function runInteractiveInit(ctx: {
 				"Use recommended defaults",
 				"Configure each role",
 				"Edit one role",
+				"Configure taskflow preferences",
 				"Show current roles",
 				"Cancel",
 			]
-		: ["Use recommended defaults", "Configure each role"];
+		: ["Use recommended defaults", "Configure each role", "Configure taskflow preferences"];
 
 	const action = await ctx.ui.select(
 		"What do you want to do with model roles?",
@@ -416,6 +437,11 @@ export async function runInteractiveInit(ctx: {
 	// ---- Cancel ----
 	if (action === "Cancel") return { kind: "cancelled" };
 
+	// ---- Configure taskflow preferences ----
+	if (action === "Configure taskflow preferences") {
+		return configureTaskflowPreferences(ctx, currentTaskflowSettings);
+	}
+
 	// ---- Configure each role ----
 	if (action === "Configure each role") {
 		const chosen = await collectRolePicks(ctx, current, recommended, undefined);
@@ -437,6 +463,59 @@ export async function runInteractiveInit(ctx: {
 // Internal helpers
 // ---------------------------------------------------------------------------
 
+function taskflowSettingsIdentical(a: TaskflowSettings, b: TaskflowSettings): boolean {
+	return a.builtInAgents === b.builtInAgents && a.syncBuiltinAgentsToProject === b.syncBuiltinAgentsToProject;
+}
+
+async function configureTaskflowPreferences(
+	ctx: { signal: AbortSignal; ui: ExtensionUIContext },
+	current: TaskflowSettings,
+): Promise<InitFlowResult> {
+	const builtInPick = await ctx.ui.select(
+		"Taskflow built-in agents",
+		[
+			`Enable built-in agents${current.builtInAgents ? " (current)" : ""}`,
+			`Disable built-in agents${!current.builtInAgents ? " (current)" : ""}`,
+			"Back to action menu",
+		],
+		{ signal: ctx.signal },
+	);
+	if (builtInPick === undefined || builtInPick === "Back to action menu") return { kind: "cancelled" };
+
+	const chosen: TaskflowSettings = {
+		...DEFAULT_TASKFLOW_SETTINGS,
+		builtInAgents: builtInPick.startsWith("Enable"),
+	};
+
+	if (chosen.builtInAgents) {
+		const syncPick = await ctx.ui.select(
+			"Expose built-in agents to native Pi/project discovery?",
+			[
+				`Do not copy to project .pi/agents${!current.syncBuiltinAgentsToProject ? " (current)" : ""}`,
+				`Copy to project .pi/agents on session start${current.syncBuiltinAgentsToProject ? " (current)" : ""}`,
+				"Back to action menu",
+			],
+			{ signal: ctx.signal },
+		);
+		if (syncPick === undefined || syncPick === "Back to action menu") return { kind: "cancelled" };
+		chosen.syncBuiltinAgentsToProject = syncPick.startsWith("Copy");
+	}
+
+	if (taskflowSettingsIdentical(current, chosen)) {
+		return { kind: "preferences-no-change", settings: chosen };
+	}
+
+	const preview = await ctx.ui.select(
+		`Review taskflow preferences:\n\n${formatTaskflowSettingsReport(chosen)}`,
+		["Save these preferences", "Cancel"],
+		{ signal: ctx.signal },
+	);
+	if (preview !== "Save these preferences") return { kind: "cancelled" };
+
+	const savedPath = writeSettings({ ...readSettings(), taskflow: chosen });
+	return { kind: "preferences-saved", settings: chosen, savedPath };
+}
+
 /** Collect picks for all roles. Returns undefined if user escapes to action menu. */
 async function collectRolePicks(
 	ctx: { signal: AbortSignal; ui: ExtensionUIContext; modelList: Model<Api>[] },

package/extensions/store.ts

@@ -121,6 +121,10 @@ const DEFAULT_MAX_KEPT_TERMINAL = 100;
 /** Remove terminal runs older than this (days). */
 const DEFAULT_MAX_AGE_DAYS = 30;
 
+// Re-exported for use in TaskflowSettings defaults (agents.ts).
+export const DEFAULT_KEPT_RUNS = DEFAULT_MAX_KEPT_TERMINAL;
+export const DEFAULT_RUN_AGE_DAYS = DEFAULT_MAX_AGE_DAYS;
+
 /** Last cleanup timestamp — module-level so it persists across calls. */
 let lastCleanupAt = 0;
 
@@ -460,6 +464,12 @@ function cleanupTerminalRuns(
 
 	if (toRemove.length === 0) return;
 
+	console.warn(
+		`[taskflow] Cleaning up ${toRemove.length} old run(s) ` +
+		`(max ${maxKeep} runs, ${maxAgeDays} day age limit). ` +
+		`Configure 'taskflow.maxKeptRuns' / 'taskflow.maxRunAgeDays' in settings.json (0 = keep all).`,
+	);
+
 	// Delete run files + lock files (outside the index lock).
 	for (const e of toRemove) {
 		const filePath = path.join(runsRoot, e.relPath);
@@ -548,6 +558,8 @@ export function getFlow(cwd: string, name: string): SavedFlow | null {
 	return listFlows(cwd).find((f) => f.name === name) ?? null;
 }
 
+let _piCreationHinted = false;
+
 export function saveFlow(
 	cwd: string,
 	def: Taskflow,
@@ -558,9 +570,20 @@ export function saveFlow(
 	const safe = def.name.replace(/[^\w.-]+/g, "_");
 	const filePath = path.join(dir, `${safe}.json`);
 	writeFileAtomic(filePath, `${JSON.stringify(def, null, 2)}\n`);
+
+	// One-shot: let the user know we're creating a .pi/ directory on first save.
+	if (!_piCreationHinted) {
+		_piCreationHinted = true;
+		console.warn(
+			`[taskflow] Created .pi/taskflows/ for project-scoped flow storage. ` +
+			`Add .pi/ to .gitignore if desired.`,
+		);
+	}
+
 	return { filePath };
 }
 
+
 // --- Run state ---
 
 function runsDir(cwd: string): string {
@@ -590,7 +613,7 @@ export function newRunId(flowName: string): string {
  * F-009: shallow-clones state before stamping updatedAt to avoid mutating the
  * caller's reference.
  */
-export function saveRun(state: RunState): void {
+export function saveRun(state: RunState, cleanup?: { maxKeep?: number; maxAgeDays?: number }): void {
 	const root = runsDir(state.cwd);
 	const flowDir = flowRunDir(root, state.flowName);
 	fs.mkdirSync(flowDir, { recursive: true });
@@ -608,7 +631,11 @@ export function saveRun(state: RunState): void {
 	});
 
 	// Opportunistic cleanup — throttled to once per CLEANUP_INTERVAL_MS.
-	cleanupTerminalRuns(root);
+	const maxKeep = cleanup?.maxKeep ?? DEFAULT_MAX_KEPT_TERMINAL;
+	const maxAgeDays = cleanup?.maxAgeDays ?? DEFAULT_MAX_AGE_DAYS;
+	if (maxKeep > 0 || maxAgeDays > 0) {
+		cleanupTerminalRuns(root, maxKeep, maxAgeDays);
+	}
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-taskflow",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "description": "Lightweight workflow orchestration for the Pi coding agent — declarative multi-phase taskflows with dynamic fan-out, isolated subagent context, resumable runs, and saveable commands.",
   "keywords": [
     "pi-package",
@@ -31,12 +31,14 @@
     "skills",
     "examples",
     "README.md",
+    "README.zh-CN.md",
+    "CHANGELOG.md",
     "DESIGN.md",
     "LICENSE"
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "PI_TASKFLOW_BUILTIN_AGENTS_DIR= node --experimental-strip-types --test test/interpolate.test.ts test/condition.test.ts test/schema.test.ts test/usage.test.ts test/runtime.test.ts test/features.test.ts test/runner.test.ts test/store.test.ts test/agents.test.ts test/init.test.ts test/render.test.ts test/desugar.test.ts test/cache.test.ts test/loop.test.ts test/tournament.test.ts test/verify.test.ts test/gate-eval.test.ts",
+    "test": "PI_TASKFLOW_BUILTIN_AGENTS_DIR= node --experimental-strip-types --test test/interpolate.test.ts test/condition.test.ts test/schema.test.ts test/usage.test.ts test/runtime.test.ts test/features.test.ts test/runner.test.ts test/store.test.ts test/agents.test.ts test/init.test.ts test/render.test.ts test/desugar.test.ts test/cache.test.ts test/loop.test.ts test/tournament.test.ts test/verify.test.ts test/gate-eval.test.ts test/transient-error.test.ts test/runtime-branches.test.ts test/interpolate-extended.test.ts test/store-extended.test.ts",
     "test:e2e": "PI_TASKFLOW_PI_BIN=pi node --experimental-strip-types test/e2e.mts",
     "test:dogfood-cache": "node --experimental-strip-types test/dogfood-cache.mts"
   },
@@ -46,7 +48,8 @@
     ],
     "skills": [
       "./skills"
-    ]
+    ],
+    "image": "https://raw.githubusercontent.com/heggria/pi-taskflow/main/assets/social-preview.png"
   },
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "*",