pi-subagents 0.69.0 → 0.70.0

package/src/runs/shared/lane-metadata.ts

@@ -1,126 +0,0 @@
-import type { AsyncStatus, ManagedWorktreeProvider, WorktreeNaming, WorkflowLaneMetadata, WorkflowLaneMode } from "../../shared/types.ts";
-
-export const WORKFLOW_LANE_KEY_MAX_BYTES = 128;
-export const WORKFLOW_LANE_SOURCE_REF_MAX_BYTES = 128;
-export const WORKFLOW_LANE_CLAIM_MAX_BYTES = 160;
-export const WORKFLOW_LANE_CLAIMS_MAX = 20;
-export const WORKFLOW_LANE_OUTPUT_PATH_MAX_BYTES = 256;
-export const WORKFLOW_LANE_OUTPUT_PATHS_MAX = 10;
-export const WORKTREE_STATUS_PATH_MAX_BYTES = 4096;
-export const WORKTREE_STATUS_BRANCH_MAX_BYTES = 256;
-export const WORKTREE_STATUS_NAMING_LABEL_MAX_BYTES = 256;
-
-const WORKFLOW_LANE_KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
-const WORKFLOW_LANE_MODES = new Set<WorkflowLaneMode>(["mutation", "review", "scout", "gate"]);
-
-function byteLength(value: string): number {
-	return Buffer.byteLength(value, "utf8");
-}
-
-function boundedNonEmptyString(value: unknown, label: string, maxBytes: number): string {
-	if (typeof value !== "string" || !value.trim()) throw new Error(`${label} must be a non-empty string.`);
-	const normalized = value.trim();
-	if (byteLength(normalized) > maxBytes) throw new Error(`${label} exceeds ${maxBytes} UTF-8 bytes.`);
-	if ([...normalized].some((character) => character === "\n" || character === "\r" || character === "\u0000")) throw new Error(`${label} must not contain newlines or NUL bytes.`);
-	return normalized;
-}
-
-function assertPlainObject(value: unknown, label: string): asserts value is Record<string, unknown> {
-	if (!value || typeof value !== "object" || Array.isArray(value) || (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)) {
-		throw new Error(`${label} must be a plain JSON object.`);
-	}
-}
-
-function assertKnownFields(value: Record<string, unknown>, fields: readonly string[], label: string): void {
-	const unknown = Object.keys(value).filter((field) => !fields.includes(field));
-	if (unknown.length > 0) throw new Error(`${label} has unsupported fields: ${unknown.join(", ")}.`);
-}
-
-function boundedStringArray(value: unknown, label: string, maxItems: number, maxBytes: number): string[] {
-	if (!Array.isArray(value)) throw new Error(`${label} must be an array.`);
-	if (value.length > maxItems) throw new Error(`${label} supports at most ${maxItems} entries.`);
-	return value.map((entry, index) => {
-		if (!Object.hasOwn(value, index)) throw new Error(`${label} must not contain sparse entries.`);
-		return boundedNonEmptyString(entry, `${label}[${index}]`, maxBytes);
-	});
-}
-
-/** Normalize and validate launch-declared lane metadata. */
-export function normalizeWorkflowLaneMetadata(value: unknown, label = "lane"): WorkflowLaneMetadata | undefined {
-	if (value === undefined) return undefined;
-	assertPlainObject(value, label);
-	assertKnownFields(value, ["version", "key", "mode", "sourceRef", "claims", "outputPaths"], label);
-	if (value.version !== 1) throw new Error(`${label}.version must be 1.`);
-	const key = boundedNonEmptyString(value.key, `${label}.key`, WORKFLOW_LANE_KEY_MAX_BYTES);
-	if (!WORKFLOW_LANE_KEY_PATTERN.test(key)) throw new Error(`${label}.key is invalid.`);
-	const mode = value.mode;
-	if (mode !== undefined && (typeof mode !== "string" || !WORKFLOW_LANE_MODES.has(mode as WorkflowLaneMode))) throw new Error(`${label}.mode is invalid.`);
-	const sourceRef = value.sourceRef === undefined ? undefined : boundedNonEmptyString(value.sourceRef, `${label}.sourceRef`, WORKFLOW_LANE_SOURCE_REF_MAX_BYTES);
-	const claims = value.claims === undefined ? undefined : boundedStringArray(value.claims, `${label}.claims`, WORKFLOW_LANE_CLAIMS_MAX, WORKFLOW_LANE_CLAIM_MAX_BYTES);
-	const outputPaths = value.outputPaths === undefined ? undefined : boundedStringArray(value.outputPaths, `${label}.outputPaths`, WORKFLOW_LANE_OUTPUT_PATHS_MAX, WORKFLOW_LANE_OUTPUT_PATH_MAX_BYTES);
-	return {
-		version: 1,
-		key,
-		...(mode !== undefined ? { mode: mode as WorkflowLaneMode } : {}),
-		...(sourceRef !== undefined ? { sourceRef } : {}),
-		...(claims !== undefined ? { claims } : {}),
-		...(outputPaths !== undefined ? { outputPaths } : {}),
-	};
-}
-
-export function assertWorkflowLaneKey(lane: WorkflowLaneMetadata | undefined, workflowKey: string | undefined, label = "lane"): void {
-	if (!lane || workflowKey === undefined) return;
-	if (lane.key !== workflowKey) throw new Error(`${label}.key '${lane.key}' does not match workflow key '${workflowKey}'.`);
-}
-
-export interface WorktreeStatusReference {
-	worktreePath: string;
-	branch: string;
-	provider?: ManagedWorktreeProvider;
-	naming?: WorktreeNaming;
-}
-
-function normalizeWorktreeNaming(value: unknown, label: string): WorktreeNaming {
-	assertPlainObject(value, label);
-	assertKnownFields(value, ["requestedBranch", "branchPrefix", "label", "sanitizedPathComponent", "collision", "collisionSuffix"], label);
-	const collision = value.collision;
-	if (collision !== undefined && collision !== "branch" && collision !== "path" && collision !== "both") throw new Error(`${label}.collision is invalid.`);
-	return {
-		requestedBranch: boundedNonEmptyString(value.requestedBranch, `${label}.requestedBranch`, WORKTREE_STATUS_BRANCH_MAX_BYTES),
-		branchPrefix: boundedNonEmptyString(value.branchPrefix, `${label}.branchPrefix`, WORKTREE_STATUS_BRANCH_MAX_BYTES),
-		label: boundedNonEmptyString(value.label, `${label}.label`, WORKTREE_STATUS_NAMING_LABEL_MAX_BYTES),
-		sanitizedPathComponent: boundedNonEmptyString(value.sanitizedPathComponent, `${label}.sanitizedPathComponent`, WORKTREE_STATUS_NAMING_LABEL_MAX_BYTES),
-		...(collision !== undefined ? { collision } : {}),
-		...(value.collisionSuffix !== undefined ? { collisionSuffix: boundedNonEmptyString(value.collisionSuffix, `${label}.collisionSuffix`, WORKTREE_STATUS_NAMING_LABEL_MAX_BYTES) } : {}),
-	};
-}
-
-/** Validate the display-only worktree fields copied into status.json. */
-export function normalizeWorktreeStatusReference(value: unknown, label = "worktree status reference"): WorktreeStatusReference | undefined {
-	if (value === undefined) return undefined;
-	assertPlainObject(value, label);
-	assertKnownFields(value, ["worktreePath", "branch", "provider", "naming"], label);
-	if (value.provider !== undefined && value.provider !== "native" && value.provider !== "worktrunk") throw new Error(`${label}.provider is invalid.`);
-	return {
-		worktreePath: boundedNonEmptyString(value.worktreePath, `${label}.worktreePath`, WORKTREE_STATUS_PATH_MAX_BYTES),
-		branch: boundedNonEmptyString(value.branch, `${label}.branch`, WORKTREE_STATUS_BRANCH_MAX_BYTES),
-		...(value.provider !== undefined ? { provider: value.provider as ManagedWorktreeProvider } : {}),
-		...(value.naming !== undefined ? { naming: normalizeWorktreeNaming(value.naming, `${label}.naming`) } : {}),
-	};
-}
-
-/** Validate only the additive lane/worktree fields of a persisted async status. */
-export function validateAsyncStatusLaneMetadata(status: Pick<AsyncStatus, "runId" | "workflowKey" | "lane" | "steps">, label = "async status"): void {
-	const lane = normalizeWorkflowLaneMetadata(status.lane, `${label}.lane`);
-	assertWorkflowLaneKey(lane, status.workflowKey, `${label}.lane`);
-	if (lane) status.lane = lane;
-	for (const [index, step] of (status.steps ?? []).entries()) {
-		const stepLane = normalizeWorkflowLaneMetadata(step.lane, `${label}.steps[${index}].lane`);
-		assertWorkflowLaneKey(stepLane, step.workflowKey, `${label}.steps[${index}].lane`);
-		if (stepLane) step.lane = stepLane;
-		const hasPath = step.worktreePath !== undefined;
-		const hasBranch = step.branch !== undefined;
-		if (hasPath !== hasBranch) throw new Error(`${label}.steps[${index}] must include both worktreePath and branch.`);
-		if (hasPath) normalizeWorktreeStatusReference({ worktreePath: step.worktreePath, branch: step.branch, ...(step.provider ? { provider: step.provider } : {}), ...(step.naming ? { naming: step.naming } : {}) }, `${label}.steps[${index}]`);
-	}
-}

package/src/runs/shared/launch-cwd.ts

@@ -1,16 +0,0 @@
-import * as fs from "node:fs";
-
-export function preflightLaunchCwd(requestedCwd: string, effectiveCwd: string): string | undefined {
-	const resolution = requestedCwd === effectiveCwd ? "" : `\n(resolved from ${JSON.stringify(requestedCwd)})`;
-	try {
-		if (!fs.statSync(effectiveCwd).isDirectory()) {
-			return `Subagent launch aborted: cwd is not a directory: ${effectiveCwd}${resolution}`;
-		}
-	} catch (error) {
-		if ((error as NodeJS.ErrnoException).code === "ENOENT") {
-			return `Subagent launch aborted: cwd does not exist: ${effectiveCwd}${resolution}`;
-		}
-		return `Subagent launch aborted: cwd could not be accessed: ${effectiveCwd}${resolution}\n${error instanceof Error ? error.message : String(error)}`;
-	}
-	return undefined;
-}

package/src/runs/shared/llm-intent-arbiter.ts

@@ -1,321 +0,0 @@
-import { createHash } from "node:crypto";
-import type { Agent, AgentTool, StreamFn } from "@earendil-works/pi-agent-core";
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { ProviderHeaders } from "@earendil-works/pi-ai";
-import { Type, type Static } from "typebox";
-import { agentStreamOptions } from "../../shared/agent-stream-options.ts";
-import { opencodeSessionHeaders } from "../../shared/opencode-session-headers.ts";
-
-/**
- * LLM intent arbiter for the completion mutation guard.
- *
- * The regex classifier (task-intent.ts) is deliberately narrow, so exotic
- * review wording can still look like an implementation task ("to fix this,
- * compare the outputs", verbs inside URLs or quoted text). When the guard is
- * about to hard-fail a run that made no edits, this arbiter asks a model
- * whether the task actually instructed file changes. It can only downgrade a
- * failure to a pass; every error, timeout, or non-read-only verdict keeps the
- * guard's original behavior.
- *
- * Enabled by default; set PI_SUBAGENTS_LLM_INTENT_ARBITER=0 to disable.
- */
-
-const COMPLETION_GUARD_ERROR_PREFIX =
-	"Subagent completed without making edits for an implementation task.";
-
-export type TaskMutationVerdict = "read-only" | "implementation" | "unavailable";
-
-export type TaskMutationArbiter = (task: string) => Promise<TaskMutationVerdict>;
-
-const DecisionParams = Type.Object(
-	{
-		classification: Type.String({ enum: ["read_only", "implementation"] }),
-		confidence: Type.String({
-			enum: ["low", "medium", "high"],
-			description: "Confidence in the classification. Only read_only with high confidence rescues a failed run.",
-		}),
-		reason: Type.String({ description: "One concise reason for this classification." }),
-	},
-	{ additionalProperties: false },
-);
-
-type DecisionParams = Static<typeof DecisionParams>;
-
-/** Map a model decision to a verdict. Only a high-confidence read_only rescues. */
-export function mapArbiterDecision(
-	decision: { classification?: string; confidence?: string } | undefined,
-): TaskMutationVerdict {
-	if (!decision) return "unavailable";
-	if (decision.classification === "read_only" && decision.confidence === "high") return "read-only";
-	return "implementation";
-}
-
-interface ArbiterRuntime {
-	model: NonNullable<RegistryModel>;
-	/** Explicit override; it always wins over a registered provider stream. */
-	explicitStreamFn?: StreamFn;
-	/** Registered provider stream, usable only when its api matches the model. */
-	registeredStreamFn?: StreamFn;
-	registeredApi?: string;
-	/** Session id for OpenCode session-routing headers, when the caller has one. */
-	sessionId?: string;
-	timeoutMs: number;
-}
-
-interface ArbiterAuth {
-	apiKey?: string;
-	headers?: ProviderHeaders;
-	env?: Record<string, string>;
-}
-
-export interface TaskMutationArbiterOptions {
-	/** Explicit "provider/id" model override (tests, config). */
-	model?: string;
-	/** Injectable stream function (tests). */
-	streamFn?: StreamFn;
-	timeoutMs?: number;
-}
-
-const DEFAULT_ARBITER_TIMEOUT_MS = 10_000;
-
-type RegistryModel = ReturnType<NonNullable<ExtensionContext["modelRegistry"]["find"]>>;
-/** Model services the arbiter needs, plus the caller's session id for OpenCode session-routing headers. */
-export type ArbiterModelContext = Pick<ExtensionContext, "model" | "modelRegistry"> & {
-	/** Session id the headers attach to (the child's, captured by detached runners; the parent's, passed by foreground callers). */
-	sessionId?: string;
-};
-
-function resolveArbiterModel(
-	ctx: ArbiterModelContext,
-	options?: TaskMutationArbiterOptions,
-): NonNullable<RegistryModel> | null {
-	const registry = ctx.modelRegistry as {
-		find?: (provider: string, modelId: string) => RegistryModel | undefined;
-		getAvailable?: () => Array<{ provider?: string; id?: string }>;
-	};
-	const explicit = options?.model?.trim();
-	if (explicit) {
-		const [provider, id] = explicit.split("/");
-		if (provider && id) return registry.find?.(provider, id) ?? null;
-		return null;
-	}
-	if (ctx.model) return ctx.model as NonNullable<RegistryModel>;
-	const first = registry.getAvailable?.()[0];
-	if (first?.provider && first.id) return registry.find?.(first.provider, first.id) ?? null;
-	return null;
-}
-
-function resolveArbiterRuntime(
-	ctx: ArbiterModelContext,
-	options?: TaskMutationArbiterOptions,
-): ArbiterRuntime | null {
-	const model = resolveArbiterModel(ctx, options);
-	if (!model?.provider || !model.id) return null;
-	const registry = ctx.modelRegistry as {
-		getRegisteredProviderConfig?: (provider: string) => { api?: string; streamSimple?: StreamFn } | undefined;
-	};
-	const registered = registry.getRegisteredProviderConfig?.(model.provider);
-	return {
-		model,
-		explicitStreamFn: options?.streamFn,
-		registeredStreamFn: registered?.streamSimple,
-		registeredApi: registered?.api,
-		sessionId: ctx.sessionId,
-		timeoutMs: options?.timeoutMs ?? DEFAULT_ARBITER_TIMEOUT_MS,
-	};
-}
-
-async function resolveArbiterAuth(
-	ctx: ArbiterModelContext,
-	model: RegistryModel,
-): Promise<ArbiterAuth | undefined> {
-	const registry = ctx.modelRegistry as {
-		getApiKeyAndHeaders?: (m: RegistryModel) => Promise<{
-			ok: boolean;
-			apiKey?: string;
-			headers?: ProviderHeaders;
-			env?: Record<string, string>;
-			error?: string;
-		}>;
-	};
-	// Call as a METHOD on the registry: the host ModelRegistry implementation
-	// is a class whose method reads instance state (this.runtime), so a
-	// detached call silently fails auth. Same shape as the watchdog.
-	if (!registry.getApiKeyAndHeaders) return {};
-	try {
-		const auth = await registry.getApiKeyAndHeaders(model);
-		if (auth.ok === false) return undefined;
-		return {
-			...(auth.apiKey ? { apiKey: auth.apiKey } : {}),
-			...(auth.headers ? { headers: auth.headers } : {}),
-			...(auth.env ? { env: auth.env } : {}),
-		};
-	} catch {
-		return undefined;
-	}
-}
-
-/** Build the effective stream function with resolved credentials wrapped in (watchdog pattern). */
-function authWrappedStreamFn(
-	base: StreamFn,
-	auth: ArbiterAuth,
-	sessionId: string | undefined,
-): StreamFn {
-	return (model, context, streamOptions) => base(model, context, {
-		...(streamOptions ?? {}),
-		...(auth.apiKey ? { apiKey: auth.apiKey } : {}),
-		...(auth.env || streamOptions?.env ? { env: { ...(auth.env ?? {}), ...(streamOptions?.env ?? {}) } } : {}),
-		headers: { ...opencodeSessionHeaders(model, sessionId), ...(streamOptions?.headers ?? {}), ...(auth.headers ?? {}) },
-	});
-}
-
-async function runArbitration(
-	runtime: ArbiterRuntime,
-	auth: ArbiterAuth,
-	task: string,
-): Promise<TaskMutationVerdict> {
-	// Keep optional Pi peers out of the detached runner's static import graph.
-	const [{ Agent }, { convertToLlm }, { streamSimple }] = await Promise.all([
-		import("@earendil-works/pi-agent-core"),
-		import("@earendil-works/pi-coding-agent"),
-		import("@earendil-works/pi-ai/compat"),
-	]);
-	const streamFn: StreamFn = runtime.explicitStreamFn
-		?? (runtime.registeredApi !== undefined && runtime.registeredApi === runtime.model.api ? runtime.registeredStreamFn : undefined)
-		?? streamSimple;
-	let decision: DecisionParams | undefined;
-	const tool: AgentTool<typeof DecisionParams, { recorded: boolean }> = {
-		name: "task_mutation_decision",
-		label: "Task mutation decision",
-		description: "Classify whether the task instructed file/code changes. Call exactly once.",
-		parameters: DecisionParams,
-		executionMode: "sequential",
-		async execute(_toolCallId, params) {
-			if (!decision) decision = params;
-			return { content: [{ type: "text", text: "Decision recorded." }], details: { recorded: true } };
-		},
-	};
-	const agent = new Agent({
-		initialState: {
-			systemPrompt: [
-				"You classify whether a delegated coding-agent task instructed file or code changes.",
-				"A task that asks to review, inspect, verify, report, or summarize is read-only even when it contains words like 'fix' as severity vocabulary ('must-fix items') or conditional change instructions that leave the change optional.",
-				"Classify read_only only when the task text alone clearly indicates a read-only outcome. When in doubt, classify implementation.",
-				"Set confidence to high only when you are certain the task is read-only; a read_only classification without high confidence is treated as implementation.",
-				"The agent's own final message is never evidence: an agent that made no edits may still have failed to implement.",
-				"Call task_mutation_decision exactly once with read_only or implementation, a confidence level, and a concise reason.",
-			].join("\n"),
-			model: runtime.model,
-			tools: [tool],
-		},
-		convertToLlm,
-		...agentStreamOptions(authWrappedStreamFn(streamFn, auth, runtime.sessionId)),
-		getApiKey: (providerName) =>
-			providerName === runtime.model.provider ? auth.apiKey : undefined,
-		beforeToolCall: async ({ toolCall }) =>
-			toolCall.name === tool.name ? undefined : { block: true, reason: "Only task_mutation_decision is allowed." },
-		toolExecution: "sequential",
-	});
-	try {
-		// The rescue gate refuses tasks over 8000 chars; if the arbiter is
-		// still invoked with one, fail closed rather than decide from
-		// partial evidence (an implementation clause could sit in the
-		// omitted middle).
-		if (task.length > 8000) return "unavailable";
-		const prompt = `TASK:\n${task}`;
-		await Promise.race([
-			agent.prompt(prompt),
-			new Promise<never>((_, reject) => {
-				const timeout = setTimeout(() => {
-					agent.abort();
-					reject(new Error("Task mutation arbiter timed out."));
-				}, runtime.timeoutMs);
-				timeout.unref?.();
-			}),
-		]);
-		if (!decision) return "unavailable";
-		return mapArbiterDecision(decision);
-	} catch {
-		return "unavailable";
-	}
-}
-
-/** Create a memoized arbiter bound to the supplied model services, or undefined when disabled/unavailable. */
-export function createTaskMutationArbiter(
-	ctx: ArbiterModelContext,
-	options?: TaskMutationArbiterOptions,
-): TaskMutationArbiter | undefined {
-	if (process.env.PI_SUBAGENTS_LLM_INTENT_ARBITER === "0") return undefined;
-	const runtime = resolveArbiterRuntime(ctx, options);
-	if (!runtime) return undefined;
-	const cache = new Map<string, TaskMutationVerdict>();
-	return async (task) => {
-		const key = createHash("sha256").update(task).digest("base64url");
-		const cached = cache.get(key);
-		if (cached) return cached;
-		const auth = await resolveArbiterAuth(ctx, runtime.model);
-		const verdict = auth ? await runArbitration(runtime, auth, task) : "unavailable";
-		if (cache.size > 200) cache.clear();
-		cache.set(key, verdict);
-		return verdict;
-	};
-}
-
-export function isCompletionGuardFailure(result: { error?: string }): boolean {
-	return result.error?.startsWith(COMPLETION_GUARD_ERROR_PREFIX) === true;
-}
-
-export async function arbitrateCompletionGuardRescue(input: {
-	guardTriggered: boolean;
-	task: string;
-	arbiter?: TaskMutationArbiter;
-}): Promise<{ triggered: boolean; rescued: boolean }> {
-	if (!input.guardTriggered || !input.arbiter) {
-		return { triggered: input.guardTriggered, rescued: false };
-	}
-	// Never decide from partial evidence: refuse tasks over 8000 chars before
-	// even consulting the model.
-	if (input.task.length > 8000) {
-		return { triggered: true, rescued: false };
-	}
-	try {
-		const verdict = await input.arbiter(input.task);
-		if (verdict === "read-only") return { triggered: false, rescued: true };
-		return { triggered: true, rescued: false };
-	} catch {
-		return { triggered: true, rescued: false };
-	}
-}
-
-/**
- * When the completion guard hard-failed a run and the arbiter classifies the
- * task as read-only, clear the failure. Returns true when rescued. All other
- * verdicts and every failure mode keep the original guard behavior.
- *
- * Classification uses the task text only: the agent's own final message is
- * never evidence, so a child that failed to implement cannot talk its way
- * out of the guard by claiming the work was read-only.
- */
-export async function maybeRescueCompletionGuardFailure(
-	result: { exitCode?: number; error?: string },
-	task: string,
-	arbiter: TaskMutationArbiter | undefined,
-): Promise<boolean> {
-	if (!arbiter || !isCompletionGuardFailure(result)) return false;
-	const verdict = await arbitrateWithGuard(arbiter, task);
-	if (verdict !== "read-only") return false;
-	result.exitCode = 0;
-	delete result.error;
-	return true;
-}
-
-async function arbitrateWithGuard(
-	arbiter: TaskMutationArbiter,
-	task: string,
-): Promise<TaskMutationVerdict> {
-	try {
-		return await arbiter(task);
-	} catch {
-		return "unavailable";
-	}
-}

package/src/runs/shared/long-running-guard.ts

@@ -1,221 +0,0 @@
-import type { ResolvedControlConfig } from "../../shared/types.ts";
-
-interface LongRunningNoticeMetrics {
-	startedAt: number;
-	now: number;
-	turns: number;
-	tokens: number;
-}
-
-type LongRunningTriggerReason = "time_threshold" | "turn_threshold" | "token_threshold";
-
-interface FailedMutatingAttempt {
-	tool: string;
-	path?: string;
-	error: string;
-	ts: number;
-}
-
-interface MutatingFailureState {
-	consecutiveFailures: number;
-	lastFailureAt?: number;
-	recentFailures: FailedMutatingAttempt[];
-	lastMutatingPath?: string;
-	repeatedPathFailures: number;
-}
-
-const MUTATING_BASH_PATTERNS = [
-	/(^|[;&|()\s])rm\s+/,
-	/(^|[;&|()\s])mv\s+/,
-	/(^|[;&|()\s])cp\s+/,
-	/(^|[;&|()\s])mkdir\s+/,
-	/(^|[;&|()\s])touch\s+/,
-	/(^|[;&|()\s])git\s+apply\b/,
-	/(^|[;&|()\s])patch\s+/,
-	/(^|[;&|()\s])sed\s+[^\n;&|]*\s-i\b/,
-	/(^|[;&|()\s])perl\s+[^\n;&|]*\s-pi\b/,
-	/(^|[;&|()]|\n)\s*tee\s+[^|&;]+/,
-	/\b(writeFile|writeFileSync|appendFile|appendFileSync)\b/,
-	/\bwrite_text\s*\(/,
-	/\bopen\s*\([^)]*,\s*["'][wa]/,
-];
-
-const MUTATING_FAILURE_HINTS = [
-	"failed",
-	"error",
-	"no exact match",
-	"did not match",
-	"malformed",
-	"rejected",
-	"unable",
-	"cannot",
-	"could not",
-];
-
-export function resolveCurrentPath(toolName: string | undefined, args: Record<string, unknown> | undefined): string | undefined {
-	if (!toolName || !args) return undefined;
-	const direct = ["path", "file", "filename", "target", "cwd"];
-	for (const key of direct) {
-		const value = args[key];
-		if (typeof value === "string" && value.trim()) return value.trim();
-	}
-	if (toolName === "bash") {
-		const command = typeof args.command === "string" ? args.command : undefined;
-		if (!command) return undefined;
-		const redirect = command.match(/(?:>|>>|tee\s+)(\S+)/);
-		if (redirect?.[1]) return redirect[1];
-	}
-	return undefined;
-}
-
-function hasUnquotedFileRedirection(command: string): boolean {
-	let inSingle = false;
-	let inDouble = false;
-	for (let i = 0; i < command.length; i++) {
-		const char = command[i]!;
-		if (char === "'" && !inDouble) {
-			inSingle = !inSingle;
-			continue;
-		}
-		if (char === '"' && !inSingle) {
-			inDouble = !inDouble;
-			continue;
-		}
-		if (inSingle || inDouble) continue;
-		if (char !== ">") continue;
-		if (command[i - 1] === "-") continue;
-		const isDouble = command[i + 1] === ">";
-		let cursor = i + (isDouble ? 2 : 1);
-		while (cursor < command.length && /\s/.test(command[cursor]!)) cursor++;
-		if (cursor >= command.length) continue;
-		const targetStart = command[cursor]!;
-		if (targetStart === "&" || targetStart === "|" || targetStart === ";") continue;
-		if (targetStart === "(" || targetStart === ")") continue;
-		return true;
-	}
-	return false;
-}
-
-function unquotedShellText(command: string): string {
-	let inSingle = false;
-	let inDouble = false;
-	let escaped = false;
-	let result = "";
-	for (const char of command) {
-		if (escaped) {
-			result += inSingle || inDouble ? "_" : char;
-			escaped = false;
-			continue;
-		}
-		if (char === "\\" && !inSingle) {
-			escaped = true;
-			result += inDouble ? "_" : char;
-			continue;
-		}
-		if (char === "'" && !inDouble) {
-			inSingle = !inSingle;
-			continue;
-		}
-		if (char === '"' && !inSingle) {
-			inDouble = !inDouble;
-			continue;
-		}
-		result += inSingle || inDouble ? "_" : char;
-	}
-	return result;
-}
-
-function hasMutatingGitCommand(command: string): boolean {
-	const unquoted = unquotedShellText(command);
-	for (const segment of unquoted.split(/(?:&&|\|\||[;|()\n])/)) {
-		const trimmed = segment.trim();
-		if (!trimmed || /^(?:echo|printf)\b/.test(trimmed)) continue;
-		if (/^git\s+(?:(?:(?:-C|--git-dir|--work-tree)\s+\S+|(?:--git-dir|--work-tree)=\S+|--paginate)\s+)*(?:add|commit|push)\b/.test(trimmed)) return true;
-	}
-	return false;
-}
-
-export function isMutatingBashCommand(command: string): boolean {
-	return hasUnquotedFileRedirection(command)
-		|| hasMutatingGitCommand(command)
-		|| MUTATING_BASH_PATTERNS.some((pattern) => pattern.test(command));
-}
-
-export function isMutatingTool(toolName: string | undefined, args: Record<string, unknown> | undefined, mutationTools?: readonly string[]): boolean {
-	if (!toolName) return false;
-	if (mutationTools?.includes(toolName)) return true;
-	if (toolName === "edit" || toolName === "write") return true;
-	if (toolName === "cursor") {
-		const activityTitle = typeof args?.activityTitle === "string" ? args.activityTitle : "";
-		return /^Cursor (?:edit|write)\b/i.test(activityTitle);
-	}
-	if (toolName !== "bash") return false;
-	const command = typeof args?.command === "string" ? args.command : "";
-	if (!command.trim()) return false;
-	return isMutatingBashCommand(command);
-}
-
-export function didMutatingToolFail(text: string): boolean {
-	const lowered = text.toLowerCase();
-	return MUTATING_FAILURE_HINTS.some((hint) => lowered.includes(hint));
-}
-
-export function nextLongRunningTrigger(
-	config: ResolvedControlConfig,
-	metrics: LongRunningNoticeMetrics,
-): LongRunningTriggerReason | undefined {
-	if (metrics.now - metrics.startedAt >= config.activeNoticeAfterMs) return "time_threshold";
-	if (config.activeNoticeAfterTurns !== undefined && metrics.turns >= config.activeNoticeAfterTurns) return "turn_threshold";
-	if (config.activeNoticeAfterTokens !== undefined && metrics.tokens >= config.activeNoticeAfterTokens) return "token_threshold";
-	return undefined;
-}
-
-export function resetMutatingFailureState(state: MutatingFailureState): void {
-	state.consecutiveFailures = 0;
-	state.lastFailureAt = undefined;
-	state.recentFailures = [];
-	state.lastMutatingPath = undefined;
-	state.repeatedPathFailures = 0;
-}
-
-export function createMutatingFailureState(): MutatingFailureState {
-	return {
-		consecutiveFailures: 0,
-		recentFailures: [],
-		repeatedPathFailures: 0,
-	};
-}
-
-export function recordMutatingFailure(
-	state: MutatingFailureState,
-	input: FailedMutatingAttempt,
-	windowMs: number,
-): void {
-	if (state.lastFailureAt === undefined || input.ts - state.lastFailureAt > windowMs) {
-		state.consecutiveFailures = 0;
-		state.recentFailures = [];
-		state.repeatedPathFailures = 0;
-		state.lastMutatingPath = undefined;
-	}
-	state.lastFailureAt = input.ts;
-	state.consecutiveFailures += 1;
-	if (input.path && state.lastMutatingPath === input.path) {
-		state.repeatedPathFailures += 1;
-	} else if (input.path) {
-		state.lastMutatingPath = input.path;
-		state.repeatedPathFailures = 1;
-	}
-	state.recentFailures.push(input);
-	if (state.recentFailures.length > 3) state.recentFailures.shift();
-}
-
-export function shouldEscalateMutatingFailures(state: MutatingFailureState, threshold: number): boolean {
-	return state.consecutiveFailures >= threshold || state.repeatedPathFailures >= threshold;
-}
-
-export function summarizeRecentMutatingFailures(state: MutatingFailureState): string | undefined {
-	if (state.recentFailures.length === 0) return undefined;
-	return state.recentFailures
-		.map((entry) => `${entry.tool}${entry.path ? `(${entry.path})` : ""}: ${entry.error}`)
-		.join(" | ");
-}