@ferris1225/pi-subagents 4.3.8 → 4.3.10

package/src/delegation/agents.ts

@@ -52,8 +52,9 @@ const READ_ONLY_TOOL_NAMES = new Set([
 ]);
 export const SUBAGENT_TOOL_NAMES = [
 	"subagent",
-	"subagent_control",
+	"subagent_status",
 	"subagent_stop",
+	"subagent_risk",
 ] as const;
 const SUBAGENT_TOOL_NAME_SET = new Set<string>(SUBAGENT_TOOL_NAMES);
 

package/src/delegation/dispatch.ts

@@ -7,10 +7,11 @@
  */
 
 import { StringEnum, type Usage } from "@earendil-works/pi-ai";
+import { resolve } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
-import { discoverAgents } from "./agents.ts";
+import { discoverAgents, isWriteCapableAgent, type AgentConfig } from "./agents.ts";
 import { loadConfig } from "../configuration/config.ts";
 import { formatCompletionBlock, formatUsage } from "../presentation/format.ts";
 import {
@@ -22,10 +23,21 @@ import {
 	sumUsage,
 	type RunWaitReason,
 } from "../presentation/monitor.ts";
-import { formatPhaseLeaseReceipt } from "./prompt.ts";
+import { findDuplicateDispatch, formatParallelScopeAdmissionNote, formatPhaseLeaseReceipt } from "./prompt.ts";
+import {
+	findPhaseScopeOverlap,
+	findWriterLeaseScopeOverlap,
+	normalizePhaseId,
+	normalizePhaseScope,
+	PHASE_ID_MAX_LENGTH,
+	PHASE_ID_PATTERN_SOURCE,
+	type PhaseScope,
+	type PhaseScopeInput,
+} from "./phase-scope.ts";
 import type { SubagentRuntime, SubagentThread } from "../lifecycle/runtime.ts";
 import { createBackgroundDispatcher } from "../lifecycle/thread-lifecycle.ts";
 import {
+	getResultError,
 	getResultOutput,
 	isFailedResult,
 	type SingleResult,
@@ -53,6 +65,23 @@ const IsolationSchema = Type.Optional(
 	StringEnum(["shared", "worktree"] as const, { description: ISOLATION_DESCRIPTION }),
 );
 
+const PhaseIdSchema = Type.Optional(Type.String({
+	minLength: 1,
+	maxLength: PHASE_ID_MAX_LENGTH,
+	pattern: PHASE_ID_PATTERN_SOURCE,
+	description: "Stable logical phase id: 1-80 ASCII letters, numbers, or ._:- characters, starting with a letter or number. Reuse it when task wording changes so duplicate fresh dispatches are rejected.",
+}));
+const ScopeSchema = Type.Optional(Type.Object({
+	paths: Type.Optional(Type.Array(Type.String({
+		...NON_BLANK_TASK_OPTIONS,
+		description: "Exact file or directory write claim resolved from the caller-facing cwd; wildcard * and ? are rejected, while other punctuation is literal.",
+	}))),
+	symbols: Type.Optional(Type.Array(Type.Object({
+		path: Type.String({ ...NON_BLANK_TASK_OPTIONS, description: "Exact file path resolved from the caller-facing cwd." }),
+		name: Type.String({ ...NON_BLANK_TASK_OPTIONS, description: "Exact symbol name claimed for writing." }),
+	}))),
+}, { description: "Declarative write-conflict metadata for admission, not filesystem permissions or a sandbox. If present, at least one valid claim is required." }));
+
 const WaitSchema = Type.Optional(
 	Type.Boolean({
 		description:
@@ -69,6 +98,8 @@ const TaskItem = Type.Object({
 		...NON_BLANK_TASK_OPTIONS,
 		description: TASK_BRIEF_DESCRIPTION,
 	}),
+	phaseId: PhaseIdSchema,
+	scope: ScopeSchema,
 	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
 	isolation: IsolationSchema,
 });
@@ -78,6 +109,8 @@ const SubagentParams = Type.Object({
 	task: Type.Optional(
 		Type.String({ ...NON_BLANK_TASK_OPTIONS, description: `${TASK_BRIEF_DESCRIPTION} (single mode)` }),
 	),
+	phaseId: PhaseIdSchema,
+	scope: ScopeSchema,
 	tasks: Type.Optional(Type.Array(TaskItem, { description: "Independently justified, disjoint phases for parallel execution" })),
 	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process (single mode)" })),
 	isolation: IsolationSchema,
@@ -109,6 +142,91 @@ export function defaultIsolationMode(
 	return mode === "parallel" && writeCapable ? "worktree" : "shared";
 }
 
+interface PreparedDispatchTask {
+	index: number;
+	agent: string;
+	task: string;
+	cwd: string;
+	phaseId?: string;
+	scope?: PhaseScope;
+	isolation?: IsolationMode;
+	writeCapable: boolean;
+}
+
+function prepareDispatchTasks(
+	tasks: ReadonlyArray<{ agent: string; task: string; cwd?: string; phaseId?: string; scope?: PhaseScopeInput; isolation?: IsolationMode }>,
+	callerCwd: string,
+	agents: readonly AgentConfig[],
+): PreparedDispatchTask[] {
+	return tasks.map((item, index) => {
+		const cwd = resolve(callerCwd, item.cwd ?? ".");
+		const agent = agents.find((candidate) => candidate.name === item.agent);
+		return {
+			index,
+			agent: item.agent,
+			task: item.task,
+			cwd,
+			phaseId: normalizePhaseId(item.phaseId),
+			scope: normalizePhaseScope(item.scope, cwd),
+			isolation: item.isolation,
+			writeCapable: agent ? isWriteCapableAgent(agent) : true,
+		};
+	});
+}
+
+function parallelAdmissionConflict(
+	tasks: readonly PreparedDispatchTask[],
+	threads: Iterable<SubagentThread>,
+): string | undefined {
+	for (let leftIndex = 0; leftIndex < tasks.length; leftIndex++) {
+		for (let rightIndex = leftIndex + 1; rightIndex < tasks.length; rightIndex++) {
+			const left = tasks[leftIndex]!;
+			const right = tasks[rightIndex]!;
+			const duplicate = findDuplicateDispatch([{
+				id: left.index,
+				agentName: left.agent,
+				task: left.task,
+				phaseId: left.phaseId,
+				cwd: left.cwd,
+				state: "queued",
+			}], right.task, right.cwd, right.phaseId);
+			if (duplicate) {
+				return `deterministic duplicate between tasks[${left.index}] and tasks[${right.index}]`;
+			}
+		}
+	}
+	const leases = [...threads];
+	for (const task of tasks) {
+		const duplicate = findDuplicateDispatch(leases, task.task, task.cwd, task.phaseId);
+		if (duplicate?.kind === "active") {
+			return `tasks[${task.index}] duplicates active run #${duplicate.source.id} (${duplicate.source.agentName})`;
+		}
+		if (duplicate?.kind === "settled") {
+			return `tasks[${task.index}] duplicates settled run #${duplicate.source.id} (${duplicate.source.agentName}); inspect it with subagent_status and handle follow-up work in main`;
+		}
+	}
+	const writers = tasks.filter(
+		(task): task is PreparedDispatchTask & { scope: PhaseScope } => task.writeCapable && task.scope !== undefined,
+	);
+	for (let leftIndex = 0; leftIndex < writers.length; leftIndex++) {
+		for (let rightIndex = leftIndex + 1; rightIndex < writers.length; rightIndex++) {
+			const left = writers[leftIndex]!;
+			const right = writers[rightIndex]!;
+			const overlap = findPhaseScopeOverlap(left.scope, right.scope);
+			if (overlap) {
+				return `tasks[${left.index}] scope ${overlap.left} overlaps tasks[${right.index}] scope ${overlap.right}`;
+			}
+		}
+	}
+	for (const task of writers) {
+		const conflict = findWriterLeaseScopeOverlap(task.scope, leases);
+		if (conflict) {
+			return `tasks[${task.index}] scope ${conflict.overlap.left} overlaps run #${conflict.lease.id} scope ${conflict.overlap.right}`;
+		}
+	}
+	return undefined;
+}
+
 /** Map the child's own usage tally onto pi's tool-result `Usage`, so sub-agent
  * token spend lands in the parent's footer, /session, and RPC session totals
  * instead of being invisible. Only the total cost is known here: a child
@@ -134,13 +252,8 @@ function toolUsage(runtime: SubagentRuntime, runIds: number[]): { usage?: Usage
 	return parts.length > 0 ? { usage: toToolUsage(sumUsage(parts)) } : {};
 }
 
-/** In-turn wait behind dispatch `wait: true` — the escape hatch for one-shot
- * `pi -p` parents that exit at end of turn or an immediate dependent step: hold
- * the call until every run it started settles, then hand back result blocks. No
- * timer: a waiter resolves the moment its run's result registers (children
- * are bounded by the idle watchdog), an already-parked run answers
- * immediately with its resume handle, and the turn's abort signal remains the
- * escape hatch. */
+/** In-turn wait for a fresh dispatch. Registration resolves it without a model-chosen
+ * timer; parent abort or removal ends the wait without losing background delivery. */
 export async function awaitRunResults(
 	runtime: SubagentRuntime,
 	runIds: number[],
@@ -153,7 +266,7 @@ export async function awaitRunResults(
 		const already = runtime.settledRuns.get(runId);
 		if (already) return Promise.resolve({ result: already });
 		if (monitor.findRun(runId)?.status === "parked") {
-			return Promise.resolve({ note: `run #${runId} is parked at a stable checkpoint; use subagent_control resume to continue it` });
+			return Promise.resolve({ note: `run #${runId} was interrupted; inspect retained work with subagent_status and finish it in main` });
 		}
 		return new Promise((resolve) => {
 			let done = false;
@@ -182,7 +295,7 @@ export async function awaitRunResults(
 				}
 				const live = monitor.findRun(runId);
 				if (live?.status === "parked") {
-					finish({ note: `run #${runId} was parked at a stable checkpoint; use subagent_control resume to continue it` });
+					finish({ note: `run #${runId} was interrupted; inspect retained work with subagent_status and finish it in main` });
 					return;
 				}
 				if (!live) {
@@ -242,15 +355,12 @@ export async function awaitRunResults(
 }
 
 export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime): void {
-	// Latest dispatch environment. The dispatcher is created once per process so
-	// restored threads can resume before any dispatch has run; each execute
-	// refreshes the fallback context, config, and agent catalog it resolves.
+	// Each dispatch refreshes the context, config, and agent catalog.
 	const environmentRef: { current: DispatchEnvironment | undefined } = { current: undefined };
 
 	// Terminal rows stay in the monitor until the next beginTurn so the footer
 	// can count them beside siblings that are still live. The widget ignores
-	// them. A second finishRun for the same endedAt is a no-op; a resume
-	// clears endedAt, so the next settlement notifies again.
+	// them. Repeated publication of the same settlement is a no-op.
 	const publishedEndedAt = new Map<number, number>();
 	const finishRun = (
 		runId: number,
@@ -265,7 +375,12 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 		if (endedAt !== undefined) publishedEndedAt.set(runId, endedAt);
 		if (opts?.silent || !runtime.sessionActive) return;
 		const icon = status === "done" ? "✓" : "✗";
-		environmentRef.current?.ctx.ui.notify(`${icon} #${run.id} ${monitor.summarize(run)}`, status === "done" ? "info" : "error");
+		const result = runtime.threads.get(runId)?.lastResult;
+		const error = status === "failed" ? result ? getResultError(result) : "No failure reason was recorded." : undefined;
+		environmentRef.current?.ctx.ui.notify(
+			`${icon} #${run.id} ${monitor.summarize(run)}${error ? ` · ${formatTaskSummary(error, 300, false)}` : ""}`,
+			status === "done" ? "info" : "error",
+		);
 	};
 
 	// Live sub-agent activity → concise one-line status ("thinking",
@@ -325,11 +440,15 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 		(mode: "single" | "parallel", background = false) =>
 		(results: SingleResult[]): SubagentDetails => ({ mode, results, background });
 
-	const phaseLeaseReceipt = (runIds: number[]): string =>
+	const phaseLeaseReceipt = (
+		runIds: number[],
+		options: { mode: "single" } | { mode: "parallel"; declaredScopesComplete: boolean },
+	): string =>
 		formatPhaseLeaseReceipt(
 			runIds
 				.map((runId) => runtime.threads.get(runId))
 				.filter((thread): thread is SubagentThread => thread !== undefined),
+			options,
 		);
 
 	/** Pacing note appended to dispatch confirmations whenever runs are actually
@@ -373,12 +492,11 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 		makeLiveHandler,
 		makeDetails,
 	});
-	runtime.dispatcher = startBackground;
 
 	pi.registerTool({
 		name: "subagent",
 		label: "Subagent",
-		description: "Start paid leaf runs for broad reconnaissance or substantial self-contained work. Each normalized task+cwd owns its phase: an exact duplicate of an active run is rejected, and one of a finished run with retained context is rejected in favor of subagent_control resume. Batch scopes must be independent. wait:true returns results in-turn; otherwise completions wake main. Parallel writers default to detached Git worktrees; isolation:'shared' serializes same-repository writes.",
+		description: "Start paid one-shot leaf runs for substantial self-contained work. phaseId is a stable logical identity; exact task+cwd is the fallback. scope declares write-conflict metadata, not permissions or a sandbox. Fresh writers are checked against active leases; parallel batches preflight duplicate phases and declared overlaps before allocation. Missing scope reports `independence not verified`; claims do not prove task independence. wait:true returns results in-turn; otherwise completions wake main. Inspect with subagent_status, cancel with subagent_stop; main handles failed or incomplete work.",
 		parameters: SubagentParams,
 
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {
@@ -401,8 +519,6 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 				projectTrusted: ctx.isProjectTrusted?.() === true,
 			});
 			const agents = discovery.agents;
-			// Refresh the dispatcher's fallback environment so control operations
-			// (resume of restored threads) never run on a stale context.
 			environmentRef.current = { ctx, config, agents };
 
 			const hasTasks = (params.tasks?.length ?? 0) > 0;
@@ -452,10 +568,21 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 			// each delegated phase. The queue paces child processes without changing
 			// phase ownership or requiring a per-call task cap.
 			if (params.tasks && params.tasks.length > 0) {
-				// Admission is synchronous and ordered; slow worktree preparation belongs
-				// to the bounded queue. Promise.all preserves caller result order while no
-				// item waits for a sibling's filesystem setup.
-				const results = await Promise.all(params.tasks.map((item) => {
+				let prepared: PreparedDispatchTask[];
+				try {
+					prepared = prepareDispatchTasks(params.tasks, ctx.cwd, agents);
+				} catch (error) {
+					throw new Error(`Parallel admission rejected: ${error instanceof Error ? error.message : String(error)} No background tasks were started.`);
+				}
+				const conflict = parallelAdmissionConflict(prepared, runtime.threads.values());
+				if (conflict) {
+					throw new Error(`Parallel admission rejected: ${conflict}. No background tasks were started.`);
+				}
+				const declaredScopesComplete = prepared.every((item) => item.scope !== undefined);
+				const admissionNote = formatParallelScopeAdmissionNote(declaredScopesComplete);
+				// Duplicate and scope admission completes for the whole batch before any
+				// startBackground call can allocate a run. Worktree preparation stays queued.
+				const results = await Promise.all(prepared.map((item) => {
 					const catalogAgent = agents.find((candidate) => candidate.name === item.agent);
 					return startBackground(
 						item.agent,
@@ -464,11 +591,16 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 						defaultIsolationMode(
 							"parallel",
 							item.agent,
-							item.isolation as IsolationMode | undefined,
+							item.isolation,
 							catalogAgent ? isWorktreeCapableAgent(catalogAgent) : undefined,
 							catalogAgent?.isolation,
 						),
-						{ deliveryRoute: params.wait ? "await" : "background" },
+						{
+							deliveryRoute: params.wait ? "await" : "background",
+							phaseId: item.phaseId,
+							scope: item.scope,
+							writeCapable: item.writeCapable,
+						},
 					);
 				}));
 				const startedRuns = results.filter((result) => result.exitCode === -1);
@@ -492,9 +624,10 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 					const blocks = await awaitRunResults(runtime, startedIds, signal, config.maxResultLines, ctx.cwd, makeProgress(makeDetails("parallel", true)(results)));
 					if (signal?.aborted) runtime.fallbackAwaitDelivery(startedIds);
 					else runtime.completeAwaitDelivery(startedIds);
-					const text = failureLines.length > 0
+					const resultText = failureLines.length > 0
 						? `${blocks}\n\nLaunch failures:\n${failureLines.join("\n")}`
 						: blocks;
+					const text = `${resultText}\n\n${admissionNote}`;
 					return {
 						content: [{ type: "text", text }],
 						details: makeDetails("parallel", true)(results),
@@ -502,7 +635,7 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 					};
 				}
 				const text = [
-					phaseLeaseReceipt(startedIds),
+					phaseLeaseReceipt(startedIds, { mode: "parallel", declaredScopesComplete }),
 					...(failureLines.length > 0 ? ["Launch failures:", ...failureLines] : []),
 				].join("\n") + queuePacingNote();
 				return {
@@ -511,19 +644,37 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 				};
 			}
 
-			const singleCatalogAgent = agents.find((candidate) => candidate.name === params.agent);
+			let single: PreparedDispatchTask;
+			try {
+				single = prepareDispatchTasks([{
+					agent: params.agent as string,
+					task: params.task as string,
+					cwd: params.cwd,
+					phaseId: params.phaseId,
+					scope: params.scope,
+					isolation: params.isolation as IsolationMode | undefined,
+				}], ctx.cwd, agents)[0]!;
+			} catch (error) {
+				throw new Error(`Dispatch admission rejected: ${error instanceof Error ? error.message : String(error)}`);
+			}
+			const singleCatalogAgent = agents.find((candidate) => candidate.name === single.agent);
 			const result = await startBackground(
-				params.agent as string,
-				params.task as string,
-				params.cwd,
+				single.agent,
+				single.task,
+				single.cwd,
 				defaultIsolationMode(
 					"single",
-					params.agent as string,
-					params.isolation as IsolationMode | undefined,
+					single.agent,
+					single.isolation,
 					singleCatalogAgent ? isWorktreeCapableAgent(singleCatalogAgent) : undefined,
 					singleCatalogAgent?.isolation,
 				),
-				{ deliveryRoute: params.wait ? "await" : "background" },
+				{
+					deliveryRoute: params.wait ? "await" : "background",
+					phaseId: single.phaseId,
+					scope: single.scope,
+					writeCapable: single.writeCapable,
+				},
 			);
 			if (result.exitCode !== -1) {
 				throw new Error(getResultOutput(result));
@@ -541,7 +692,7 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 			return {
 				content: [{
 					type: "text",
-					text: phaseLeaseReceipt(result.runId === undefined ? [] : [result.runId]) + queuePacingNote(),
+					text: phaseLeaseReceipt(result.runId === undefined ? [] : [result.runId], { mode: "single" }) + queuePacingNote(),
 				}],
 				details: makeDetails("single", true)([result]),
 			};

package/src/delegation/phase-scope.ts

@@ -0,0 +1,178 @@
+import { isAbsolute, relative, resolve, sep } from "node:path";
+
+export interface SymbolScopeClaim {
+	path: string;
+	name: string;
+}
+
+export interface PhaseScopeInput {
+	paths?: string[];
+	symbols?: SymbolScopeClaim[];
+}
+
+/** Absolute, platform-normalized claims used only for deterministic admission. */
+export interface PhaseScope {
+	paths?: string[];
+	symbols?: SymbolScopeClaim[];
+}
+
+export interface PhaseScopeOverlap {
+	left: string;
+	right: string;
+	kind: "path-path" | "path-symbol" | "symbol-symbol";
+}
+
+export const PHASE_ID_MAX_LENGTH = 80;
+export const PHASE_ID_PATTERN_SOURCE = "^[A-Za-z0-9][A-Za-z0-9._:-]*$";
+const PHASE_ID_PATTERN = new RegExp(PHASE_ID_PATTERN_SOURCE, "u");
+const WILDCARD_PATH = /[*?]/u;
+
+function normalizePathCase(path: string): string {
+	return process.platform === "win32" ? path.toLowerCase() : path;
+}
+
+function normalizeClaimPath(path: unknown, cwd: string, label: string): string {
+	if (typeof path !== "string" || path.trim().length === 0) {
+		throw new Error(`${label} must be a non-blank exact file or directory path.`);
+	}
+	const trimmed = path.trim();
+	if (WILDCARD_PATH.test(trimmed)) {
+		throw new Error(`${label} must be exact; wildcard * and ? inputs are not supported. Other punctuation is treated literally.`);
+	}
+	return normalizePathCase(resolve(cwd, trimmed));
+}
+
+export function normalizePhaseId(phaseId: string | undefined): string | undefined {
+	if (phaseId === undefined) return undefined;
+	if (
+		typeof phaseId !== "string" ||
+		phaseId.length > PHASE_ID_MAX_LENGTH ||
+		!PHASE_ID_PATTERN.test(phaseId)
+	) {
+		throw new Error(`phaseId must be a single-line identifier of 1-${PHASE_ID_MAX_LENGTH} ASCII letters, numbers, or ._:- characters, starting with a letter or number.`);
+	}
+	return phaseId;
+}
+
+/** Resolve exact claims against the caller-facing cwd. An omitted scope remains
+ * compatible; a present scope must contain at least one valid claim. */
+export function normalizePhaseScope(
+	scope: PhaseScopeInput | undefined,
+	cwd: string,
+): PhaseScope | undefined {
+	if (scope === undefined) return undefined;
+	if (!scope || typeof scope !== "object") throw new Error("scope must be an object when provided.");
+	if (scope.paths !== undefined && !Array.isArray(scope.paths)) throw new Error("scope.paths must be an array.");
+	if (scope.symbols !== undefined && !Array.isArray(scope.symbols)) throw new Error("scope.symbols must be an array.");
+
+	const paths = [...new Set((scope.paths ?? []).map((path, index) =>
+		normalizeClaimPath(path, cwd, `scope.paths[${index}]`),
+	))];
+	const symbols: SymbolScopeClaim[] = [];
+	const symbolKeys = new Set<string>();
+	for (const [index, symbol] of (scope.symbols ?? []).entries()) {
+		if (!symbol || typeof symbol !== "object") {
+			throw new Error(`scope.symbols[${index}] must contain an exact path and symbol name.`);
+		}
+		const path = normalizeClaimPath(symbol.path, cwd, `scope.symbols[${index}].path`);
+		if (typeof symbol.name !== "string" || symbol.name.trim().length === 0) {
+			throw new Error(`scope.symbols[${index}].name must be non-blank.`);
+		}
+		const name = symbol.name.trim();
+		const key = `${path}\0${name}`;
+		if (!symbolKeys.has(key)) {
+			symbolKeys.add(key);
+			symbols.push({ path, name });
+		}
+	}
+	if (paths.length === 0 && symbols.length === 0) {
+		throw new Error("scope must contain at least one valid claim in paths or symbols.");
+	}
+	return {
+		...(paths.length > 0 ? { paths } : {}),
+		...(symbols.length > 0 ? { symbols } : {}),
+	};
+}
+
+function containsPath(ancestor: string, candidate: string): boolean {
+	if (ancestor === candidate) return true;
+	const child = relative(ancestor, candidate);
+	return child !== "" && child !== ".." && !child.startsWith(`..${sep}`) && !isAbsolute(child);
+}
+
+function describeSymbol(symbol: SymbolScopeClaim): string {
+	return `${symbol.path}#${symbol.name}`;
+}
+
+/** Return the first deterministic overlap. Path claims cover the named path and
+ * descendants; symbols on the same file overlap only when their names match. */
+export function findPhaseScopeOverlap(
+	left: PhaseScope,
+	right: PhaseScope,
+): PhaseScopeOverlap | undefined {
+	for (const leftPath of left.paths ?? []) {
+		for (const rightPath of right.paths ?? []) {
+			if (containsPath(leftPath, rightPath) || containsPath(rightPath, leftPath)) {
+				return { left: leftPath, right: rightPath, kind: "path-path" };
+			}
+		}
+	}
+	for (const leftPath of left.paths ?? []) {
+		for (const rightSymbol of right.symbols ?? []) {
+			if (containsPath(leftPath, rightSymbol.path)) {
+				return { left: leftPath, right: describeSymbol(rightSymbol), kind: "path-symbol" };
+			}
+		}
+	}
+	for (const leftSymbol of left.symbols ?? []) {
+		for (const rightPath of right.paths ?? []) {
+			if (containsPath(rightPath, leftSymbol.path)) {
+				return { left: describeSymbol(leftSymbol), right: rightPath, kind: "path-symbol" };
+			}
+		}
+	}
+	for (const leftSymbol of left.symbols ?? []) {
+		for (const rightSymbol of right.symbols ?? []) {
+			if (leftSymbol.path === rightSymbol.path && leftSymbol.name === rightSymbol.name) {
+				return {
+					left: describeSymbol(leftSymbol),
+					right: describeSymbol(rightSymbol),
+					kind: "symbol-symbol",
+				};
+			}
+		}
+	}
+	return undefined;
+}
+
+export interface WriterScopeLease {
+	id: number;
+	agentName: string;
+	state: "queued" | "running" | "interrupting" | "parked" | "completed" | "failed" | "stopped";
+	lifecycleOperation?: "stop" | "settle";
+	retired?: boolean;
+	scope?: PhaseScope;
+	writeCapable?: boolean;
+}
+
+export interface WriterLeaseScopeOverlap {
+	lease: WriterScopeLease;
+	overlap: PhaseScopeOverlap;
+}
+
+const SCOPE_ADMISSION_STATES = new Set<WriterScopeLease["state"]>(["queued", "running", "interrupting", "parked"]);
+
+/** Compare absolute normalized claims against active writer leases across caller cwds. */
+export function findWriterLeaseScopeOverlap(
+	scope: PhaseScope,
+	leases: Iterable<WriterScopeLease>,
+): WriterLeaseScopeOverlap | undefined {
+	for (const lease of leases) {
+		const active = lease.lifecycleOperation === "settle" || SCOPE_ADMISSION_STATES.has(lease.state);
+		const writes = lease.writeCapable ?? lease.agentName !== "scout";
+		if (!active || lease.retired || !writes || !lease.scope) continue;
+		const overlap = findPhaseScopeOverlap(scope, lease.scope);
+		if (overlap) return { lease, overlap };
+	}
+	return undefined;
+}