taskplane 0.1.18 → 0.2.0

package/extensions/taskplane/extension.ts

@@ -281,6 +281,17 @@ export default function (pi: ExtensionAPI) {
 						"info",
 					);
 				}
+				const hasStrictErrors = fatalErrors.some(
+					(e) => e.code === "TASK_ROUTING_STRICT",
+				);
+				if (hasStrictErrors) {
+					ctx.ui.notify(
+						"💡 Strict routing is enabled (routing.strict: true). Every task must declare an explicit execution target.\n" +
+						"   Add a `## Execution Target` section with `Repo: <id>` to each task's PROMPT.md.\n" +
+						"   To disable strict routing, set `routing.strict: false` in workspace config.",
+						"info",
+					);
+				}
 				return;
 			}
 

package/extensions/taskplane/index.ts

@@ -8,6 +8,7 @@
 export * from "./types.ts";
 export * from "./config.ts";
 export * from "./git.ts";
+export * from "./naming.ts";
 export * from "./worktree.ts";
 export * from "./discovery.ts";
 export * from "./waves.ts";

package/extensions/taskplane/merge.ts

@@ -7,8 +7,10 @@ import { spawnSync } from "child_process";
 import { join } from "path";
 
 import { buildLaneEnvVars, buildTmuxSpawnArgs, execLog, tmuxHasSession, tmuxKillSession, toTmuxPath } from "./execution.ts";
+import { resolveOperatorId } from "./naming.ts";
 import { MERGE_POLL_INTERVAL_MS, MERGE_RESULT_GRACE_MS, MERGE_RESULT_READ_RETRIES, MERGE_RESULT_READ_RETRY_DELAY_MS, MERGE_SPAWN_RETRY_MAX, MERGE_TIMEOUT_MS, MergeError, VALID_MERGE_STATUSES } from "./types.ts";
-import type { AllocatedLane, LaneExecutionResult, MergeLaneResult, MergeResult, MergeResultStatus, MergeWaveResult, OrchestratorConfig, WaveExecutionResult } from "./types.ts";
+import type { AllocatedLane, LaneExecutionResult, MergeLaneResult, MergeResult, MergeResultStatus, MergeWaveResult, OrchestratorConfig, RepoMergeOutcome, WaveExecutionResult, WorkspaceConfig } from "./types.ts";
+import { resolveBaseBranch, resolveRepoRoot } from "./waves.ts";
 import { sleepSync } from "./worktree.ts";
 
 // ── Merge Implementation ─────────────────────────────────────────────
@@ -493,6 +495,7 @@ export function mergeWave(
 ): MergeWaveResult {
 	const startTime = Date.now();
 	const tmuxPrefix = config.orchestrator.tmux_prefix;
+	const opId = resolveOperatorId(config);
 	const targetBranch = baseBranch;
 	const laneResults: MergeLaneResult[] = [];
 
@@ -543,8 +546,9 @@ export function mergeWave(
 	// ── Create isolated merge worktree ──────────────────────────────
 	// Merging in a dedicated worktree prevents dirty-worktree failures
 	// caused by user edits or orchestrator-generated files in the main repo.
-	const tempBranch = `_merge-temp-${batchId}`;
-	const mergeWorkDir = join(repoRoot, ".worktrees", "merge-workspace");
+	// Include opId to prevent collisions between concurrent operators.
+	const tempBranch = `_merge-temp-${opId}-${batchId}`;
+	const mergeWorkDir = join(repoRoot, ".worktrees", `merge-workspace-${opId}`);
 
 	// Clean up stale merge worktree/branch from prior failed attempt
 	try {
@@ -592,10 +596,10 @@ export function mergeWave(
 
 	for (const lane of orderedLanes) {
 		const laneStart = Date.now();
-		const sessionName = `${tmuxPrefix}-merge-${lane.laneNumber}`;
-		const resultFileName = `merge-result-w${waveIndex}-lane${lane.laneNumber}-${batchId}.json`;
+		const sessionName = `${tmuxPrefix}-${opId}-merge-${lane.laneNumber}`;
+		const resultFileName = `merge-result-w${waveIndex}-lane${lane.laneNumber}-${opId}-${batchId}.json`;
 		const resultFilePath = join(repoRoot, ".pi", resultFileName);
-		const requestFileName = `merge-request-w${waveIndex}-lane${lane.laneNumber}-${batchId}.txt`;
+		const requestFileName = `merge-request-w${waveIndex}-lane${lane.laneNumber}-${opId}-${batchId}.txt`;
 		const requestFilePath = join(repoRoot, ".pi", requestFileName);
 
 		execLog("merge", sessionName, `starting merge for lane ${lane.laneNumber}`, {
@@ -647,6 +651,7 @@ export function mergeWave(
 				result: mergeResult,
 				error: null,
 				durationMs: Date.now() - laneStart,
+				repoId: lane.repoId,
 			});
 
 			// Handle merge outcome
@@ -715,6 +720,7 @@ export function mergeWave(
 				result: null,
 				error: errMsg,
 				durationMs: Date.now() - laneStart,
+				repoId: lane.repoId,
 			});
 
 			failedLane = lane.laneNumber;
@@ -795,3 +801,241 @@ export function mergeWave(
 	};
 }
 
+
+// ── Repo-Scoped Merge ────────────────────────────────────────────────
+
+/**
+ * Group mergeable lanes by their `repoId`.
+ *
+ * Returns groups sorted deterministically by repoId (undefined/repo-mode
+ * group sorts first as empty string). Lanes within each group preserve
+ * the input order.
+ *
+ * @param lanes - Lanes to group (already filtered for mergeability)
+ * @returns Array of { repoId, lanes } groups in deterministic order
+ */
+export function groupLanesByRepo(
+	lanes: AllocatedLane[],
+): Array<{ repoId: string | undefined; lanes: AllocatedLane[] }> {
+	const groupMap = new Map<string, AllocatedLane[]>();
+
+	for (const lane of lanes) {
+		const key = lane.repoId ?? "";
+		const existing = groupMap.get(key) || [];
+		existing.push(lane);
+		groupMap.set(key, existing);
+	}
+
+	const sortedKeys = [...groupMap.keys()].sort();
+	return sortedKeys.map(key => ({
+		repoId: key || undefined,
+		lanes: groupMap.get(key)!,
+	}));
+}
+
+/**
+ * Merge a wave's lanes partitioned by repository.
+ *
+ * In repo mode (all lanes have repoId=undefined), this produces a single
+ * repo group and delegates to `mergeWave()` exactly once — a no-op
+ * regression case that preserves existing behavior.
+ *
+ * In workspace mode, lanes are grouped by `repoId`. Each repo group gets:
+ * - Its own repo root (via `resolveRepoRoot()`)
+ * - Its own base branch (via `resolveBaseBranch()`)
+ * - An independent `mergeWave()` call with those repo-scoped parameters
+ *
+ * Repo groups are processed in deterministic order (sorted by repoId).
+ * Per-repo results are aggregated into a single `MergeWaveResult` for
+ * the existing wave-level failure policy handling in `engine.ts`.
+ *
+ * Failure semantics:
+ * - A failure in one repo does NOT stop merging in other repos.
+ * - The aggregate status is "succeeded" only if all repos succeeded.
+ * - If any repo failed and any succeeded, status is "partial".
+ * - `repoResults` field carries per-repo attribution for downstream
+ *   reporting (Step 1 will use this for explicit partial-success summaries).
+ *
+ * @param completedLanes   - Lanes that completed execution (from wave result)
+ * @param waveResult       - The wave execution result (for lane status filtering)
+ * @param waveIndex        - Wave number (1-indexed)
+ * @param config           - Orchestrator configuration
+ * @param repoRoot         - Default repository root (used in repo mode)
+ * @param batchId          - Batch ID for session naming
+ * @param baseBranch       - Default branch to merge into (captured at batch start)
+ * @param workspaceConfig  - Workspace configuration (null in repo mode)
+ * @returns MergeWaveResult with per-lane and per-repo outcomes
+ */
+export function mergeWaveByRepo(
+	completedLanes: AllocatedLane[],
+	waveResult: WaveExecutionResult,
+	waveIndex: number,
+	config: OrchestratorConfig,
+	repoRoot: string,
+	batchId: string,
+	baseBranch: string,
+	workspaceConfig?: WorkspaceConfig | null,
+): MergeWaveResult {
+	const startTime = Date.now();
+
+	// Build lane outcome lookup for merge eligibility (same logic as mergeWave).
+	const laneOutcomeByNumber = new Map<number, LaneExecutionResult>();
+	for (const laneOutcome of waveResult.laneResults) {
+		laneOutcomeByNumber.set(laneOutcome.laneNumber, laneOutcome);
+	}
+
+	// Filter to mergeable lanes (same criteria as mergeWave).
+	const mergeableLanes = completedLanes.filter(lane => {
+		const outcome = laneOutcomeByNumber.get(lane.laneNumber);
+		if (!outcome) return false;
+		const hasSucceeded = outcome.tasks.some(t => t.status === "succeeded");
+		const hasHardFailure = outcome.tasks.some(
+			t => t.status === "failed" || t.status === "stalled",
+		);
+		return hasSucceeded && !hasHardFailure;
+	});
+
+	if (mergeableLanes.length === 0) {
+		execLog("merge", `W${waveIndex}`, "no mergeable lanes (all failed or empty)");
+		return {
+			waveIndex,
+			status: "succeeded",
+			laneResults: [],
+			failedLane: null,
+			failureReason: null,
+			totalDurationMs: Date.now() - startTime,
+			repoResults: [],
+		};
+	}
+
+	// Group lanes by repo
+	const repoGroups = groupLanesByRepo(mergeableLanes);
+
+	execLog("merge", `W${waveIndex}`, `merging across ${repoGroups.length} repo group(s)`, {
+		repos: repoGroups.map(g => g.repoId ?? "(default)").join(", "),
+		totalLanes: mergeableLanes.length,
+	});
+
+	// In repo mode (single group with repoId=undefined), delegate directly
+	// to mergeWave() for zero-overhead backward compatibility.
+	if (repoGroups.length === 1 && repoGroups[0].repoId === undefined) {
+		const result = mergeWave(
+			completedLanes,
+			waveResult,
+			waveIndex,
+			config,
+			repoRoot,
+			batchId,
+			baseBranch,
+		);
+		// Attach empty repoResults for consistent shape
+		return { ...result, repoResults: [] };
+	}
+
+	// ── Workspace mode: per-repo merge loops ─────────────────────
+	const allLaneResults: MergeLaneResult[] = [];
+	const repoOutcomes: RepoMergeOutcome[] = [];
+	let firstFailedLane: number | null = null;
+	let firstFailureReason: string | null = null;
+	// Track repo-level failures independently of lane-level failures.
+	// mergeWave() can return status="failed" with failedLane=null for
+	// pre-lane setup errors (temp branch creation, worktree creation).
+	// We must detect these to avoid misclassifying the aggregate as "succeeded".
+	let anyRepoFailed = false;
+
+	for (const group of repoGroups) {
+		const groupRepoRoot = resolveRepoRoot(group.repoId, repoRoot, workspaceConfig);
+		const groupBaseBranch = resolveBaseBranch(group.repoId, groupRepoRoot, baseBranch, workspaceConfig);
+
+		execLog("merge", `W${waveIndex}`, `merging repo group: ${group.repoId ?? "(default)"}`, {
+			repoRoot: groupRepoRoot,
+			baseBranch: groupBaseBranch,
+			laneCount: group.lanes.length,
+			lanes: group.lanes.map(l => l.laneNumber).join(","),
+		});
+
+		// Build a filtered WaveExecutionResult containing only this group's lanes.
+		const groupLaneNumbers = new Set(group.lanes.map(l => l.laneNumber));
+		const filteredWaveResult: WaveExecutionResult = {
+			...waveResult,
+			laneResults: waveResult.laneResults.filter(lr => groupLaneNumbers.has(lr.laneNumber)),
+			allocatedLanes: waveResult.allocatedLanes.filter(l => groupLaneNumbers.has(l.laneNumber)),
+		};
+
+		const groupResult = mergeWave(
+			group.lanes,
+			filteredWaveResult,
+			waveIndex,
+			config,
+			groupRepoRoot,
+			batchId,
+			groupBaseBranch,
+		);
+
+		// Accumulate lane results
+		allLaneResults.push(...groupResult.laneResults);
+
+		// Build per-repo outcome
+		const repoOutcome: RepoMergeOutcome = {
+			repoId: group.repoId,
+			status: groupResult.status,
+			laneResults: groupResult.laneResults,
+			failedLane: groupResult.failedLane,
+			failureReason: groupResult.failureReason,
+		};
+		repoOutcomes.push(repoOutcome);
+
+		// Track failures across repos (but continue to merge other repos).
+		// Check groupResult.status (not just failedLane) to catch setup failures
+		// where mergeWave() returns status="failed" with failedLane=null
+		// (e.g., temp branch creation or worktree creation failure).
+		if (groupResult.status !== "succeeded") {
+			anyRepoFailed = true;
+
+			if (firstFailureReason === null) {
+				firstFailedLane = groupResult.failedLane;
+				firstFailureReason = groupResult.failureReason
+					? `[repo:${group.repoId ?? "default"}] ${groupResult.failureReason}`
+					: `[repo:${group.repoId ?? "default"}] Merge failed (setup error)`;
+			}
+		}
+	}
+
+	// ── Aggregate status ─────────────────────────────────────────
+	// Use both lane-level and repo-level evidence for correct classification:
+	// - anyLaneSucceeded: at least one lane merged successfully across all repos
+	// - anyRepoFailed: at least one repo had a non-succeeded status (includes
+	//   both lane-level failures AND repo setup failures with failedLane=null)
+	const anyLaneSucceeded = allLaneResults.some(
+		r => r.result?.status === "SUCCESS" || r.result?.status === "CONFLICT_RESOLVED",
+	);
+
+	let status: MergeWaveResult["status"];
+	if (!anyRepoFailed) {
+		status = "succeeded";
+	} else if (anyLaneSucceeded) {
+		status = "partial";
+	} else {
+		status = "failed";
+	}
+
+	const totalDurationMs = Date.now() - startTime;
+
+	execLog("merge", `W${waveIndex}`, `repo-scoped wave merge complete: ${status}`, {
+		repoCount: repoOutcomes.length,
+		repoStatuses: repoOutcomes.map(r => `${r.repoId ?? "default"}:${r.status}`).join(", "),
+		mergedLanes: allLaneResults.filter(r => r.result?.status === "SUCCESS" || r.result?.status === "CONFLICT_RESOLVED").length,
+		duration: `${Math.round(totalDurationMs / 1000)}s`,
+	});
+
+	return {
+		waveIndex,
+		status,
+		laneResults: allLaneResults,
+		failedLane: firstFailedLane,
+		failureReason: firstFailureReason,
+		totalDurationMs,
+		repoResults: repoOutcomes,
+	};
+}
+

package/extensions/taskplane/messages.ts

@@ -2,7 +2,7 @@
  * User-facing message templates (ORCH_MESSAGES)
  * @module orch/messages
  */
-import type { AbortMode } from "./types.ts";
+import type { AbortMode, MergeWaveResult, OrchestratorConfig, RepoMergeOutcome } from "./types.ts";
 
 // ── Message Templates ────────────────────────────────────────────────
 
@@ -19,7 +19,7 @@ export const ORCH_MESSAGES = {
 	orchWaveComplete: (waveNum: number, succeeded: number, failed: number, skipped: number, elapsedSec: number) =>
 		`✅ Wave ${waveNum} complete: ${succeeded} succeeded, ${failed} failed, ${skipped} skipped (${elapsedSec}s)`,
 	orchMergeStart: (waveNum: number, laneCount: number) =>
-		`🔀 [Wave ${waveNum}] Merging ${laneCount} lane(s) into develop...`,
+		`🔀 [Wave ${waveNum}] Merging ${laneCount} lane(s) into target branch...`,
 	orchMergeLaneSuccess: (laneNum: number, commit: string, durationSec: number) =>
 		`  ✅ Lane ${laneNum} merged (${commit.slice(0, 8)}, ${durationSec}s)`,
 	orchMergeLaneConflictResolved: (laneNum: number, conflictCount: number, durationSec: number) =>
@@ -35,7 +35,7 @@ export const ORCH_MESSAGES = {
 	orchMergePlaceholder: (waveNum: number) =>
 		`🔀 [Wave ${waveNum}] Merge: placeholder — Step 3 (TS-008) will replace with mergeWave()`,
 	orchWorktreeReset: (waveNum: number, lanes: number) =>
-		`🔄 Resetting ${lanes} worktree(s) to develop HEAD after wave ${waveNum}`,
+		`🔄 Resetting ${lanes} worktree(s) to target branch HEAD after wave ${waveNum}`,
 	orchBatchComplete: (batchId: string, succeeded: number, failed: number, skipped: number, blocked: number, elapsedSec: number) => {
 		const lines = [`\n🏁 Batch ${batchId} complete: ${succeeded} succeeded, ${failed} failed, ${skipped} skipped, ${blocked} blocked (${elapsedSec}s)`];
 		if (failed > 0 || blocked > 0) {
@@ -117,9 +117,213 @@ export const ORCH_MESSAGES = {
 		`No active batch to abort. Use /orch <areas|all> to start a batch.`,
 	abortComplete: (mode: AbortMode, sessionsKilled: number) =>
 		`🏁 Abort (${mode}) complete: ${sessionsKilled} session(s) terminated. Worktrees and branches preserved.`,
+	// /orch merge — repo-scoped partial summary (TP-005 Step 1)
+	orchMergePartialRepoSummary: (waveNum: number, repoLines: string[]) =>
+		`⚠️ [Wave ${waveNum}] Merge partially succeeded — repo outcomes diverged:\n${repoLines.join("\n")}`,
 } as const;
 
 
+// ── Repo-Scoped Merge Summary (TP-005) ──────────────────────────────
+
+/**
+ * Status emoji for repo merge outcome.
+ */
+function repoStatusIcon(status: RepoMergeOutcome["status"]): string {
+	switch (status) {
+		case "succeeded": return "✅";
+		case "partial": return "⚠️";
+		case "failed": return "❌";
+		default: return "❓";
+	}
+}
+
+/**
+ * Format a repo-divergence summary for a partial merge wave result.
+ *
+ * Returns null if:
+ * - repoResults is empty or undefined (mono-repo mode)
+ * - all repos have the same status (no divergence)
+ * - there is only one repo group (divergence is meaningless)
+ *
+ * When the partial result is caused by mixed-outcome lanes within
+ * a single repo (not repo divergence), this returns null to avoid
+ * misleading "cross-repo divergence" messaging.
+ *
+ * The returned string is a complete, ready-to-emit message.
+ *
+ * @param mergeResult - The MergeWaveResult with status "partial"
+ * @returns Formatted summary string, or null if no repo-divergence summary applies
+ */
+export function formatRepoMergeSummary(mergeResult: MergeWaveResult): string | null {
+	const repoResults = mergeResult.repoResults;
+
+	// No repo attribution → mono-repo mode, no summary
+	if (!repoResults || repoResults.length === 0) {
+		return null;
+	}
+
+	// Single repo group → divergence is meaningless (partial is lane-level)
+	if (repoResults.length < 2) {
+		return null;
+	}
+
+	// Check for actual divergence: are there different statuses across repos?
+	const statuses = new Set(repoResults.map(r => r.status));
+	if (statuses.size < 2) {
+		// All repos have the same status (e.g., all "partial") —
+		// the partial is from within-repo lane failures, not cross-repo divergence
+		return null;
+	}
+
+	// Build per-repo summary lines (sorted by repoId, which repoResults already is)
+	const repoLines = repoResults.map(r => {
+		const repoLabel = r.repoId ?? "(default)";
+		const icon = repoStatusIcon(r.status);
+		const mergedCount = r.laneResults.filter(
+			lr => lr.result?.status === "SUCCESS" || lr.result?.status === "CONFLICT_RESOLVED",
+		).length;
+		const totalCount = r.laneResults.length;
+		let detail = `${mergedCount}/${totalCount} lane(s) merged`;
+		if (r.failureReason) {
+			detail += ` — ${r.failureReason.slice(0, 150)}`;
+		}
+		return `   ${icon} ${repoLabel}: ${detail}`;
+	});
+
+	return ORCH_MESSAGES.orchMergePartialRepoSummary(mergeResult.waveIndex, repoLines);
+}
+
+
+// ── Merge Failure Policy Application (TP-005 Step 2) ─────────────────
+
+/**
+ * Result of applying the merge failure policy.
+ *
+ * Pure function output — callers use this to perform state mutations
+ * and notifications consistently. Ensures engine.ts and resume.ts
+ * apply identical pause/abort transitions.
+ */
+export interface MergeFailurePolicyResult {
+	/** The applied policy: "pause" or "abort". */
+	policy: "pause" | "abort";
+	/** Target phase for batchState.phase. */
+	targetPhase: "paused" | "stopped";
+	/** Error message to push to batchState.errors. */
+	errorMessage: string;
+	/** Persistence trigger label. */
+	persistTrigger: "merge-failure-pause" | "merge-failure-abort";
+	/** User-facing notification message. */
+	notifyMessage: string;
+	/** Notification level for onNotify. */
+	notifyLevel: "error";
+	/** Comma-separated failed lane identifiers for logging. */
+	failedLaneIds: string;
+	/** Structured log details for execLog. */
+	logDetails: {
+		failedLane: number;
+		failedLaneIds: string;
+		reason: string;
+	};
+}
+
+/**
+ * Compute the merge failure policy application result.
+ *
+ * This is a **pure function** — it computes all outputs deterministically
+ * from the merge result and config, without performing any side effects.
+ *
+ * Both engine.ts and resume.ts MUST use this function to guarantee
+ * identical failure attribution, phase transitions, error messages,
+ * and notifications on repo-scoped merge failures.
+ *
+ * Failure attribution rules (priority chain):
+ * 1. Lane-level: lanes with CONFLICT_UNRESOLVED, BUILD_FAILURE, or error
+ *    → formatted as `lane-<N>` (comma-separated).
+ * 2. Fallback: if no lane-level failures but `mergeResult.failedLane`
+ *    is non-null, uses `lane-<N>` as the identifier.
+ * 3. Repo-level: if no lane-level failures and failedLane is null
+ *    (repo setup failure), uses `repo:<repoId>` from repoResults
+ *    entries with non-succeeded status. Sorted deterministically.
+ * - The failure reason is truncated to 200 chars for notifications and
+ *   logged in full in batchState.errors.
+ *
+ * @param mergeResult  - The merge wave result with status "failed" or "partial"
+ * @param waveIndex    - 0-based wave index (displayed as 1-indexed)
+ * @param config       - Orchestrator configuration (for on_merge_failure policy)
+ * @returns Policy result object for callers to apply
+ */
+export function computeMergeFailurePolicy(
+	mergeResult: MergeWaveResult,
+	waveIndex: number,
+	config: OrchestratorConfig,
+): MergeFailurePolicyResult {
+	const waveNum = waveIndex + 1;
+	const mergeFailurePolicy = config.failure.on_merge_failure;
+
+	// Build failed lane identifiers from lane results.
+	// Priority chain:
+	//   1. Lane-level: lanes with CONFLICT_UNRESOLVED, BUILD_FAILURE, or error
+	//   2. Fallback: failedLane from mergeResult (single lane ID)
+	//   3. Repo-level: repos with non-succeeded status from repoResults
+	//      (catches setup failures where failedLane=null and no lane results)
+	let failedLaneIds = mergeResult.laneResults
+		.filter(r => r.result?.status === "CONFLICT_UNRESOLVED" || r.result?.status === "BUILD_FAILURE" || r.error)
+		.map(r => `lane-${r.laneNumber}`)
+		.join(", ");
+	if (!failedLaneIds && mergeResult.failedLane !== null) {
+		failedLaneIds = `lane-${mergeResult.failedLane}`;
+	}
+	if (!failedLaneIds && mergeResult.repoResults && mergeResult.repoResults.length > 0) {
+		// Repo-level fallback for setup failures (no lane results, failedLane=null).
+		// Uses sorted repoResults order for determinism.
+		failedLaneIds = mergeResult.repoResults
+			.filter(r => r.status !== "succeeded")
+			.map(r => `repo:${r.repoId ?? "default"}`)
+			.join(", ");
+	}
+
+	const reason = mergeResult.failureReason || "unknown";
+	const reasonTruncated = reason.slice(0, 200);
+
+	const logDetails = {
+		failedLane: mergeResult.failedLane ?? 0,
+		failedLaneIds,
+		reason: reasonTruncated,
+	};
+
+	const errorMessage =
+		`Merge failed at wave ${waveNum}: ${reason}. ` +
+		(mergeFailurePolicy === "pause"
+			? `Batch paused. Resolve conflicts and use /orch-resume to continue.`
+			: `Batch aborted by on_merge_failure policy.`);
+
+	const laneDetail = failedLaneIds ? ` (${failedLaneIds})` : "";
+
+	let notifyMessage: string;
+	if (mergeFailurePolicy === "pause") {
+		notifyMessage =
+			`⏸️  Batch paused due to merge failure at wave ${waveNum}${laneDetail}. ` +
+			`Reason: ${reasonTruncated}. ` +
+			`Resolve conflicts and resume.`;
+	} else {
+		notifyMessage =
+			`⛔ Batch aborted due to merge failure at wave ${waveNum}${laneDetail}. ` +
+			`Reason: ${reasonTruncated}.`;
+	}
+
+	return {
+		policy: mergeFailurePolicy,
+		targetPhase: mergeFailurePolicy === "pause" ? "paused" : "stopped",
+		errorMessage,
+		persistTrigger: mergeFailurePolicy === "pause" ? "merge-failure-pause" : "merge-failure-abort",
+		notifyMessage,
+		notifyLevel: "error",
+		failedLaneIds,
+		logDetails,
+	};
+}
+
+
 // ── Resume ORCH_MESSAGES ─────────────────────────────────────────────
 
 // Note: These are added via extension to the ORCH_MESSAGES object below.

package/extensions/taskplane/naming.ts

@@ -0,0 +1,117 @@
+/**
+ * Naming contract helpers for team-scale collision resistance.
+ *
+ * Provides deterministic, human-readable identifiers for TMUX sessions,
+ * worktree directories, git branches, and merge artifacts. All naming
+ * components are sanitized for safe use in filesystem paths, git refs,
+ * and TMUX session names.
+ *
+ * @module orch/naming
+ */
+import { basename, resolve } from "path";
+import { userInfo } from "os";
+
+import type { OrchestratorConfig } from "./types.ts";
+
+// ── Sanitization ─────────────────────────────────────────────────────
+
+/**
+ * Sanitize a raw string into a safe naming component.
+ *
+ * Rules:
+ * - Lowercase
+ * - Replace non-alphanumeric characters (except hyphens) with hyphens
+ * - Collapse consecutive hyphens
+ * - Trim leading/trailing hyphens
+ * - Truncate to `maxLen` characters
+ *
+ * Safe for use in: TMUX session names, git branch refs, filesystem paths.
+ *
+ * @param raw    - Raw input string
+ * @param maxLen - Maximum length (default: 16)
+ * @returns Sanitized string, or empty string if input sanitizes to nothing
+ */
+export function sanitizeNameComponent(raw: string, maxLen: number = 16): string {
+	return raw
+		.toLowerCase()
+		.replace(/[^a-z0-9-]/g, "-")
+		.replace(/-+/g, "-")
+		.replace(/^-+|-+$/g, "")
+		.slice(0, maxLen);
+}
+
+// ── Operator ID ──────────────────────────────────────────────────────
+
+/**
+ * Resolve the operator identifier from available sources.
+ *
+ * Resolution order (first non-empty wins):
+ * 1. `TASKPLANE_OPERATOR_ID` environment variable
+ * 2. `operator_id` field in OrchestratorConfig
+ * 3. Current OS username via `os.userInfo().username`
+ * 4. Fallback: `"op"`
+ *
+ * The resolved value is sanitized and truncated to 12 characters.
+ *
+ * @param config - Orchestrator configuration (may contain operator_id)
+ * @param env    - Environment variables (defaults to process.env)
+ * @returns Sanitized operator identifier (never empty)
+ */
+export function resolveOperatorId(
+	config: OrchestratorConfig,
+	env: Record<string, string | undefined> = process.env,
+): string {
+	const FALLBACK = "op";
+	const MAX_LEN = 12;
+
+	// 1. Environment variable
+	const envValue = env.TASKPLANE_OPERATOR_ID;
+	if (envValue && envValue.trim()) {
+		const sanitized = sanitizeNameComponent(envValue.trim(), MAX_LEN);
+		if (sanitized) return sanitized;
+	}
+
+	// 2. Config field
+	const configValue = config.orchestrator.operator_id;
+	if (configValue && configValue.trim()) {
+		const sanitized = sanitizeNameComponent(configValue.trim(), MAX_LEN);
+		if (sanitized) return sanitized;
+	}
+
+	// 3. OS username
+	try {
+		const username = userInfo().username;
+		if (username && username.trim()) {
+			const sanitized = sanitizeNameComponent(username.trim(), MAX_LEN);
+			if (sanitized) return sanitized;
+		}
+	} catch {
+		// userInfo() can throw on some platforms
+	}
+
+	// 4. Fallback
+	return FALLBACK;
+}
+
+// ── Repo Slug ────────────────────────────────────────────────────────
+
+/**
+ * Derive a repo slug from the repository root directory name.
+ *
+ * Provides cross-repo disambiguation when multiple repos share the
+ * same machine. Used in TMUX session names and worktree paths where
+ * names must be globally unique on the machine.
+ *
+ * @param repoRoot - Absolute path to the repository root
+ * @returns Sanitized repo slug (never empty; falls back to "repo")
+ */
+export function resolveRepoSlug(repoRoot: string): string {
+	const FALLBACK = "repo";
+	const MAX_LEN = 16;
+
+	const dirName = basename(resolve(repoRoot));
+	if (!dirName) return FALLBACK;
+
+	const sanitized = sanitizeNameComponent(dirName, MAX_LEN);
+	return sanitized || FALLBACK;
+}