pi-subagents 0.46.0 → 0.47.1

package/src/runs/foreground/workflow-foreground-steering.ts

@@ -0,0 +1,187 @@
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { Details, ForegroundRunControl, SubagentState } from "../../shared/types.ts";
+import { readStatus } from "../../shared/utils.ts";
+import {
+	consumeSteerAckFromDir,
+	readSteerCapability,
+	steerAcksDir,
+	steerCapabilityPath,
+	stepSteerInboxDir,
+	writeSteerRequestToExistingDir,
+	type SteerDeliveryMode,
+	type SteerRequest,
+} from "../background/control-channel.ts";
+
+export interface WorkflowForegroundSteeringTarget {
+	control: ForegroundRunControl;
+	workflowRunId: string;
+	sourceRunId: string;
+}
+
+export type WorkflowForegroundSteeringResolution =
+	| { ok: true; target: WorkflowForegroundSteeringTarget }
+	| { ok: false; message: string };
+
+function activeWorkflowError(state: SubagentState, workflowRunId: string, asyncDirRoot: string): string | undefined {
+	if (!state.currentSessionId) return "Workflow steering requires an active parent session.";
+	if (!state.workflowControllers?.has(workflowRunId)) return `Workflow '${workflowRunId}' has no live foreground child.`;
+	const status = readStatus(path.join(asyncDirRoot, workflowRunId));
+	if (!status || status.mode !== "workflow" || (status.state !== "running" && status.state !== "queued")) {
+		return `Workflow '${workflowRunId}' has no live foreground child.`;
+	}
+	if (status.sessionId !== state.currentSessionId) return `Workflow '${workflowRunId}' was not found in the active session.`;
+	return undefined;
+}
+
+function controlIsLiveInWorkflow(control: ForegroundRunControl, workflowRunId: string, sessionId: string): boolean {
+	return control.parentWorkflowRunId === workflowRunId
+		&& control.sessionId === sessionId
+		&& Boolean(control.workflowSteeringDir)
+		&& (control.activeChildren?.size ?? 0) > 0;
+}
+
+export function resolveWorkflowForegroundSteeringTarget(input: {
+	state: SubagentState;
+	childRunId?: string;
+	workflowRunId?: string;
+	asyncDirRoot: string;
+}): WorkflowForegroundSteeringResolution {
+	const { state, childRunId, asyncDirRoot } = input;
+	if (childRunId) {
+		const control = state.foregroundControls.get(childRunId);
+		if (!control?.parentWorkflowRunId) return { ok: false, message: `Foreground run '${childRunId}' is not a live workflow-owned child.` };
+		const workflowRunId = control.parentWorkflowRunId;
+		const workflowError = activeWorkflowError(state, workflowRunId, asyncDirRoot);
+		if (workflowError) return { ok: false, message: workflowError };
+		if (!controlIsLiveInWorkflow(control, workflowRunId, state.currentSessionId!)) {
+			return { ok: false, message: `Foreground run '${childRunId}' is not a live workflow-owned child in the active session.` };
+		}
+		return { ok: true, target: { control, workflowRunId, sourceRunId: childRunId } };
+	}
+
+	const workflowRunId = input.workflowRunId;
+	if (!workflowRunId) return { ok: false, message: "Workflow steering requires a workflow or child run id." };
+	const workflowError = activeWorkflowError(state, workflowRunId, asyncDirRoot);
+	if (workflowError) return { ok: false, message: workflowError };
+	const controls = [...state.foregroundControls.values()].filter((control) => controlIsLiveInWorkflow(control, workflowRunId, state.currentSessionId!));
+	if (controls.length === 0) return { ok: false, message: `Workflow '${workflowRunId}' has no live foreground child.` };
+	if (controls.length > 1) return { ok: false, message: `Workflow '${workflowRunId}' has ${controls.length} live foreground children; steer a child run id instead.` };
+	return { ok: true, target: { control: controls[0]!, workflowRunId, sourceRunId: workflowRunId } };
+}
+
+function managementError(message: string): AgentToolResult<Details> {
+	return { content: [{ type: "text", text: message }], isError: true, details: { mode: "management", results: [] } };
+}
+
+export async function steerWorkflowForegroundTarget(input: {
+	target: WorkflowForegroundSteeringTarget;
+	message: string;
+	mode?: SteerDeliveryMode;
+	index?: number;
+	signal?: AbortSignal;
+	ackTimeoutMs?: number;
+}): Promise<AgentToolResult<Details>> {
+	const { control, sourceRunId } = input.target;
+	const routeDir = control.workflowSteeringDir;
+	if (!routeDir || !fs.existsSync(routeDir)) return managementError(`Foreground run '${control.runId}' has no live workflow steering route.`);
+	const activeIndexes = [...(control.activeChildren?.keys() ?? [])].sort((left, right) => left - right);
+	const index = input.index ?? (activeIndexes.length === 1 ? activeIndexes[0] : undefined);
+	if (index === undefined) {
+		return managementError(activeIndexes.length === 0
+			? `Foreground run '${control.runId}' has no live child session.`
+			: `Foreground run '${control.runId}' has ${activeIndexes.length} live child sessions; provide index.`);
+	}
+	if (!activeIndexes.includes(index)) return managementError(`Foreground run '${control.runId}' child ${index} is not live.`);
+	const capability = readSteerCapability(routeDir, index);
+	if (capability?.supported === false) return managementError(`Foreground run '${control.runId}' child ${index} does not support steering.`);
+
+	const request: SteerRequest = {
+		type: "steer",
+		id: randomUUID(),
+		ts: Date.now(),
+		message: input.message.trim(),
+		...(input.mode && input.mode !== "steer" ? { mode: input.mode } : {}),
+		targetIndex: index,
+		source: "steer-action",
+	};
+	try {
+		writeSteerRequestToExistingDir(stepSteerInboxDir(routeDir, index), request);
+	} catch (error) {
+		if (typeof error === "object" && error !== null && "code" in error && (error as NodeJS.ErrnoException).code === "ENOENT") {
+			return managementError(`Foreground run '${control.runId}' has no live workflow steering route.`);
+		}
+		return managementError(`Failed to queue steering for foreground run ${control.runId}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+
+	const deadline = Date.now() + (input.ackTimeoutMs ?? 3_000);
+	let ack;
+	let routeRemoved = false;
+	while (Date.now() <= deadline) {
+		ack = consumeSteerAckFromDir(steerAcksDir(routeDir, index), request.id);
+		if (ack || input.signal?.aborted) break;
+		if (!fs.existsSync(routeDir)) {
+			routeRemoved = true;
+			break;
+		}
+		await new Promise<void>((resolve) => setTimeout(resolve, Math.min(50, Math.max(1, deadline - Date.now()))));
+	}
+	if (routeRemoved || (!ack && !input.signal?.aborted && !fs.existsSync(routeDir))) {
+		return managementError(`Foreground run '${control.runId}' has no live child session.`);
+	}
+	const target = ack?.state === "delivered"
+		? { index, state: "delivered" as const, deliveredAt: ack.ts }
+		: ack?.state === "queued"
+			? { index, state: "queued" as const }
+			: ack?.state === "failed"
+				? { index, state: "failed" as const, reason: ack.message }
+				: { index, state: "pending" as const };
+	const steering = {
+		requestId: request.id,
+		state: ack?.state === "delivered" ? "delivered" as const : ack?.state === "failed" ? "failed" as const : "pending" as const,
+		deliveryStatus: ack?.state === "delivered" ? "delivered" as const : "queued" as const,
+		sourceRunId,
+		targets: [target],
+	};
+	if (input.signal?.aborted) {
+		return { content: [{ type: "text", text: `Steering pending for foreground run ${control.runId} (request ${request.id}); caller aborted before acknowledgment.` }], details: { mode: "management", results: [], steering } };
+	}
+	if (ack?.state === "delivered") {
+		return { content: [{ type: "text", text: `Steering delivered for foreground run ${control.runId} (request ${request.id}).` }], details: { mode: "management", results: [], steering } };
+	}
+	if (ack?.state === "queued") {
+		return { content: [{ type: "text", text: `Steering queued for foreground run ${control.runId} (request ${request.id}).` }], details: { mode: "management", results: [], steering } };
+	}
+	if (ack?.state === "failed") {
+		return { content: [{ type: "text", text: `Steering failed for foreground run ${control.runId} (request ${request.id}): ${ack.message}` }], isError: true, details: { mode: "management", results: [], steering } };
+	}
+	return { content: [{ type: "text", text: `Steering pending for foreground run ${control.runId} (request ${request.id}); no acknowledgment was received.` }], details: { mode: "management", results: [], steering } };
+}
+
+export function workflowForegroundSteeringDir(asyncDirRoot: string, workflowRunId: string, childRunId: string): string {
+	return path.join(asyncDirRoot, workflowRunId, "control", "workflow-foreground", childRunId);
+}
+
+export function removeWorkflowForegroundSteeringRoute(control: ForegroundRunControl): void {
+	if (!control.workflowSteeringDir) return;
+	try {
+		fs.rmSync(control.workflowSteeringDir, { recursive: true, force: true });
+	} catch (error) {
+		console.warn(`[pi-subagents] Failed to remove workflow foreground steering route '${control.workflowSteeringDir}': ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+
+export function workflowForegroundSteeringLaunchOptions(control: ForegroundRunControl | undefined, index: number): Pick<import("../../shared/types.ts").RunSyncOptions, "steerInboxDir" | "steerCapabilityPath" | "steerAckDir"> {
+	if (!control?.workflowSteeringDir) return {};
+	const steerInboxDir = stepSteerInboxDir(control.workflowSteeringDir, index);
+	const steerAckDir = steerAcksDir(control.workflowSteeringDir, index);
+	fs.mkdirSync(steerInboxDir, { recursive: true });
+	fs.mkdirSync(steerAckDir, { recursive: true });
+	return {
+		steerInboxDir,
+		steerCapabilityPath: steerCapabilityPath(control.workflowSteeringDir, index),
+		steerAckDir,
+	};
+}

package/src/runs/shared/dynamic-fanout.ts

@@ -49,7 +49,7 @@ const DYNAMIC_EXPAND_FROM_KEYS = new Set(["output", "path"]);
 const DYNAMIC_PARALLEL_KEYS = new Set(["agent", "task", "phase", "label", "outputSchema", "cwd", "output", "outputMode", "reads", "progress", "skill", "model", "toolBudget", "acceptance", "agentContract", "gateOn"]);
 const RUNNER_DYNAMIC_PARALLEL_KEYS = new Set([
 	...DYNAMIC_PARALLEL_KEYS,
-	"outputName", "structured", "inheritProjectContext", "inheritSkills", "skills", "outputPath", "namespaceOutputPath", "maxSubagentDepth", "waitToolEnabled",
+	"outputName", "structured", "inheritProjectContext", "inheritSkills", "skills", "outputPath", "namespaceOutputPath", "maxSubagentDepth", "timeoutMs", "waitToolEnabled",
 	"structuredOutput", "structuredOutputSchema", "tools", "extensions", "subagentOnlyExtensions", "mcpDirectTools", "capabilityCeiling", "completionGuard", "systemPrompt",
 	"systemPromptMode", "thinking", "modelCandidates", "sessionFile", "effectiveAcceptance", "acceptanceInput", "acceptanceRole", "parentSessionId", "launchResolvedExtensions",
 ]);

package/src/runs/shared/model-fallback.ts

@@ -191,7 +191,8 @@ function defaultScopeWarn(violation: ModelScopeViolation): void {
  *
  * An explicitly requested model string is resolved via {@link resolveModelCandidate}.
  * When `options.scope.enforce` is on, an out-of-scope resolved model throws for
- * an explicit (`source: "explicit"`) request and warns for an inherited one.
+ * an explicit (`source: "explicit"`) request and warns for an inherited one,
+ * unless strict scope enforcement makes inherited violations hard errors.
  */
 export function resolveSubagentModelOverride(
 	requestedModel: string | boolean | undefined,
@@ -245,7 +246,7 @@ export function resolveEffectiveSubagentModel(
 }
 
 export interface BuildModelCandidatesOptions {
-	/** Fallback models are inherited agent config and warn, rather than error, when out of scope. */
+	/** Fallback models warn by default and throw when strict scope enforcement is enabled. */
 	scope?: ModelScopeConfig;
 	onWarn?: (violation: ModelScopeViolation) => void;
 }
@@ -265,9 +266,12 @@ export function buildModelCandidates(
 		if (!raw) continue;
 		const normalized = resolveModelCandidate(raw.trim(), availableModels, preferredProvider);
 		if (!normalized || seen.has(normalized)) continue;
-		if (index > 0 && options?.scope?.enforce) {
+		if ((index > 0 || options?.scope?.strict === true) && options?.scope?.enforce) {
 			const violation = checkModelScope(normalized, options.scope, "inherited");
-			if (violation) (options.onWarn ?? defaultScopeWarn)(violation);
+			if (violation) {
+				if (violation.severity === "error") throw new Error(violation.message);
+				(options.onWarn ?? defaultScopeWarn)(violation);
+			}
 		}
 		seen.add(normalized);
 		candidates.push(normalized);

package/src/runs/shared/model-scope.ts

@@ -6,7 +6,8 @@
  * where the model came from: an explicit caller-supplied model (`--model`,
  * tool-call `model`, or a TUI clarify pick) is a hard error, while a model
  * inherited from agent frontmatter / `defaultModel` / the parent session only
- * emits a warning so existing configurations keep working.
+ * emits a warning so existing configurations keep working. Optional strict
+ * enforcement makes inherited models hard errors too.
  *
  * The decision logic ({@link checkModelScope}) is a pure function of its
  * inputs so it can be unit-tested without touching the filesystem or config.
@@ -16,6 +17,8 @@ import { splitKnownThinkingSuffix } from "../../shared/model-info.ts";
 
 export interface ModelScopeConfig {
 	enforce?: boolean;
+	/** Reject inherited and fallback models outside the allowlist instead of warning. */
+	strict?: boolean;
 	/** Glob-style allow patterns (only `*` is special), matched against `provider/id`. */
 	allow?: string[];
 }
@@ -67,7 +70,7 @@ export function checkModelScope(
 	if (allow.some((pattern) => matchesScopePattern(model, pattern))) return undefined;
 
 	const baseModel = stripThinkingSuffix(model);
-	const severity: ModelScopeViolation["severity"] = source === "explicit" ? "error" : "warn";
+	const severity: ModelScopeViolation["severity"] = source === "explicit" || scope.strict === true ? "error" : "warn";
 	return {
 		model: baseModel,
 		severity,
@@ -102,6 +105,13 @@ export function parseModelScopeConfig(
 		config.enforce = input.enforce;
 	}
 
+	if ("strict" in input) {
+		if (typeof input.strict !== "boolean") {
+			throw new Error(`Subagent settings in '${meta.filePath}' have invalid 'modelScope.strict'; expected a boolean.`);
+		}
+		config.strict = input.strict;
+	}
+
 	if ("allow" in input) {
 		if (!Array.isArray(input.allow)) {
 			throw new Error(`Subagent settings in '${meta.filePath}' have invalid 'modelScope.allow'; expected an array of strings.`);

package/src/runs/shared/parallel-utils.ts

@@ -40,6 +40,7 @@ export interface RunnerSubagentStep {
 	outputMode?: "inline" | "file-only";
 	sessionFile?: string;
 	maxSubagentDepth?: number;
+	timeoutMs?: number;
 	waitToolEnabled?: boolean;
 	structuredOutput?: {
 		schema: import("../../shared/types.ts").JsonSchemaObject;

package/src/runs/shared/subagent-prompt-runtime.ts

@@ -31,6 +31,7 @@ const SUBAGENT_INHERIT_PROJECT_CONTEXT_ENV = "PI_SUBAGENT_INHERIT_PROJECT_CONTEX
 const SUBAGENT_INHERIT_SKILLS_ENV = "PI_SUBAGENT_INHERIT_SKILLS";
 export const SUBAGENT_INTERCOM_SESSION_NAME_ENV = "PI_SUBAGENT_INTERCOM_SESSION_NAME";
 const STEERING_LEGACY_SETTLE_FALLBACK_MS = 1000;
+const STEERING_SAFETY_POLL_INTERVAL_MS = 5000;
 
 const STRUCTURED_OUTPUT_INSTRUCTIONS = [
 	"This subagent step has a strict structured output contract.",
@@ -331,7 +332,13 @@ function registerToolBudget(pi: ExtensionAPI, budget: ResolvedToolBudget | undef
 
 export function registerSteeringInbox(
 	pi: ExtensionAPI,
-	deps: { watch?: typeof fs.watch; nativeRealpath?: (filePath: string) => string; legacySettleFallbackMs?: number } = {},
+	deps: {
+		watch?: typeof fs.watch;
+		nativeRealpath?: (filePath: string) => string;
+		legacySettleFallbackMs?: number;
+		safetyPollIntervalMs?: number;
+		timers?: Pick<typeof globalThis, "setInterval" | "clearInterval">;
+	} = {},
 ): void {
 	const steerInbox = process.env[SUBAGENT_STEER_INBOX_ENV]?.trim();
 	if (!steerInbox) return;
@@ -350,6 +357,7 @@ export function registerSteeringInbox(
 	let canSteer = typeof sendUserMessage === "function";
 	let watcher: fs.FSWatcher | undefined;
 	let interval: NodeJS.Timeout | undefined;
+	let safetyInterval: NodeJS.Timeout | undefined;
 	let settleFallback: NodeJS.Timeout | undefined;
 	const legacySettleFallbackMs = deps.legacySettleFallbackMs ?? STEERING_LEGACY_SETTLE_FALLBACK_MS;
 	const acknowledge = (request: SteerRequest, state: "delivered" | "queued" | "failed", message: string, deliveryStatus?: SteerDeliveryStatus): void => {
@@ -431,14 +439,24 @@ export function registerSteeringInbox(
 			return;
 		}
 		started = true;
+		const startPolling = (): void => {
+			if (interval || disposed) return;
+			interval = (deps.timers?.setInterval ?? setInterval)(flush, 250) as NodeJS.Timeout;
+			interval.unref?.();
+		};
+		const startSafetyPolling = (): void => {
+			if (safetyInterval || disposed) return;
+			safetyInterval = (deps.timers?.setInterval ?? setInterval)(flush, deps.safetyPollIntervalMs ?? STEERING_SAFETY_POLL_INTERVAL_MS) as NodeJS.Timeout;
+			safetyInterval.unref?.();
+		};
 		try {
 			watcher = (deps.watch ?? fs.watch)(resolveWatchPath(steerInbox, deps.nativeRealpath), () => flush());
-			watcher.on("error", () => {});
+			watcher.on("error", startPolling);
+			startSafetyPolling();
 		} catch {
 			watcher = undefined;
+			startPolling();
 		}
-		interval = setInterval(flush, 250);
-		interval.unref?.();
 	};
 	const activate = (): undefined => {
 		start();
@@ -534,7 +552,8 @@ export function registerSteeringInbox(
 		disposed = true;
 		clearSettleFallback();
 		try { watcher?.close(); } catch {}
-		if (interval) clearInterval(interval);
+		if (interval) (deps.timers?.clearInterval ?? clearInterval)(interval);
+		if (safetyInterval) (deps.timers?.clearInterval ?? clearInterval)(safetyInterval);
 	});
 }
 

package/src/runs/shared/worktree.ts

@@ -3,6 +3,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { resolveAuthorityDecision, type AuthorityPolicyConfig } from "../../policy/authority.ts";
+import { PROJECT_SUBAGENTS_RELATIVE_DIR } from "../../shared/artifacts.ts";
 
 export interface WorktreeSetup {
 	cwd: string;
@@ -135,9 +136,9 @@ function resolveRepoState(cwd: string): RepoState {
 	const cwdRelative = resolveRepoCwdRelative(cwd);
 	const toplevel = runGitChecked(cwd, ["rev-parse", "--show-toplevel"]).trim();
 
-	// pi-subagents writes durable runtime state under .pi-subagents/ by default;
+	// pi-subagents writes durable runtime state under .pi/subagents/ by default;
 	// that state must not make managed isolation unusable for later runs.
-	const status = runGitChecked(toplevel, ["status", "--porcelain", "--", ":!.pi-subagents"]);
+	const status = runGitChecked(toplevel, ["status", "--porcelain", "--", `:!${PROJECT_SUBAGENTS_RELATIVE_DIR}`]);
 	if (status.trim().length > 0) {
 		throw new Error("worktree isolation requires a clean git working tree. Commit or stash changes first.");
 	}

package/src/shared/artifacts.ts

@@ -3,19 +3,19 @@ import * as path from "node:path";
 import { CHAIN_RUNS_DIR, TEMP_ARTIFACTS_DIR, type ArtifactPaths, type ArtifactDirPreference } from "./types.ts";
 import { getAgentDir } from "./utils.ts";
 const CLEANUP_MARKER_FILE = ".last-cleanup";
-const PROJECT_ARTIFACT_ROOT = ".pi-subagents";
+export const PROJECT_SUBAGENTS_RELATIVE_DIR = ".pi/subagents";
 
 const PROJECT_ARTIFACT_PATHS = [
-	`${PROJECT_ARTIFACT_ROOT}/artifacts/output.md`,
-	`${PROJECT_ARTIFACT_ROOT}/artifacts/run_worker_input.md`,
-	`${PROJECT_ARTIFACT_ROOT}/artifacts/run_worker_output.md`,
-	`${PROJECT_ARTIFACT_ROOT}/artifacts/run_worker.jsonl`,
-	`${PROJECT_ARTIFACT_ROOT}/artifacts/run_worker_transcript.jsonl`,
-	`${PROJECT_ARTIFACT_ROOT}/artifacts/run_worker_meta.json`,
-	`${PROJECT_ARTIFACT_ROOT}/artifacts/progress/run/progress.md`,
-	`${PROJECT_ARTIFACT_ROOT}/artifacts/outputs/output.md`,
-	`${PROJECT_ARTIFACT_ROOT}/artifacts/outputs/run/output.md`,
-	`${PROJECT_ARTIFACT_ROOT}/chain-runs/run.json`,
+	`${PROJECT_SUBAGENTS_RELATIVE_DIR}/artifacts/output.md`,
+	`${PROJECT_SUBAGENTS_RELATIVE_DIR}/artifacts/run_worker_input.md`,
+	`${PROJECT_SUBAGENTS_RELATIVE_DIR}/artifacts/run_worker_output.md`,
+	`${PROJECT_SUBAGENTS_RELATIVE_DIR}/artifacts/run_worker.jsonl`,
+	`${PROJECT_SUBAGENTS_RELATIVE_DIR}/artifacts/run_worker_transcript.jsonl`,
+	`${PROJECT_SUBAGENTS_RELATIVE_DIR}/artifacts/run_worker_meta.json`,
+	`${PROJECT_SUBAGENTS_RELATIVE_DIR}/artifacts/progress/run/progress.md`,
+	`${PROJECT_SUBAGENTS_RELATIVE_DIR}/artifacts/outputs/output.md`,
+	`${PROJECT_SUBAGENTS_RELATIVE_DIR}/artifacts/outputs/run/output.md`,
+	`${PROJECT_SUBAGENTS_RELATIVE_DIR}/chain-runs/run.json`,
 ];
 
 function globMatchesPath(pattern: string, filePath: string): boolean {
@@ -59,7 +59,7 @@ function normalizePattern(pattern: string): string {
 
 function patternMatchesArtifactPath(pattern: string, artifactPath: string): boolean {
 	const normalized = normalizePattern(pattern);
-	return normalized === PROJECT_ARTIFACT_ROOT
+	return normalized === PROJECT_SUBAGENTS_RELATIVE_DIR
 		|| normalized === "*"
 		|| artifactPath.startsWith(`${normalized}/`)
 		|| globMatchesPath(normalized, artifactPath);
@@ -127,11 +127,11 @@ export function getProjectArtifactPackagingWarning(cwd: string): string | undefi
 	const ignorePath = fs.existsSync(npmIgnorePath) ? npmIgnorePath : path.join(cwd, ".gitignore");
 	if (filesIncludeArtifacts === undefined && ignoreFileExcludesProjectArtifacts(ignorePath)) return undefined;
 
-	return "Project-scoped subagent artifacts can be included when this package is published. Add '.pi-subagents/' to .npmignore, restrict package.json files, or set artifactDir to 'session' or 'temp'.";
+	return "Project-scoped subagent artifacts can be included when this package is published. Add '.pi/subagents/' to .npmignore, restrict package.json files, or set artifactDir to 'session' or 'temp'.";
 }
 
 export function getProjectSubagentsDir(cwd: string): string {
-	return path.join(cwd, PROJECT_ARTIFACT_ROOT);
+	return path.join(cwd, PROJECT_SUBAGENTS_RELATIVE_DIR);
 }
 
 export function getProjectArtifactsDir(cwd: string): string {
@@ -228,7 +228,7 @@ export function appendJsonl(filePath: string, line: string): void {
 }
 
 export function cleanupOldArtifacts(dir: string, maxAgeDays: number): void {
-	if (!fs.existsSync(dir)) return;
+	if (maxAgeDays <= 0 || !fs.existsSync(dir)) return;
 
 	const markerPath = path.join(dir, CLEANUP_MARKER_FILE);
 	const now = Date.now();

package/src/shared/display-text.ts

@@ -0,0 +1,100 @@
+function codePointWidth(codePoint: number): 1 | 2 {
+	return codePoint > 0xffff ? 2 : 1;
+}
+
+function isWhitespaceOrControl(codePoint: number): boolean {
+	if (codePoint <= 0x20 || (codePoint >= 0x7f && codePoint <= 0x9f)) return true;
+	if (codePoint >= 0xd800 && codePoint <= 0xdfff) return true;
+	return String.fromCodePoint(codePoint).trim().length === 0;
+}
+
+function consumeControlString(value: string, index: number, osc: boolean): number {
+	while (index < value.length) {
+		const codePoint = value.codePointAt(index)!;
+		const width = codePointWidth(codePoint);
+		if (osc && codePoint === 0x07) return index + width;
+		if (codePoint === 0x9c) return index + width;
+		if (codePoint === 0x1b && value.charCodeAt(index + 1) === 0x5c) return index + 2;
+		index += width;
+	}
+	return value.length;
+}
+
+function consumeCsi(value: string, index: number): number {
+	while (index < value.length) {
+		const codePoint = value.codePointAt(index)!;
+		const width = codePointWidth(codePoint);
+		if (codePoint >= 0x40 && codePoint <= 0x7e) return index + width;
+		index += width;
+	}
+	return value.length;
+}
+
+export function sanitizeDisplayText(value: string): string {
+	const output: string[] = [];
+	let pendingSpace = false;
+
+	const appendSpace = (): void => {
+		if (output.length > 0) pendingSpace = true;
+	};
+	const appendText = (text: string): void => {
+		if (pendingSpace) output.push(" ");
+		output.push(text);
+		pendingSpace = false;
+	};
+
+	for (let index = 0; index < value.length;) {
+		const codePoint = value.codePointAt(index)!;
+		const width = codePointWidth(codePoint);
+
+		if (codePoint === 0x1b) {
+			const next = value.charCodeAt(index + 1);
+			appendSpace();
+			if (next === 0x5b) {
+				index = consumeCsi(value, index + 2);
+				continue;
+			}
+			if (next === 0x5d || next === 0x50 || next === 0x58 || next === 0x5e || next === 0x5f) {
+				index = consumeControlString(value, index + 2, next === 0x5d);
+				continue;
+			}
+			index += next ? 2 : 1;
+			continue;
+		}
+
+		if (codePoint === 0x9b) {
+			appendSpace();
+			index = consumeCsi(value, index + width);
+			continue;
+		}
+		if (codePoint === 0x90 || codePoint === 0x98 || codePoint === 0x9d || codePoint === 0x9e || codePoint === 0x9f) {
+			appendSpace();
+			index = consumeControlString(value, index + width, codePoint === 0x9d);
+			continue;
+		}
+
+		if (isWhitespaceOrControl(codePoint)) appendSpace();
+		else appendText(String.fromCodePoint(codePoint));
+		index += width;
+	}
+
+	return output.join("");
+}
+
+export function truncateDisplayText(value: string, maxLength: number): string {
+	if (maxLength <= 0) return "";
+	if (value.length <= maxLength) return value;
+	let output = "";
+	for (const char of value) {
+		if (output.length + char.length > maxLength) break;
+		output += char;
+	}
+	return output;
+}
+
+export function previewDisplayText(value: string, maxLength: number): string {
+	const normalized = sanitizeDisplayText(value);
+	if (normalized.length <= maxLength) return normalized;
+	if (maxLength <= 3) return truncateDisplayText(normalized, maxLength);
+	return `${truncateDisplayText(normalized, maxLength - 3)}...`;
+}

package/src/shared/file-coalescer.ts

@@ -5,6 +5,7 @@ interface TimerApi {
 
 interface FileCoalescer {
 	schedule(file: string, delayMs?: number): boolean;
+	flush(file: string): boolean;
 	clear(): void;
 }
 
@@ -30,6 +31,14 @@ export function createFileCoalescer(
 			pending.set(file, timer);
 			return true;
 		},
+		flush(file: string): boolean {
+			const timer = pending.get(file);
+			if (timer === undefined) return false;
+			timerApi.clearTimeout(timer);
+			pending.delete(file);
+			handler(file);
+			return true;
+		},
 		clear(): void {
 			for (const timer of pending.values()) {
 				timerApi.clearTimeout(timer);

package/src/shared/formatters.ts

@@ -7,6 +7,7 @@ import * as path from "node:path";
 import type { Usage, SingleResult } from "./types.ts";
 import type { ChainStep } from "./settings.ts";
 import { isDynamicParallelStep, isParallelStep } from "./settings.ts";
+import { previewDisplayText, sanitizeDisplayText } from "./display-text.ts";
 import { splitKnownThinkingSuffix, THINKING_LEVELS } from "./model-info.ts";
 
 /**
@@ -100,8 +101,7 @@ export function formatToolCall(name: string, args: Record<string, unknown>, expa
 	switch (name) {
 		case "bash": {
 			const command = typeof args.command === "string" ? args.command : "";
-			const maxLength = expanded ? 240 : 60;
-			return `$ ${command.slice(0, maxLength)}${command.length > maxLength ? "..." : ""}`;
+			return `$ ${previewDisplayText(command, expanded ? 240 : 60)}`;
 		}
 		case "read":
 		case "write":
@@ -111,12 +111,10 @@ export function formatToolCall(name: string, args: Record<string, unknown>, expa
 				: typeof args.file_path === "string"
 					? args.file_path
 					: "";
-			return `${name} ${shortenPath(target)}`;
+			return `${name} ${sanitizeDisplayText(shortenPath(target))}`;
 		}
 		default: {
-			const s = JSON.stringify(args);
-			const maxLength = expanded ? 160 : 40;
-			return `${name} ${s.slice(0, maxLength)}${s.length > maxLength ? "..." : ""}`;
+			return `${name} ${previewDisplayText(JSON.stringify(args), expanded ? 160 : 40)}`;
 		}
 	}
 }

package/src/shared/settings.ts

@@ -353,6 +353,18 @@ export function resolveChainPath(filePath: string, chainDir: string): string {
 	return path.isAbsolute(expanded) ? expanded : path.join(chainDir, expanded);
 }
 
+export function resolveExistingReadInstructionPaths(reads: readonly string[], instructionCwd: string, existenceCwd = instructionCwd): string[] {
+	return reads.flatMap((filePath) => {
+		const instructionPath = resolveChainPath(filePath, instructionCwd);
+		const existencePath = resolveChainPath(filePath, existenceCwd);
+		return fs.existsSync(existencePath) ? [instructionPath] : [];
+	});
+}
+
+export function resolveExistingReadPaths(reads: readonly string[], cwd: string): string[] {
+	return resolveExistingReadInstructionPaths(reads, cwd);
+}
+
 /**
  * Build chain instructions from resolved behavior.
  * These are appended to the task to tell the agent what to read/write.
@@ -367,14 +379,15 @@ export function buildChainInstructions(
 	chainDir: string,
 	isFirstProgressAgent: boolean,
 	previousSummary?: string,
+	readExistenceDir = chainDir,
 ): { prefix: string; suffix: string } {
 	const prefixParts: string[] = [];
 	const suffixParts: string[] = [];
 
 	// READS - prepend to override any hardcoded filenames in task text
 	if (behavior.reads && behavior.reads.length > 0) {
-		const files = behavior.reads.map((f) => resolveChainPath(f, chainDir));
-		prefixParts.push(`[Read from: ${files.join(", ")}]`);
+		const files = resolveExistingReadInstructionPaths(behavior.reads, chainDir, readExistenceDir);
+		if (files.length > 0) prefixParts.push(`[Read from: ${files.join(", ")}]`);
 	}
 
 	// OUTPUT - prepend so agent knows where to write