pi-agent-flow 1.4.3 → 1.5.0

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
@@ -80,8 +81,8 @@ The result is faster, cheaper, and cleaner delegation: the main agent remains un
 | Flow | Purpose | Tools | Tier |
 |------|---------|-------|------|
 | `[scout]` | Discover files, trace code paths, map architecture | `batch`, `bash`, `find`, `grep`, `ls` | `lite` |
-| `[debug]` | Investigate logs, errors, stack traces, root causes | `batch`, `bash`, `find`, `grep`, `ls` | `lite` |
-| `[build]` | Implement features, fix bugs, write tests, ship | `batch`, `bash`, `find`, `grep`, `ls` | `flash` |
+| `[debug]` | Investigate logs, errors, stack traces, root causes, and update relevant troubleshooting docs | `batch`, `bash`, `find`, `grep`, `ls` | `lite` |
+| `[build]` | Implement features, fix bugs, write tests, update relevant docs, ship | `batch`, `bash`, `find`, `grep`, `ls` | `flash` |
 | `[craft]` | Plan structure, break down requirements, design solutions | `batch`, `bash`, `find`, `grep`, `ls` | `full` |
 | `[audit]` | Audit security, quality, correctness; fix issues autonomously | `batch`, `bash`, `find`, `grep`, `ls` | `flash` |
 | `[ideas]` | Generate ideas and explore possibilities with inherited context | `batch`, `bash` | `full` |
@@ -90,6 +91,35 @@ 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.
 
+> **Docs hygiene:** Bundled `build` and `debug` flows are instructed to update relevant documentation after their work when the findings or implementation change developer or operational knowledge. If no docs apply, they should state why in the final report.
+
+### 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 +289,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 +326,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 +344,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/agents/build.md

@@ -17,8 +17,9 @@ During this build flow — your mission is to implement and verify changes. Be a
 4. Execute — implement changes following core principles.
 5. Refactor — clean up only if the change is working.
 6. Verify — run tests and relevant checks before considering the work done.
-7. Ship — commit, push, monitor CI/CD, and fix failures until green when shipping is in scope.
-8. Finalize — confirm implementation, tests, and CI/CD status.
+7. Document — update relevant docs after the implementation and verification are settled; if no docs apply, state why.
+8. Ship — commit, push, monitor CI/CD, and fix failures until green when shipping is in scope.
+9. Finalize — confirm implementation, docs, tests, and CI/CD status.
 
 ## Rules
 
@@ -28,6 +29,7 @@ During this build flow — your mission is to implement and verify changes. Be a
 - If already on a feature/fix branch, continue on it.
 - Commit with a clear conventional message such as `feat:`, `fix:`, or `refactor:` when committing is in scope.
 - Push only after local verification passes when shipping is in scope.
+- Update relevant documentation after finishing the work; if no docs changed, explain why in the final report.
 - If CI/CD fails, diagnose, fix, commit, push, and repeat until green.
 - If an unexpected error or trace is needed, recommend [debug] rather than guessing.
 

package/agents/debug.md

@@ -16,6 +16,8 @@ During this debug flow — your mission is to investigate root cause. Be forensi
 3. Check changes — inspect recent diffs, configuration, dependencies, and environment differences.
 4. Identify root cause — state exactly what is broken and why.
 5. Recommend fix — propose the smallest safe correction only after evidence confirms the cause.
+6. Document — update relevant docs, runbooks, or troubleshooting notes after finishing the investigation; if no docs apply, state why.
+7. Finalize — confirm root cause, evidence, documentation updates, and recommended next steps.
 
 ## Rules
 
@@ -23,7 +25,8 @@ During this debug flow — your mission is to investigate root cause. Be forensi
 - Read logs and symptoms before reading broad code areas.
 - Use `batch` with `o: "read"`, `s: <offset>`, and `l: <limit>` for targeted file reading instead of bash `sed`/`head`/`tail`.
 - Do not suggest fixes until root cause is confirmed.
-- Do not implement changes from this flow unless explicitly requested.
+- Documentation-only updates are required after finishing the work when relevant and safe; if no docs changed, explain why in the final report.
+- Do not implement product-code changes from this flow unless explicitly requested.
 
 ## Note
 Treat this as a clean-slate system rewrite, unless explicitly mentioned in the requirements. Perform a comprehensive migration with zero requirements for backwards compatibility. You must ensure that all residual code, variable names, test suites, and documentation are fully refactored and perfectly aligned with the new architecture.

package/package.json

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

package/src/agents.ts

@@ -56,6 +56,18 @@ export function getFlowTier(flowName: string): FlowTier {
 	}
 }
 
+/** Return the bundled flow names associated with a given tier. */
+export function getTierFlowNames(tier: FlowTier): string[] {
+	switch (tier) {
+		case "lite":
+			return ["scout", "debug"];
+		case "flash":
+			return ["build", "audit"];
+		case "full":
+			return ["ideas", "craft"];
+	}
+}
+
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------

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,8 +8,9 @@
 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";
+import { type FlowTier } from "./agents.js";
 
-export type FlowTier = "lite" | "flash" | "full";
 
 export interface FlowModelTierConfig {
 	primary?: string;
@@ -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 };
@@ -318,3 +369,23 @@ export function resolveFlowModelCandidates(opts: {
 
 	return { primary: candidates[0], candidates };
 }
+
+export function formatFlowModelStrategy(modeName: string, strategy: FlowModelStrategy): string {
+	const tiers: FlowTier[] = ["lite", "flash", "full"];
+	const parts: string[] = [];
+	for (const tier of tiers) {
+		const config = strategy[tier];
+		const hasPrimary = Boolean(config?.primary);
+		const hasFailover = config?.failover && config.failover.length > 0;
+		let value: string;
+		if (hasPrimary) {
+			value = config!.primary!;
+		} else if (hasFailover) {
+			value = `failover: ${config!.failover!.join(", ")}`;
+		} else {
+			value = "(default)";
+		}
+		parts.push(`${tier}: ${value}`);
+	}
+	return `mode: ${modeName} | ${parts.join(" · ")}`;
+}

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,12 @@ import { type FlowConfig, discoverFlows, getFlowTier } from "./agents.js";
 import {
 	loadFlowModelConfigs,
 	loadFlowSettings,
+	loadProjectFlowModelConfigName,
+	normalizeFlowModeName,
 	resolveFlowModelCandidates,
 	selectFlowModelStrategy,
+	writeGlobalFlowMode,
+	formatFlowModelStrategy,
 	type LoadedFlowModelConfigs,
 } from "./config.js";
 import { getInheritedCliArgs } from "./cli-args.js";
@@ -55,6 +59,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 +95,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 +654,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 +674,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 +697,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 +710,98 @@ 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 {
+					writeGlobalFlowMode(requestedFlowMode);
+					const strategy = loadedFlowModelConfigs.configs[requestedFlowMode] ?? {};
+					const strategyDescription = formatFlowModelStrategy(requestedFlowMode, strategy);
+					console.warn(strategyDescription);
+				} 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 +996,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 +1042,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 +1058,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,
 				);
 
@@ -1004,7 +1094,12 @@ flow [type] accomplished
 		pi.emit("pi-agent-flow:ready", pluginApi);
 	}
 
-	// Register cleanup on process exit (once)
+	// Register cleanup on process exit (once).
+	// We intentionally do NOT hook SIGINT/SIGTERM here. A plugin must not
+	// override the host process signal handling; doing so can cut off the
+	// host's terminal-cleanup logic and leave escape sequences or status
+	// lines visible on Ctrl+C. The 'exit' event fires for normal exits,
+	// including when the host handles the signal and calls process.exit().
 	if (!(globalThis as any).__pi_agent_flow_shutdown_registered) {
 		(globalThis as any).__pi_agent_flow_shutdown_registered = true;
 		const emitShutdown = () => {
@@ -1013,8 +1108,6 @@ flow [type] accomplished
 			}
 		};
 		process.on("exit", emitShutdown);
-		process.on("SIGINT", () => { emitShutdown(); process.exit(130); });
-		process.on("SIGTERM", () => { emitShutdown(); process.exit(143); });
 	}
 
 }

package/src/render-utils.ts

@@ -43,27 +43,34 @@ function formatTps(value: number | undefined): string {
 	return value.toFixed(1).padStart(5);
 }
 
-export function formatCompactStats(usage: Partial<UsageStats>, model?: string, maxWidth?: number): string {
-	const parts: string[] = [];
-	parts.push(`↑ ${formatFixedTokens(usage.input || 0)}`);
-	parts.push(`↓ ${formatFixedTokens(usage.output || 0)}`);
-	parts.push(`tps: ${formatTps(usage.smoothedTps)}`);
-	parts.push(`ctx: ${formatFixedTokens(usage.contextTokens || 0)}`);
+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,
+	options: { skipTokens?: boolean } = {},
+): string {
+	const tokenParts = [`↑ ${formatFixedTokens(usage.input || 0)}`, `↓ ${formatFixedTokens(usage.output || 0)}`];
+	const runtimeParts = [`tps: ${formatTps(usage.smoothedTps)}`, `ctx: ${formatFixedTokens(usage.contextTokens || 0)}`];
+	const parts = options.skipTokens ? runtimeParts : [...tokenParts, ...runtimeParts];
 
 	const displayModel = model ? model.replace(/^[^/]+\//, "") : undefined;
 	let result = parts.join(" · ") + (displayModel ? ` · ${displayModel}` : "");
 	if (maxWidth && visibleLength(result) > maxWidth) {
-		// Drop model first
+		// Drop model first.
 		let narrow = parts.join(" · ");
 		if (visibleLength(narrow) <= maxWidth) return narrow;
 
-		// Drop context tokens
-		const narrowParts = parts.slice(0, 3); // up to tps
-		narrow = narrowParts.join(" · ");
+		// Drop context tokens next.
+		const withoutContext = parts.filter((part) => !part.startsWith("ctx:"));
+		narrow = withoutContext.join(" · ");
 		if (visibleLength(narrow) <= maxWidth) return narrow;
 
-		// Bare minimum (just input/output)
-		narrow = `${parts[0]} · ${parts[1]}`;
+		// Bare minimum: token pair for normal stats, tps for token-free headers.
+		narrow = options.skipTokens ? runtimeParts[0] : tokenParts.join(" · ");
 		if (visibleLength(narrow) <= maxWidth) return narrow;
 
 		return truncateChars(result, maxWidth);
@@ -72,6 +79,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
 // ---------------------------------------------------------------------------
@@ -305,7 +319,7 @@ function renderFlowCollapsed(
 ): Container {
 	const container = new Container();
 	const maxWidth = process.stdout.columns ?? 80;
-	const stats = formatCompactStats(r.usage, r.model, maxWidth);
+	const stats = formatCompactStats(r.usage, r.model, maxWidth, { skipTokens: true });
 	const typeName = formatFlowTypeName(r.type);
 	let header = `${theme.fg("accent", theme.bold(typeName))} ${theme.fg("dim", stats)}`;
 	if (error && r.stopReason) header += ` ${theme.fg("error", `[${r.stopReason}]`)}`;
@@ -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;
@@ -434,7 +451,7 @@ function renderActivityPanel(
 	for (let i = 0; i < results.length; i++) {
 		const r = results[i];
 		const isLast = i === results.length - 1;
-		const stats = formatCompactStats(r.usage, r.model, maxWidth);
+		const stats = formatCompactStats(r.usage, r.model, maxWidth, { skipTokens: true });
 		const error = isFlowError(r);
 		const typeName = formatFlowTypeName(r.type);
 
@@ -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. */