pi-agent-flow 1.4.3 → 1.4.4

package/README.md

@@ -47,6 +47,7 @@ pi install .
 - **Parallel execution** — batch independent flows into one call with bounded concurrency
 - **Structured reports** — every flow returns `[Summary]`, `[Done]`, `[Not Done]`, `[Next Steps]`
 - **Depth guards** — configurable max delegation depth (default: `3`)
+- **Session timeout modes** — child flows use controlled budgets: `fast` (300s), `default` (600s), or `long` (900s)
 - **Cycle prevention** — blocks re-entering flows already in the ancestor stack
 - **Model tiering & failover** — flows map to `lite` / `flash` / `full` tiers with primary + failover model chains
 - **Unified batch tools** — `batch` (read/write/edit/delete) and `batch_read` replace separate file tools for cross-cutting work
@@ -90,6 +91,33 @@ The result is faster, cheaper, and cleaner delegation: the main agent remains un
 
 > **Clean slate:** Set `inheritContext: false` in a custom flow's front-matter so it receives only the intent, ideal for unbiased creative work.
 
+### Session modes
+
+Each flow call may set `sessionMode` to choose the child-agent time budget:
+
+| Mode | Budget | Recommended use |
+|------|-------:|-----------------|
+| `fast` | 300s | quick scouting, narrow checks, small design passes |
+| `default` | 600s | normal flow work; this is the default |
+| `long` | 900s | large builds, full test runs, broad refactors, complex debugging |
+
+Example:
+
+```json
+{
+  "flow": [
+    {
+      "type": "build",
+      "intent": "Run the full test suite and fix failures",
+      "aim": "Fix failing tests",
+      "sessionMode": "long"
+    }
+  ]
+}
+```
+
+The public interface is mode-based; arbitrary per-flow numeric timeouts are not exposed.
+
 ---
 
 ## Flow Definitions
@@ -259,6 +287,36 @@ Use `flowModelConfigs` in your Pi settings to define tiered model strategies. Ea
 
 Settings are merged: project `.pi/settings.json` overrides global `~/.pi/agent/settings.json`.
 
+Switch the global active strategy quickly with `--flow-mode`:
+
+```bash
+pi --flow-mode balance
+pi --flow-mode quality
+pi --flow-mode mimo
+```
+
+`--flow-mode` updates `flowModelConfig` in global `~/.pi/agent/settings.json` (or `$PI_CODING_AGENT_DIR/settings.json`) and applies the mode immediately for the current invocation. The mode must already exist in the merged `flowModelConfigs`; project `.pi/settings.json` can still override global settings on later no-flag runs.
+
+You can also set flow runtime defaults under `flowSettings`:
+
+```json
+{
+  "flowSettings": {
+    "sessionMode": "default",
+    "maxConcurrency": 4,
+    "toolOptimize": true,
+    "structuredOutput": true,
+    "autoTransition": false
+  }
+}
+```
+
+`flowSettings.sessionMode` accepts `fast`, `default`, or `long`. Session mode precedence is:
+
+```txt
+per-flow sessionMode > --flow-session-mode > PI_FLOW_SESSION_MODE > flowSettings.sessionMode > default
+```
+
 ### Flags
 
 | Flag | Description | Default |
@@ -266,10 +324,12 @@ Settings are merged: project `.pi/settings.json` overrides global `~/.pi/agent/s
 | `--flow-max-depth [n]` | Maximum delegation depth | `3` |
 | `--flow-prevent-cycles` | Block cyclic delegation | `true` |
 | `--no-flow-prevent-cycles` | Disable cycle prevention | — |
-| `--flow-model-config [name]` | Select a named model strategy | `balance` |
+| `--flow-model-config [name]` | Select a named model strategy for this invocation | `balance` |
+| `--flow-mode [name]` | Persistently switch the global model strategy and apply it immediately | — |
 | `--flow-lite-model [model]` | Override the lite-tier model | — |
 | `--flow-flash-model [model]` | Override the flash-tier model | — |
 | `--flow-full-model [model]` | Override the full-tier model | — |
+| `--flow-session-mode [mode]` | Default child-flow session mode: `fast`, `default`, or `long` | `default` |
 | `--tool-optimize` | Use unified `batch`/`batch_read` instead of separate read/write/edit | `true` |
 | `--no-tool-optimize` | Disable tool optimization; use legacy read/write/edit tools | — |
 
@@ -282,7 +342,7 @@ Settings are merged: project `.pi/settings.json` overrides global `~/.pi/agent/s
 | `PI_FLOW_STACK` | JSON array of ancestor flow names |
 | `PI_FLOW_PREVENT_CYCLES` | `"1"` or `"0"` |
 | `PI_FLOW_TOOL_OPTIMIZE` | `"1"` or `"0"` (overrides default tool optimization) |
-| `PI_FLOW_TIMEOUT_MS` | Per-flow timeout in milliseconds (default: 10 minutes) |
+| `PI_FLOW_SESSION_MODE` | Default child-flow session mode: `fast`, `default`, or `long` |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-agent-flow",
-  "version": "1.4.3",
+  "version": "1.4.4",
   "description": "Flow-state delegation extension for Pi coding agent.",
   "type": "module",
   "main": "src/index.ts",

package/src/cli-args.ts

@@ -5,6 +5,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { parseAgentSessionMode, type AgentSessionMode } from "./session-mode.js";
 
 function looksLikeExplicitRelativePath(value: string): boolean {
 	return (
@@ -47,6 +48,8 @@ export interface ParsedFlowCliArgs {
 	fallbackTools?: string;
 	fallbackNoTools: boolean;
 	flowModelConfig?: string;
+	flowMode?: string;
+	flowSessionMode?: AgentSessionMode;
 	tieredModels: {
 		lite?: string;
 		flash?: string;
@@ -80,6 +83,8 @@ export function parseFlowCliArgs(argv: string[]): ParsedFlowCliArgs {
 	let fallbackTools: string | undefined;
 	let fallbackNoTools = false;
 	let flowModelConfig: string | undefined;
+	let flowMode: string | undefined;
+	let flowSessionMode: AgentSessionMode | undefined;
 	let tieredLiteModel: string | undefined;
 	let tieredFlashModel: string | undefined;
 	let tieredFullModel: string | undefined;
@@ -112,6 +117,20 @@ export function parseFlowCliArgs(argv: string[]): ParsedFlowCliArgs {
 			continue;
 		}
 
+		if (flagName === "--flow-mode") {
+			const [value, skip] = getValue();
+			if (value !== undefined) flowMode = value;
+			i += skip;
+			continue;
+		}
+
+		if (flagName === "--flow-session-mode") {
+			const [value, skip] = getValue();
+			flowSessionMode = parseAgentSessionMode(value);
+			i += skip;
+			continue;
+		}
+
 		if (
 			[
 				"--mode",
@@ -285,6 +304,8 @@ export function parseFlowCliArgs(argv: string[]): ParsedFlowCliArgs {
 		fallbackTools,
 		fallbackNoTools,
 		flowModelConfig,
+		flowMode,
+		flowSessionMode,
 		tieredModels: {
 			lite: tieredLiteModel,
 			flash: tieredFlashModel,

package/src/config.ts

@@ -8,6 +8,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { parseAgentSessionMode, type AgentSessionMode } from "./session-mode.js";
 
 export type FlowTier = "lite" | "flash" | "full";
 
@@ -33,6 +34,8 @@ export interface FlowSettings {
 	maxConcurrency?: number;
 	/** Whether to automatically queue follow-up flows based on hook transitions. Default: false. */
 	autoTransition?: boolean;
+	/** Default child-flow session mode. Default: "default" (600s). */
+	sessionMode?: AgentSessionMode;
 }
 
 const BUILTIN_FLOW_MODEL_CONFIGS: FlowModelConfigs = {
@@ -54,7 +57,7 @@ function readSettingsJson(filePath: string): Record<string, unknown> | null {
 	}
 }
 
-function getGlobalSettingsPath(): string {
+export function getGlobalSettingsPath(): string {
 	const agentDir = process.env["PI_CODING_AGENT_DIR"]?.trim() || path.join(os.homedir(), ".pi", "agent");
 	return path.join(agentDir, "settings.json");
 }
@@ -63,12 +66,56 @@ function getProjectSettingsPath(cwd: string): string {
 	return path.join(cwd, ".pi", "settings.json");
 }
 
+export function normalizeFlowModeName(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const normalized = value.trim();
+	return normalized.length > 0 ? normalized : undefined;
+}
+
 function extractSelectedFlowModelConfigName(settings: Record<string, unknown> | null): string | undefined {
 	if (!isPlainObject(settings)) return undefined;
-	const raw = settings.flowModelConfig;
-	if (typeof raw !== "string") return undefined;
-	const normalized = raw.trim();
-	return normalized.length > 0 ? normalized : undefined;
+	return normalizeFlowModeName(settings.flowModelConfig);
+}
+
+export function loadProjectFlowModelConfigName(cwd: string): string | undefined {
+	return extractSelectedFlowModelConfigName(readSettingsJson(getProjectSettingsPath(cwd)));
+}
+
+export function writeGlobalFlowMode(mode: string): { path: string; previous?: string } {
+	const normalized = normalizeFlowModeName(mode);
+	if (!normalized) {
+		throw new Error("Cannot update flow mode. Expected a non-empty mode name.");
+	}
+
+	const filePath = getGlobalSettingsPath();
+	let settings: Record<string, unknown> = {};
+
+	if (fs.existsSync(filePath)) {
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+		} catch (error) {
+			throw new Error(`Cannot update flow mode because ${filePath} contains invalid JSON.`);
+		}
+		if (!isPlainObject(parsed)) {
+			throw new Error(`Cannot update flow mode because ${filePath} must contain a JSON object.`);
+		}
+		settings = { ...parsed };
+	}
+
+	const previous = extractSelectedFlowModelConfigName(settings);
+	settings.flowModelConfig = normalized;
+
+	const dir = path.dirname(filePath);
+	fs.mkdirSync(dir, { recursive: true });
+	const tmpPath = path.join(dir, `.settings.json.${process.pid}.${Date.now()}.tmp`);
+	fs.writeFileSync(tmpPath, `${JSON.stringify(settings, null, 2)}\n`, "utf-8");
+	fs.renameSync(tmpPath, filePath);
+
+	return {
+		path: filePath,
+		...(previous !== undefined ? { previous } : {}),
+	};
 }
 
 function normalizeFailoverList(
@@ -186,6 +233,10 @@ function extractFlowSettings(settings: Record<string, unknown> | null): FlowSett
 	if (typeof obj.autoTransition === "boolean") {
 		result.autoTransition = obj.autoTransition;
 	}
+	const sessionMode = parseAgentSessionMode(obj.sessionMode);
+	if (sessionMode !== undefined) {
+		result.sessionMode = sessionMode;
+	}
 	return result;
 }
 
@@ -245,7 +296,7 @@ export function selectFlowModelStrategy(
 	configs: FlowModelConfigs,
 	requestedName?: string,
 ): LoadedFlowModelConfigs {
-	const normalizedRequested = requestedName?.trim() || "default";
+	const normalizedRequested = normalizeFlowModeName(requestedName) ?? "default";
 	const strategy = configs[normalizedRequested];
 	if (strategy) {
 		return { selectedName: normalizedRequested, configs, strategy };

package/src/executor.ts

@@ -18,7 +18,8 @@ import { extractStructuredOutput } from "./structured-output.js";
 import { runHooksDetailed, type RunHooksResult } from "./hooks.js";
 import { mapFlowConcurrent, runFlow } from "./flow.js";
 import { getFlowSummaryText } from "./runner-events.js";
-import { resolveFlowModelCandidates, selectFlowModelStrategy, type LoadedFlowModelConfigs, type FlowModelStrategy } from "./config.js";
+import { normalizeFlowModeName, resolveFlowModelCandidates, selectFlowModelStrategy, type LoadedFlowModelConfigs, type FlowModelStrategy } from "./config.js";
+import { getAgentSessionTimeoutMs, resolveAgentSessionMode, type AgentSessionMode } from "./session-mode.js";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -47,6 +48,8 @@ export interface FlowExecutorDeps {
 	maxConcurrency: number;
 	/** Whether auto-transition is enabled. */
 	autoTransition: boolean;
+	/** Default child-flow session mode. */
+	defaultSessionMode: AgentSessionMode;
 	/** Abort signal. */
 	signal?: AbortSignal;
 	/** Streaming update callback. */
@@ -82,6 +85,7 @@ export interface ExecuteFlowParams {
 	intent: string;
 	aim: string;
 	cwd?: string;
+	sessionMode?: AgentSessionMode;
 }
 
 export interface ExecuteFlowResult {
@@ -184,7 +188,7 @@ export async function executeFlows(
 	const {
 		flows, currentDepth, maxDepth, ancestorFlowStack, preventCycles,
 		toolOptimize, structuredOutput, cwd, loadedFlowModelConfigs,
-		maxConcurrency, autoTransition, signal, onUpdate, makeDetails,
+		maxConcurrency, autoTransition, defaultSessionMode, signal, onUpdate, makeDetails,
 		getFlag, tierOverrideResolver, fallbackModel, forkSessionSnapshotJsonl,
 		flowResultCache, projectFlowsDir, hasUI, uiConfirm, onFlowMetrics,
 		confirmProjectFlows,
@@ -222,13 +226,16 @@ export async function executeFlows(
 	}
 
 	// Resolve model strategy
-	const cliFlowModelConfig =
-		typeof getFlag("flow-model-config") === "string"
-			? (getFlag("flow-model-config") as string)
-			: undefined;
+	const cliFlowMode = normalizeFlowModeName(getFlag("flow-mode"));
+	const cliFlowModelConfig = normalizeFlowModeName(getFlag("flow-model-config"));
+	if (cliFlowMode !== undefined && cliFlowModelConfig !== undefined && cliFlowMode !== cliFlowModelConfig) {
+		console.warn(
+			`[pi-agent-flow] Both --flow-mode "${cliFlowMode}" and --flow-model-config "${cliFlowModelConfig}" were provided. Using --flow-mode.`,
+		);
+	}
 	const selectedFlowModelConfig = selectFlowModelStrategy(
 		loadedFlowModelConfigs.configs,
-		cliFlowModelConfig ?? loadedFlowModelConfigs.selectedName,
+		cliFlowMode ?? cliFlowModelConfig ?? loadedFlowModelConfigs.selectedName,
 	);
 
 	// Pre-allocate results array
@@ -257,10 +264,12 @@ export async function executeFlows(
 			text +
 			"|" +
 			allResults
-				.map(
-					(r) =>
-						`${r.messages.length}:${r.usage.toolCalls}:${r.usage.input}:${r.usage.output}:${r.usage.contextTokens}:${r.usage.smoothedTps ?? 0}:${r.errorMessage ?? ""}`,
-				)
+				.map((r) => {
+					const remainingSeconds = r.exitCode === -1 && typeof r.deadlineAtMs === "number"
+						? Math.max(0, Math.ceil((r.deadlineAtMs - Date.now()) / 1000))
+						: "";
+					return `${r.messages.length}:${r.usage.toolCalls}:${r.usage.input}:${r.usage.output}:${r.usage.contextTokens}:${r.usage.smoothedTps ?? 0}:${r.startedAtMs ?? ""}:${r.deadlineAtMs ?? ""}:${remainingSeconds}:${r.errorMessage ?? ""}`;
+				})
 				.join(";");
 		if (signature === lastEmittedSignature) return;
 		lastEmittedSignature = signature;
@@ -276,6 +285,7 @@ export async function executeFlows(
 	const executionStart = Date.now();
 	const results = await mapFlowConcurrent(params, maxConcurrency, async (item, index) => {
 		const normalizedType = item.type.toLowerCase();
+		const sessionMode = resolveAgentSessionMode(item.sessionMode, defaultSessionMode);
 		const targetFlow = flows.find((f) => f.name === normalizedType);
 		const effectiveMaxDepth =
 			targetFlow?.maxDepth !== undefined ? targetFlow.maxDepth : maxDepth;
@@ -297,6 +307,22 @@ export async function executeFlows(
 		for (let attempt = 0; attempt < attemptModels.length; attempt++) {
 			const candidateModel = attemptModels[attempt];
 			if (candidateModel) attemptedModels.push(candidateModel);
+			const attemptStartMs = Date.now();
+			const attemptTimeoutMs = getAgentSessionTimeoutMs(sessionMode);
+			allResults[index] = {
+				type: normalizedType,
+				agentSource: targetFlow?.source ?? "unknown",
+				intent: item.intent,
+				aim: item.aim,
+				exitCode: -1,
+				messages: [],
+				stderr: "",
+				usage: emptyFlowUsage(),
+				model: candidateModel,
+				startedAtMs: attemptStartMs,
+				deadlineAtMs: attemptStartMs + attemptTimeoutMs,
+			};
+			emitProgress();
 			result = await runFlow({
 				cwd,
 				flows,
@@ -311,6 +337,7 @@ export async function executeFlows(
 				preventCycles,
 				toolOptimize,
 				structuredOutput,
+				sessionMode,
 				model: candidateModel,
 				signal,
 				onUpdate: (partial) => {

package/src/flow.ts

@@ -21,11 +21,11 @@ import {
 	normalizeFlowResult,
 } from "./types.js";
 import { extractStructuredOutput, enrichStructuredOutputCommands } from "./structured-output.js";
+import { DEFAULT_AGENT_SESSION_MODE, getAgentSessionTimeoutMs, type AgentSessionMode } from "./session-mode.js";
 
 const isWindows = process.platform === "win32";
 const SIGKILL_TIMEOUT_MS = 5000;
 const AGENT_END_GRACE_MS = 2000;
-const DEFAULT_FLOW_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes
 const FLOW_TIME_BUDGET_WARNING_MS = 2 * 60 * 1000; // warn 2 min before kill
 const FLOW_FINAL_URGE_MS = 30 * 1000; // final urge 30 s before kill
 const REPORTING_GRACE_MS = 10_000; // grace period after timeout for agent to report findings
@@ -34,7 +34,6 @@ const FLOW_DEPTH_ENV = "PI_FLOW_DEPTH";
 const FLOW_MAX_DEPTH_ENV = "PI_FLOW_MAX_DEPTH";
 const FLOW_STACK_ENV = "PI_FLOW_STACK";
 const FLOW_PREVENT_CYCLES_ENV = "PI_FLOW_PREVENT_CYCLES";
-const FLOW_TIMEOUT_ENV = "PI_FLOW_TIMEOUT_MS";
 const FLOW_DEADLINE_ENV = "PI_FLOW_DEADLINE_MS";
 const FLOW_TOOL_SUMMARY_GRACE_ENV = "PI_FLOW_TOOL_SUMMARY_GRACE_MS";
 export const FLOW_TOOL_OPTIMIZE_ENV = "PI_FLOW_TOOL_OPTIMIZE";
@@ -146,7 +145,8 @@ function buildFlowArgs(
 	maxDepth: number = 0,
 	toolOptimize: boolean = false,
 	structuredOutput: boolean = true,
-	timeoutMs?: number,
+	sessionMode: AgentSessionMode = DEFAULT_AGENT_SESSION_MODE,
+	sessionTimeoutMs: number = getAgentSessionTimeoutMs(sessionMode),
 ): string[] {
 	const args: string[] = [
 		"--mode",
@@ -163,6 +163,9 @@ function buildFlowArgs(
 	if (inheritedCliArgs.flowModelConfig) {
 		args.push("--flow-model-config", inheritedCliArgs.flowModelConfig);
 	}
+	if (inheritedCliArgs.flowSessionMode) {
+		args.push("--flow-session-mode", inheritedCliArgs.flowSessionMode);
+	}
 	if (inheritedCliArgs.tieredModels?.lite) {
 		args.push("--flow-lite-model", inheritedCliArgs.tieredModels.lite);
 	}
@@ -218,8 +221,8 @@ function buildFlowArgs(
 		: `You may NOT delegate to sub-flows (depth limit reached).`;
 
 	const timeBudgetHint =
-		timeoutMs && timeoutMs > 0
-			? `Time budget: ${Math.round(timeoutMs / 1000)}s total. Long-running tools may be interrupted near the deadline to preserve final-summary time; if a tool reports [Flow timeout], stop tool use and output structured findings immediately.\n`
+		sessionTimeoutMs > 0
+			? `Session mode: ${sessionMode}. Time budget: ${Math.round(sessionTimeoutMs / 1000)}s total. Long-running tools may be interrupted near the deadline to preserve final-summary time; if a tool reports [Flow timeout], stop tool use and output structured findings immediately.\n`
 			: "";
 
 	const activation =
@@ -324,8 +327,8 @@ export interface RunFlowOptions {
 	onUpdate?: FlowUpdateCallback;
 	/** Factory to wrap results into FlowDetails. */
 	makeDetails: (results: SingleResult[]) => FlowDetails;
-	/** Max execution time in ms before child is terminated. Default: 10 minutes. */
-	timeoutMs?: number;
+	/** Child-flow session mode. Default: "default" (600s). */
+	sessionMode?: AgentSessionMode;
 }
 
 /**
@@ -370,6 +373,10 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 		};
 	}
 
+	const effectiveSessionMode = opts.sessionMode ?? DEFAULT_AGENT_SESSION_MODE;
+	const effectiveTimeout = getAgentSessionTimeoutMs(effectiveSessionMode);
+	const startedAtMs = Date.now();
+	const deadlineAtMs = effectiveTimeout > 0 ? startedAtMs + effectiveTimeout : undefined;
 	const resolvedModel = model ?? flow.model ?? inheritedCliArgs.fallbackModel;
 	const result: SingleResult = {
 		type: normalizedFlowName,
@@ -381,6 +388,8 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 		stderr: "",
 		usage: emptyFlowUsage(),
 		model: resolvedModel,
+		startedAtMs,
+		...(deadlineAtMs !== undefined ? { deadlineAtMs } : {}),
 	};
 
 	let liveStreamingText = "";
@@ -419,14 +428,6 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 		forkSessionTmpPath = forkTmp.filePath;
 	}
 
-	// Resolve timeout: explicit option > env var > default (10 min)
-	const envTimeoutRaw = process.env[FLOW_TIMEOUT_ENV];
-	const envTimeout = envTimeoutRaw !== undefined ? (() => {
-		const n = Number(envTimeoutRaw);
-		return Number.isSafeInteger(n) && n >= 0 ? n : null;
-	})() : null;
-	const effectiveTimeout = opts.timeoutMs ?? envTimeout ?? DEFAULT_FLOW_TIMEOUT_MS;
-
 	try {
 		const piArgs = buildFlowArgs(
 			flow,
@@ -437,6 +438,7 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 			maxDepth,
 			toolOptimize,
 			structuredOutput,
+			effectiveSessionMode,
 			effectiveTimeout,
 		);
 		let wasAborted = false;
@@ -468,7 +470,7 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 					[FLOW_TOOL_OPTIMIZE_ENV]: toolOptimize ? "1" : "0",
 					[PI_OFFLINE_ENV]: "1",
 					...(effectiveTimeout > 0 ? {
-						[FLOW_DEADLINE_ENV]: String(Date.now() + effectiveTimeout),
+						[FLOW_DEADLINE_ENV]: String(deadlineAtMs),
 						[FLOW_TOOL_SUMMARY_GRACE_ENV]: String(toolSummaryGraceMs),
 					} : {
 						[FLOW_DEADLINE_ENV]: "",
@@ -494,6 +496,7 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 			let settled = false;
 			let timeoutFired = false;
 			let semanticCompletionTimer: NodeJS.Timeout | undefined;
+			let countdownTimer: NodeJS.Timeout | undefined;
 
 			const clearSemanticCompletionTimer = () => {
 				if (semanticCompletionTimer) {
@@ -502,6 +505,13 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 				}
 			};
 
+			const clearCountdownTimer = () => {
+				if (countdownTimer) {
+					clearInterval(countdownTimer);
+					countdownTimer = undefined;
+				}
+			};
+
 			const terminateChild = () => {
 				endStdin();
 				if (isWindows) {
@@ -529,6 +539,7 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 				settled = true;
 				endStdin();
 				clearSemanticCompletionTimer();
+				clearCountdownTimer();
 				if (signal && abortHandler) {
 					signal.removeEventListener("abort", abortHandler);
 				}
@@ -575,6 +586,14 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 			proc.stdout.on("data", onStdoutData);
 			proc.stderr.on("data", onStderrData);
 
+			if (onUpdate && effectiveTimeout > 0) {
+				countdownTimer = setInterval(() => {
+					if (didClose || settled) return;
+					emitUpdate();
+				}, 1000);
+				countdownTimer.unref();
+			}
+
 			proc.on("close", (code) => {
 				didClose = true;
 				if (buffer.trim()) flushBufferedLines(buffer);

package/src/index.ts

@@ -12,8 +12,11 @@ import { type FlowConfig, discoverFlows, getFlowTier } from "./agents.js";
 import {
 	loadFlowModelConfigs,
 	loadFlowSettings,
+	loadProjectFlowModelConfigName,
+	normalizeFlowModeName,
 	resolveFlowModelCandidates,
 	selectFlowModelStrategy,
+	writeGlobalFlowMode,
 	type LoadedFlowModelConfigs,
 } from "./config.js";
 import { getInheritedCliArgs } from "./cli-args.js";
@@ -55,6 +58,12 @@ import {
 } from "./sliding-prompt.js";
 import { DEFAULT_TRANSITIONS, buildTransitionHooks } from "./transitions.js";
 import { createTimedBashToolDefinition } from "./timed-bash.js";
+import {
+	DEFAULT_AGENT_SESSION_MODE,
+	PI_FLOW_SESSION_MODE_ENV,
+	parseAgentSessionMode,
+	type AgentSessionMode,
+} from "./session-mode.js";
 
 // ---------------------------------------------------------------------------
 // Limits
@@ -85,13 +94,23 @@ const FlowItem = Type.Object({
 	cwd: Type.Optional(
 		Type.String({ description: "Working directory override for this flow." }),
 	),
+	sessionMode: Type.Optional(
+		Type.Union([
+			Type.Literal("fast"),
+			Type.Literal("default"),
+			Type.Literal("long"),
+		], {
+			description: "Agent session budget for this flow: fast=300s, default=600s, long=900s. Use long only for large builds, broad refactors, full test runs, or complex debugging.",
+		}),
+	),
 });
 
 const FlowParams = Type.Object({
 	flow: Type.Array(FlowItem, {
 		description:
 			"Array of flow tasks to execute. Each runs in its own forked process. " +
-			'Example: { flow: [{ type: "scout", "intent": "Find all authentication-related code and trace JWT validation", "aim": "Find auth code and trace JWT" }, { type: "build", "intent": "Fix the bug in user registration", "aim": "Fix registration bug" }] }',
+			"Optional sessionMode selects the child-agent budget: fast=300s, default=600s, long=900s. " +
+			'Example: { flow: [{ type: "scout", "intent": "Find all authentication-related code and trace JWT validation", "aim": "Find auth code and trace JWT", "sessionMode": "fast" }, { type: "build", "intent": "Fix the bug in user registration", "aim": "Fix registration bug", "sessionMode": "long" }] }',
 		minItems: 1,
 	}),
 	confirmProjectFlows: Type.Optional(
@@ -634,6 +653,10 @@ export default function (pi: ExtensionAPI) {
 		description: "Named flow model strategy from settings.json flowModelConfigs.",
 		type: "string",
 	});
+	pi.registerFlag("flow-mode", {
+		description: "Persistently switch the global flow model strategy in ~/.pi/agent/settings.json.",
+		type: "string",
+	});
 	pi.registerFlag("flow-lite-model", {
 		description: "Model for lite-tier flows (scout, debug).",
 		type: "string",
@@ -650,6 +673,10 @@ export default function (pi: ExtensionAPI) {
 		description: "Maximum number of flows to execute in parallel (default: 4).",
 		type: "string",
 	});
+	pi.registerFlag("flow-session-mode", {
+		description: "Default child-flow session mode: fast (300s), default (600s), or long (900s).",
+		type: "string",
+	});
 	pi.registerFlag("auto-transition", {
 		description: "Automatically queue follow-up flows based on hook transitions (default: false).",
 		type: "boolean",
@@ -669,6 +696,7 @@ export default function (pi: ExtensionAPI) {
 	let structuredOutput = true;
 	let maxConcurrency = 4;
 	let autoTransition = false;
+	let defaultSessionMode: AgentSessionMode = DEFAULT_AGENT_SESSION_MODE;
 	const envToolOptimize = process.env[FLOW_TOOL_OPTIMIZE_ENV];
 	if (envToolOptimize !== undefined) {
 		const parsed = parseBoolean(envToolOptimize);
@@ -681,39 +709,96 @@ export default function (pi: ExtensionAPI) {
 		configs: { default: {} },
 		strategy: {},
 	};
+	let activeRuntimeFlowMode: string | undefined;
 
 	// Auto-discover flows on session start
 	pi.on("session_start", async (_event, ctx) => {
 		const discovery = discoverFlows(ctx.cwd, "all");
 		discoveredFlows = discovery.flows;
 		loadedFlowModelConfigs = loadFlowModelConfigs(ctx.cwd);
+		activeRuntimeFlowMode = undefined;
+
+		const requestedFlowMode = normalizeFlowModeName(pi.getFlag("flow-mode"));
+		if (requestedFlowMode !== undefined) {
+			if (!Object.prototype.hasOwnProperty.call(loadedFlowModelConfigs.configs, requestedFlowMode)) {
+				const availableModes = Object.keys(loadedFlowModelConfigs.configs).sort().join(", ") || "(none)";
+				console.warn(
+					`[pi-agent-flow] Cannot switch flow mode to "${requestedFlowMode}"; no flowModelConfigs.${requestedFlowMode} strategy was found. Available modes: ${availableModes}.`,
+				);
+			} else {
+				try {
+					const writeResult = writeGlobalFlowMode(requestedFlowMode);
+					console.warn(`[pi-agent-flow] Flow mode switched to "${requestedFlowMode}" in ${writeResult.path}.`);
+				} catch (error) {
+					const message = error instanceof Error ? error.message : String(error);
+					console.warn(`[pi-agent-flow] ${message}`);
+				}
+
+				const projectFlowModelConfig = loadProjectFlowModelConfigName(ctx.cwd);
+				if (projectFlowModelConfig !== undefined && projectFlowModelConfig !== requestedFlowMode) {
+					console.warn(
+						`[pi-agent-flow] Switched global flow mode to "${requestedFlowMode}"; this project selects "${projectFlowModelConfig}" in .pi/settings.json, so future runs in this project may still use "${projectFlowModelConfig}" unless project settings are changed.`,
+					);
+				}
+
+				activeRuntimeFlowMode = requestedFlowMode;
+				loadedFlowModelConfigs = selectFlowModelStrategy(loadedFlowModelConfigs.configs, requestedFlowMode);
+			}
+		}
 
 		// Register declarative transition hooks from the transition matrix
 		for (const hook of buildTransitionHooks(DEFAULT_TRANSITIONS)) {
 			registerHook(hook);
 		}
 
+		const flowSettings = loadFlowSettings(ctx.cwd);
+		if (typeof flowSettings.structuredOutput === "boolean") {
+			structuredOutput = flowSettings.structuredOutput;
+		}
+		if (typeof flowSettings.maxConcurrency === "number") {
+			maxConcurrency = flowSettings.maxConcurrency;
+		}
+		if (typeof flowSettings.autoTransition === "boolean") {
+			autoTransition = flowSettings.autoTransition;
+		}
+
 		// Resolve toolOptimize: CLI flag > env var > settings.json > default
 		const cliFlag = pi.getFlag("tool-optimize");
+		if (typeof flowSettings.toolOptimize === "boolean") {
+			toolOptimize = flowSettings.toolOptimize;
+		}
+		if (envToolOptimize !== undefined) {
+			const parsed = parseBoolean(envToolOptimize);
+			if (parsed !== null) toolOptimize = parsed;
+		}
 		if (typeof cliFlag === "boolean") {
 			toolOptimize = cliFlag;
 		} else if (typeof cliFlag === "string") {
 			const parsed = parseBoolean(cliFlag);
 			if (parsed !== null) toolOptimize = parsed;
-		} else {
-			const flowSettings = loadFlowSettings(ctx.cwd);
-			if (typeof flowSettings.toolOptimize === "boolean") {
-				toolOptimize = flowSettings.toolOptimize;
-			}
-			if (typeof flowSettings.structuredOutput === "boolean") {
-				structuredOutput = flowSettings.structuredOutput;
-			}
-			if (typeof flowSettings.maxConcurrency === "number") {
-				maxConcurrency = flowSettings.maxConcurrency;
+		}
+
+		// Resolve sessionMode: CLI flag > env var > settings.json > default
+		defaultSessionMode = flowSettings.sessionMode ?? DEFAULT_AGENT_SESSION_MODE;
+		const envSessionModeRaw = process.env[PI_FLOW_SESSION_MODE_ENV];
+		if (envSessionModeRaw !== undefined) {
+			const envSessionMode = parseAgentSessionMode(envSessionModeRaw);
+			if (envSessionMode !== undefined) {
+				defaultSessionMode = envSessionMode;
+			} else {
+				console.warn(`[pi-agent-flow] Ignoring invalid ${PI_FLOW_SESSION_MODE_ENV}="${envSessionModeRaw}". Expected fast, default, or long.`);
 			}
-			if (typeof flowSettings.autoTransition === "boolean") {
-				autoTransition = flowSettings.autoTransition;
+		}
+		const cliSessionModeRaw = pi.getFlag("flow-session-mode");
+		if (typeof cliSessionModeRaw === "string") {
+			const cliSessionMode = parseAgentSessionMode(cliSessionModeRaw);
+			if (cliSessionMode !== undefined) {
+				defaultSessionMode = cliSessionMode;
+			} else {
+				console.warn(`[pi-agent-flow] Ignoring invalid --flow-session-mode value "${cliSessionModeRaw}". Expected fast, default, or long.`);
 			}
+		} else if (inheritedCliArgs.flowSessionMode !== undefined) {
+			defaultSessionMode = inheritedCliArgs.flowSessionMode;
 		}
 
 		// Resolve maxConcurrency: CLI flag > env var > settings.json > default
@@ -908,7 +993,8 @@ flow [type] accomplished
 				"You MUST enter to the following flow states, with tool call method.",
 				"",
 				"Flow states are isolated \u03c0 processes with forked session snapshots. They run in parallel.",
-				'Invoke: { "flow": [{ "type": "scout", "intent": "..." }, ...] }',
+				'Invoke: { "flow": [{ "type": "scout", "intent": "...", "aim": "...", "sessionMode": "default" }, ...] }',
+				"Session modes: fast=300s, default=600s, long=900s. Use long only when the work genuinely needs the larger budget.",
 				"States: scout, debug, build, craft, audit, ideas.",
 				"Custom states configs in (create if not exists): .md files in .pi/agents/ or ~/.pi/agent/agents/.",
 			].join("\n"),
@@ -953,10 +1039,11 @@ flow [type] accomplished
 						loadedFlowModelConfigs,
 						maxConcurrency,
 						autoTransition,
+						defaultSessionMode,
 						signal,
 						onUpdate,
 						makeDetails,
-						getFlag: (name: string) => pi.getFlag(name),
+						getFlag: (name: string) => name === "flow-mode" ? activeRuntimeFlowMode : pi.getFlag(name),
 						tierOverrideResolver: getTierOverride,
 						fallbackModel: inheritedCliArgs.fallbackModel,
 						forkSessionSnapshotJsonl,
@@ -968,7 +1055,7 @@ flow [type] accomplished
 						onFlowMetrics: (metrics) => { if (typeof pi.emit === "function") pi.emit("pi-agent-flow:complete", metrics); },
 						confirmProjectFlows: params.confirmProjectFlows,
 					},
-					params.flow.map((f: any) => ({ type: f.type, intent: f.intent, aim: f.aim, cwd: f.cwd })),
+					params.flow.map((f: any) => ({ type: f.type, intent: f.intent, aim: f.aim, cwd: f.cwd, sessionMode: f.sessionMode })),
 					toolCallId,
 				);
 

package/src/render-utils.ts

@@ -43,6 +43,10 @@ function formatTps(value: number | undefined): string {
 	return value.toFixed(1).padStart(5);
 }
 
+export function formatCompactTokenPair(usage: Partial<UsageStats>): string {
+	return `↑ ${formatFixedTokens(usage.input || 0)} · ↓ ${formatFixedTokens(usage.output || 0)}`;
+}
+
 export function formatCompactStats(usage: Partial<UsageStats>, model?: string, maxWidth?: number): string {
 	const parts: string[] = [];
 	parts.push(`↑ ${formatFixedTokens(usage.input || 0)}`);
@@ -72,6 +76,13 @@ export function formatCompactStats(usage: Partial<UsageStats>, model?: string, m
 	return result;
 }
 
+export function formatCountdown(ms: number): string {
+	const totalSeconds = Math.max(0, Math.ceil(ms / 1000));
+	const minutes = Math.floor(totalSeconds / 60);
+	const seconds = totalSeconds % 60;
+	return `${String(minutes).padStart(2, "0")}:${String(seconds).padStart(2, "0")}`;
+}
+
 /** Regex matching ANSI escape sequences. */
 const ANSI_RE = /\x1b\[[0-9;]*m/g;
 

package/src/render.ts

@@ -22,7 +22,7 @@ import {
 	isFlowError,
 	isFlowSuccess,
 } from "./types.js";
-import { formatCompactStats, formatFlowTypeName, truncateChars, tailText, contentBudget } from "./render-utils.js";
+import { formatCompactStats, formatCompactTokenPair, formatCountdown, formatFlowTypeName, truncateChars, tailText, contentBudget, visibleLength } from "./render-utils.js";
 
 function shortenPath(p: string): string {
 	const home = os.homedir();
@@ -138,6 +138,20 @@ function sectionHeader(label: string): string {
 	return `${left} ${label} ${right}`;
 }
 
+function getLiveCountdown(r: SingleResult): string | undefined {
+	if (r.exitCode !== -1 || typeof r.deadlineAtMs !== "number") return undefined;
+	return formatCountdown(r.deadlineAtMs - Date.now());
+}
+
+function formatAimLinePrefix(treePrefix: string, r: SingleResult): string {
+	const countdown = getLiveCountdown(r);
+	return countdown ? `${treePrefix} aim: [${countdown}] - ` : `${treePrefix} aim: `;
+}
+
+function formatMsgLinePrefix(treePrefix: string, r: SingleResult): string {
+	return `${treePrefix} msg: [${formatCompactTokenPair(r.usage)}] - `;
+}
+
 // ---------------------------------------------------------------------------
 // renderFlowCall — shown while the flow is being invoked
 // ---------------------------------------------------------------------------
@@ -313,37 +327,40 @@ function renderFlowCollapsed(
 
 	// aim: line (short headline)
 	if (r.aim) {
-		const dirContent = truncateChars(r.aim, contentBudget(10));
-		container.addChild(new TruncatedText(`${theme.fg("dim", "├─ aim:")} ${theme.fg("dim", dirContent)}`, 0, 0));
+		const aimPrefix = formatAimLinePrefix("├─", r);
+		const dirContent = truncateChars(r.aim, contentBudget(visibleLength(aimPrefix)));
+		container.addChild(new TruncatedText(`${theme.fg("dim", aimPrefix)}${theme.fg("dim", dirContent)}`, 0, 0));
 	}
 
 	// act: line (last tool call with count)
 	const lastTool = getLastToolCall(r.messages);
 	if (lastTool) {
 		const actStr = formatFlowToolCall(lastTool.name, lastTool.args, theme.fg.bind(theme));
-		const actPrefix = `act: [${r.usage.toolCalls}] - `;
-		const actContent = truncateChars(actStr, contentBudget(10));
-		container.addChild(new TruncatedText(`${theme.fg("dim", "├─ " + actPrefix)}${actContent}`, 0, 0));
+		const actPrefix = `├─ act: [${r.usage.toolCalls}] - `;
+		const actContent = truncateChars(actStr, contentBudget(visibleLength(actPrefix)));
+		container.addChild(new TruncatedText(`${theme.fg("dim", actPrefix)}${actContent}`, 0, 0));
 	}
 
 	// msg: line (last assistant text or streaming)
+	const msgPrefix = formatMsgLinePrefix("└─", r);
+	const msgBudget = contentBudget(visibleLength(msgPrefix));
 	if (r.exitCode === -1 && streamingText) {
-		const logContent = tailText(streamingText, contentBudget(10));
-		container.addChild(new TruncatedText(`${theme.fg("dim", "└─ msg:")} ${theme.fg("dim", logContent)}`, 0, 0));
+		const logContent = tailText(streamingText, msgBudget);
+		container.addChild(new TruncatedText(`${theme.fg("dim", msgPrefix)}${theme.fg("dim", logContent)}`, 0, 0));
 	} else if (r.structuredOutput?.summary) {
-		const logContent = truncateChars(r.structuredOutput.summary, contentBudget(10));
-		container.addChild(new TruncatedText(`${theme.fg("dim", "└─ msg:")} ${theme.fg("dim", logContent)}`, 0, 0));
+		const logContent = truncateChars(r.structuredOutput.summary, msgBudget);
+		container.addChild(new TruncatedText(`${theme.fg("dim", msgPrefix)}${theme.fg("dim", logContent)}`, 0, 0));
 	} else if (flowOutput) {
-		const logContent = tailText(flowOutput, contentBudget(10));
-		container.addChild(new TruncatedText(`${theme.fg("dim", "└─ msg:")} ${theme.fg("dim", logContent)}`, 0, 0));
+		const logContent = tailText(flowOutput, msgBudget);
+		container.addChild(new TruncatedText(`${theme.fg("dim", msgPrefix)}${theme.fg("dim", logContent)}`, 0, 0));
 	} else if (streamingText) {
-		const logContent = tailText(streamingText, contentBudget(10));
-		container.addChild(new TruncatedText(`${theme.fg("dim", "└─ msg:")} ${theme.fg("dim", logContent)}`, 0, 0));
+		const logContent = tailText(streamingText, msgBudget);
+		container.addChild(new TruncatedText(`${theme.fg("dim", msgPrefix)}${theme.fg("dim", logContent)}`, 0, 0));
 	} else if (error && r.errorMessage) {
-		const logContent = truncateChars(r.errorMessage, contentBudget(10));
-		container.addChild(new TruncatedText(`${theme.fg("dim", "└─ msg:")} ${theme.fg("error", logContent)}`, 0, 0));
+		const logContent = truncateChars(r.errorMessage, msgBudget);
+		container.addChild(new TruncatedText(`${theme.fg("dim", msgPrefix)}${theme.fg("error", logContent)}`, 0, 0));
 	} else {
-		container.addChild(new TruncatedText(`${theme.fg("dim", "└─ msg:")} ${theme.fg("dim", "[n/a]")}`, 0, 0));
+		container.addChild(new TruncatedText(`${theme.fg("dim", msgPrefix)}${theme.fg("dim", "[n/a]")}`, 0, 0));
 	}
 
 	return container;
@@ -451,30 +468,33 @@ function renderActivityPanel(
 
 		// aim: line (short headline)
 		if (r.aim) {
-			const dirContent = truncateChars(r.aim, contentBudget(10));
-			container.addChild(new TruncatedText(`${theme.fg("dim", indent + "├─ aim:")} ${theme.fg("dim", dirContent)}`, 0, 0));
+			const aimPrefix = formatAimLinePrefix(indent + "├─", r);
+			const dirContent = truncateChars(r.aim, contentBudget(visibleLength(aimPrefix)));
+			container.addChild(new TruncatedText(`${theme.fg("dim", aimPrefix)}${theme.fg("dim", dirContent)}`, 0, 0));
 		}
 
 		// act: line (last tool call with count)
 		const lastTool = getLastToolCall(r.messages);
 		if (lastTool) {
 			const actStr = formatFlowToolCall(lastTool.name, lastTool.args, theme.fg.bind(theme));
-			const actPrefix = `act: [${r.usage.toolCalls}] - `;
-			const actContent = truncateChars(actStr, contentBudget(10));
-			container.addChild(new TruncatedText(`${theme.fg("dim", indent + "├─ " + actPrefix)}${actContent}`, 0, 0));
+			const actPrefix = `${indent}├─ act: [${r.usage.toolCalls}] - `;
+			const actContent = truncateChars(actStr, contentBudget(visibleLength(actPrefix)));
+			container.addChild(new TruncatedText(`${theme.fg("dim", actPrefix)}${actContent}`, 0, 0));
 		}
 
 		// msg: line (live streaming text or last assistant text)
+		const msgPrefix = formatMsgLinePrefix(indent + "└─", r);
+		const msgBudget = contentBudget(visibleLength(msgPrefix));
 		const liveText = r.exitCode === -1 ? r.streamingText : undefined;
 		const lastText = liveText || getLastAssistantText(r.messages);
 		if (lastText) {
-			const logContent = tailText(lastText, contentBudget(10));
-			container.addChild(new TruncatedText(`${theme.fg("dim", indent + "└─ msg:")} ${theme.fg("dim", logContent)}`, 0, 0));
+			const logContent = tailText(lastText, msgBudget);
+			container.addChild(new TruncatedText(`${theme.fg("dim", msgPrefix)}${theme.fg("dim", logContent)}`, 0, 0));
 		} else if (error && r.errorMessage) {
-			const logContent = truncateChars(r.errorMessage, contentBudget(10));
-			container.addChild(new TruncatedText(`${theme.fg("dim", indent + "└─ msg:")} ${theme.fg("error", logContent)}`, 0, 0));
+			const logContent = truncateChars(r.errorMessage, msgBudget);
+			container.addChild(new TruncatedText(`${theme.fg("dim", msgPrefix)}${theme.fg("error", logContent)}`, 0, 0));
 		} else {
-			container.addChild(new TruncatedText(`${theme.fg("dim", indent + "└─ msg:")} ${theme.fg("dim", "[n/a]")}`, 0, 0));
+			container.addChild(new TruncatedText(`${theme.fg("dim", msgPrefix)}${theme.fg("dim", "[n/a]")}`, 0, 0));
 		}
 
 		// Add blank line separator between flows (with continuation pipe)

package/src/session-mode.ts

@@ -0,0 +1,32 @@
+export const AGENT_SESSION_MODES = ["fast", "default", "long"] as const;
+
+export type AgentSessionMode = typeof AGENT_SESSION_MODES[number];
+
+export const DEFAULT_AGENT_SESSION_MODE: AgentSessionMode = "default";
+export const MAX_AGENT_SESSION_TIMEOUT_MS = 900_000;
+export const PI_FLOW_SESSION_MODE_ENV = "PI_FLOW_SESSION_MODE";
+
+export const AGENT_SESSION_TIMEOUTS_MS: Record<AgentSessionMode, number> = {
+	fast: 300_000,
+	default: 600_000,
+	long: MAX_AGENT_SESSION_TIMEOUT_MS,
+};
+
+export function parseAgentSessionMode(value: unknown): AgentSessionMode | undefined {
+	if (typeof value !== "string") return undefined;
+	const normalized = value.trim().toLowerCase();
+	return (AGENT_SESSION_MODES as readonly string[]).includes(normalized)
+		? normalized as AgentSessionMode
+		: undefined;
+}
+
+export function resolveAgentSessionMode(
+	value: unknown,
+	fallback: AgentSessionMode = DEFAULT_AGENT_SESSION_MODE,
+): AgentSessionMode {
+	return parseAgentSessionMode(value) ?? fallback;
+}
+
+export function getAgentSessionTimeoutMs(mode: AgentSessionMode): number {
+	return AGENT_SESSION_TIMEOUTS_MS[mode];
+}

package/src/types.ts

@@ -122,6 +122,10 @@ export interface SingleResult {
 	stopReason?: string;
 	errorMessage?: string;
 	sawAgentEnd?: boolean;
+	/** Epoch ms when flow execution started; used for live countdown rendering. */
+	startedAtMs?: number;
+	/** Epoch ms when the flow hard timeout occurs; used for live countdown rendering. */
+	deadlineAtMs?: number;
 	/** Live in-progress text for status rendering; not part of the final flow report. */
 	streamingText?: string;
 	/** Structured JSON output parsed from the flow's final response. */