taskplane 0.4.1 → 0.4.3

package/extensions/taskplane/config-loader.ts

@@ -726,6 +726,7 @@ export function toOrchestratorConfig(config: TaskplaneConfig): import("./types.t
 			spawn_mode: o.orchestrator.spawnMode,
 			tmux_prefix: o.orchestrator.tmuxPrefix,
 			operator_id: o.orchestrator.operatorId,
+			integration: o.orchestrator.integration,
 		},
 		dependencies: {
 			source: o.dependencies.source,

package/extensions/taskplane/config-schema.ts

@@ -216,6 +216,8 @@ export interface OrchestratorCoreConfig {
 	tmuxPrefix: string;
 	/** Operator identifier. Auto-detected from OS username if empty */
 	operatorId: string;
+	/** How completed batches are integrated. manual = user runs /orch-integrate. auto = fast-forward on completion. */
+	integration: "manual" | "auto";
 }
 
 /** Dependency resolution settings */
@@ -427,6 +429,7 @@ export const DEFAULT_ORCHESTRATOR_SECTION: OrchestratorSection = {
 		spawnMode: "subprocess",
 		tmuxPrefix: "orch",
 		operatorId: "",
+		integration: "manual",
 	},
 	dependencies: {
 		source: "prompt",

package/extensions/taskplane/persistence.ts

@@ -366,6 +366,18 @@ export function validatePersistedState(data: unknown): PersistedBatchState {
 		);
 	}
 
+	// ── Optional string fields: orchBranch ───────────────────────
+	// orchBranch was added after schema v2 shipped; default to "" if missing.
+	if (obj.orchBranch !== undefined && typeof obj.orchBranch !== "string") {
+		throw new StateFileError(
+			"STATE_SCHEMA_INVALID",
+			`Invalid "orchBranch" field (expected string, got ${typeof obj.orchBranch})`,
+		);
+	}
+	if (obj.orchBranch === undefined) {
+		obj.orchBranch = "";
+	}
+
 	// ── v2: mode field ───────────────────────────────────────────
 	// mode is required in v2, absent in v1 (defaults to "repo" via upconvert).
 	if (!isV1 && obj.mode === undefined) {
@@ -776,6 +788,7 @@ export function serializeBatchState(
 		phase: state.phase,
 		batchId: state.batchId,
 		baseBranch: state.baseBranch,
+		orchBranch: state.orchBranch ?? "",
 		mode: state.mode ?? "repo",
 		startedAt: state.startedAt,
 		updatedAt: now,

package/extensions/taskplane/resume.ts

@@ -612,6 +612,7 @@ export async function resumeOrchBatch(
 	batchState.phase = "executing";
 	batchState.batchId = persistedState.batchId;
 	batchState.baseBranch = persistedState.baseBranch || "";
+	batchState.orchBranch = persistedState.orchBranch || "";
 	batchState.mode = persistedState.mode;
 	batchState.startedAt = persistedState.startedAt;
 	batchState.pauseSignal = { paused: false };

package/extensions/taskplane/settings-tui.ts

@@ -98,9 +98,11 @@ export const SECTIONS: SectionDef[] = [
 			{ configPath: "orchestrator.orchestrator.worktreeLocation", label: "Worktree Location", control: "toggle", layer: "L1", fieldType: "enum", values: ["sibling", "subdirectory"], description: "Where lane worktree directories are created" },
 			{ configPath: "orchestrator.orchestrator.worktreePrefix", label: "Worktree Prefix", control: "input", layer: "L1", fieldType: "string", description: "Prefix for worktree directory names" },
 			{ configPath: "orchestrator.orchestrator.batchIdFormat", label: "Batch ID Format", control: "toggle", layer: "L1", fieldType: "enum", values: ["timestamp", "sequential"], description: "Batch ID format for logs/branch naming" },
-			{ configPath: "orchestrator.orchestrator.spawnMode", label: "Spawn Mode", control: "toggle", layer: "L1+L2", fieldType: "enum", values: ["tmux", "subprocess"], prefsKey: "spawnMode", description: "How lane sessions are spawned" },
+			// spawn_mode removed from Orchestrator section — /orch always requires tmux.
+			// The user-facing spawn mode setting is under Worker (controls /task behavior).
 			{ configPath: "orchestrator.orchestrator.tmuxPrefix", label: "Tmux Prefix", control: "input", layer: "L1+L2", fieldType: "string", prefsKey: "tmuxPrefix", description: "Prefix for orchestrator tmux sessions" },
 			{ configPath: "orchestrator.orchestrator.operatorId", label: "Operator ID", control: "input", layer: "L1+L2", fieldType: "string", prefsKey: "operatorId", description: "Operator identifier (empty = auto-detect)" },
+			{ configPath: "orchestrator.orchestrator.integration", label: "Integration", control: "toggle", layer: "L1", fieldType: "enum", values: ["manual", "auto"], description: "How completed batches are integrated. manual = user runs /orch-integrate. auto = fast-forward on completion." },
 		],
 	},
 	{
@@ -153,7 +155,7 @@ export const SECTIONS: SectionDef[] = [
 			{ configPath: "taskRunner.worker.model", label: "Worker Model", control: "input", layer: "L1+L2", fieldType: "string", prefsKey: "workerModel", description: "Worker model (empty = inherit session)" },
 			{ configPath: "taskRunner.worker.tools", label: "Worker Tools", control: "input", layer: "L1", fieldType: "string", description: "Worker tool allowlist" },
 			{ configPath: "taskRunner.worker.thinking", label: "Worker Thinking", control: "input", layer: "L1", fieldType: "string", description: "Worker thinking mode" },
-			{ configPath: "taskRunner.worker.spawnMode", label: "Worker Spawn Mode", control: "toggle", layer: "L1", fieldType: "enum", values: ["(inherit)", "subprocess", "tmux"], optional: true, description: "Worker spawn mode override (inherit = use orchestrator)" },
+			{ configPath: "taskRunner.worker.spawnMode", label: "Spawn Mode", control: "toggle", layer: "L1", fieldType: "enum", values: ["subprocess", "tmux"], description: "How /task spawns workers and reviewers. subprocess = child process (simpler), tmux = named sessions (attachable for debugging)" },
 		],
 	},
 	{
@@ -1109,6 +1111,30 @@ async function showSectionSettingsLoop(
 		const field = section.fields.find((f) => f.configPath === result.fieldId);
 		if (!field) continue;  // Safety: field not found
 
+		// Input fields: the submenu returned a sentinel — use ctx.ui.input() for actual editing
+		if (result.rawValue === "__EDIT_REQUESTED__" && field.control === "input") {
+			const state = loadConfigState(configRoot, pointerConfigRoot);
+			const currentDisplay = getFieldDisplayValue(field, state.mergedConfig, state.prefs);
+			const currentClean = String(currentDisplay).replace(/\s+\((?:default|project|user)\)$/, "");
+			const placeholder = currentClean === "(not set)" || currentClean === "(inherit)" ? "" : currentClean;
+
+			const newValue = await ctx.ui.input(
+				`${field.label}${field.description ? ` — ${field.description}` : ""}`,
+				placeholder,
+			);
+
+			if (newValue === null || newValue === undefined) continue;  // Cancelled
+
+			// Validate
+			const validation = validateFieldInput(field, newValue);
+			if (!validation.valid) {
+				ctx.ui.notify(`❌ Invalid value: ${validation.error}`, "error");
+				continue;
+			}
+
+			result.rawValue = newValue;
+		}
+
 		const typedValue = coerceValueForWrite(field, result.rawValue);
 
 		// Collect UI answers for the write-decision contract
@@ -1199,11 +1225,12 @@ async function showSectionSettingsOnce(
 			item.values = field.values.map((v) => `${v}  ${sourceBadge}`);
 		}
 
-		// Input fields get a submenu for inline editing
+		// Input fields: use a single-value cycling pattern instead of a submenu.
+		// The inline submenu approach freezes on Windows/tmux (issue #57).
+		// We set a single sentinel value so pressing Enter/Space triggers onChange,
+		// which exits the TUI. The caller then uses ctx.ui.input() for actual editing.
 		if (field.control === "input") {
-			item.submenu = (currentValue: string, submenuDone: (selectedValue?: string) => void) => {
-				return createInputSubmenu(field, currentValue, submenuDone);
-			};
+			item.values = [`__EDIT_REQUESTED__`];
 		}
 
 		return item;

package/extensions/taskplane/types.ts

@@ -17,6 +17,8 @@ export interface OrchestratorConfig {
 		tmux_prefix: string;
 		/** Optional operator identifier. Auto-detected from OS username if empty. */
 		operator_id: string;
+		/** How completed batches are integrated. manual = user runs /orch-integrate. auto = fast-forward on completion. */
+		integration: "manual" | "auto";
 	};
 	dependencies: {
 		source: "prompt" | "agent";
@@ -151,6 +153,7 @@ export const DEFAULT_ORCHESTRATOR_CONFIG: OrchestratorConfig = {
 		spawn_mode: "subprocess",
 		tmux_prefix: "orch",
 		operator_id: "",
+		integration: "manual",
 	},
 	dependencies: {
 		source: "prompt",
@@ -829,6 +832,8 @@ export interface OrchBatchRuntimeState {
 	batchId: string;
 	/** Branch that was active when /orch started — used as base for worktrees and merge target */
 	baseBranch: string;
+	/** Orchestrator-managed branch name (e.g., 'orch/henry-20260318T140000'). Empty = legacy mode (merge into baseBranch directly). */
+	orchBranch: string;
 	/** Workspace execution mode (v2). Defaults to "repo" for backward compatibility. */
 	mode: WorkspaceMode;
 	/** Shared pause signal — set by /orch-pause, read by executeLane/executeWave */
@@ -908,6 +913,7 @@ export function freshOrchBatchState(): OrchBatchRuntimeState {
 		phase: "idle",
 		batchId: "",
 		baseBranch: "",
+		orchBranch: "",
 		mode: "repo",
 		pauseSignal: { paused: false },
 		waveResults: [],
@@ -1367,6 +1373,8 @@ export interface PersistedBatchState {
 	batchId: string;
 	/** Branch that was active when /orch started — used as base for worktrees and merge target */
 	baseBranch: string;
+	/** Orchestrator-managed branch name (e.g., 'orch/henry-20260318T140000'). Empty = legacy mode (merge into baseBranch directly). */
+	orchBranch: string;
 	/**
 	 * Workspace execution mode at batch start (v2).
 	 * - "repo": Single-repo mode (default, backward-compatible).

package/extensions/taskplane/worktree.ts

@@ -2,7 +2,7 @@
  * Worktree CRUD, bulk ops, branch protection, preflight
  * @module orch/worktree
  */
-import { existsSync, readdirSync, realpathSync, rmSync } from "fs";
+import { existsSync, mkdirSync, readdirSync, realpathSync, rmSync } from "fs";
 import { execSync } from "child_process";
 import { join, basename, resolve } from "path";
 
@@ -54,20 +54,71 @@ export function resolveWorktreeBasePath(
 	return resolve(repoRoot, ".worktrees");
 }
 
+/**
+ * Generate the batch container directory name.
+ *
+ * Format: `{opId}-{batchId}`
+ * Example: `henrylach-20260308T111750`
+ *
+ * This is the directory that holds all lane worktrees and the merge
+ * worktree for a single batch.
+ *
+ * @param opId    - Operator identifier (sanitized, e.g., "henrylach")
+ * @param batchId - Batch ID timestamp (e.g. "20260308T111750")
+ */
+export function generateBatchContainerName(opId: string, batchId: string): string {
+	return `${opId}-${batchId}`;
+}
+
+/**
+ * Generate the absolute path to the batch container directory.
+ *
+ * All worktrees for a single batch (lanes + merge) live inside this container.
+ * Format: `{basePath}/{opId}-{batchId}`
+ *
+ * Uses `resolveWorktreeBasePath()` to respect `worktree_location` config
+ * (sibling vs subdirectory mode). Both `generateWorktreePath()` and
+ * `generateMergeWorktreePath()` delegate to this function, ensuring
+ * consistent base-path resolution.
+ *
+ * @param opId     - Operator identifier (sanitized, e.g., "henrylach")
+ * @param batchId  - Batch ID timestamp (e.g. "20260308T111750")
+ * @param repoRoot - Absolute path to the main repository root
+ * @param config   - Orchestrator config (optional; defaults to subdirectory mode)
+ * @returns        - Absolute path to the batch container directory
+ */
+export function generateBatchContainerPath(
+	opId: string,
+	batchId: string,
+	repoRoot: string,
+	config?: OrchestratorConfig,
+): string {
+	const effectiveConfig = config || DEFAULT_ORCHESTRATOR_CONFIG;
+	const basePath = resolveWorktreeBasePath(repoRoot, effectiveConfig);
+	return resolve(basePath, generateBatchContainerName(opId, batchId));
+}
+
 /**
  * Generate worktree path based on config's worktree_location setting.
  *
- * Naming rule: basename = {prefix}-{opId}-{N}
- *   Sibling mode:      ../{prefix}-{opId}-{N}        (e.g. ../taskplane-wt-henrylach-1)
- *   Subdirectory mode: .worktrees/{prefix}-{opId}-{N} (e.g. .worktrees/taskplane-wt-henrylach-1)
+ * Naming rule: `{basePath}/{opId}-{batchId}/lane-{N}`
+ *   Sibling mode:      ../{opId}-{batchId}/lane-{N}
+ *   Subdirectory mode: .worktrees/{opId}-{batchId}/lane-{N}
+ *
+ * Each batch gets its own container directory, preventing collisions
+ * between concurrent batches by the same operator.
+ *
+ * Uses `generateBatchContainerPath()` for the container directory,
+ * preserving `worktree_location` semantics (sibling vs subdirectory).
  *
  * Uses path.resolve() for Windows path normalization (R002 requirement).
  *
- * @param prefix     - Directory prefix (e.g. "taskplane-wt")
+ * @param prefix     - Directory prefix (unused in new scheme, kept for API compat)
  * @param laneNumber - Lane number (1-indexed)
  * @param repoRoot   - Absolute path to the main repository root
  * @param opId       - Operator identifier (sanitized, e.g., "henrylach")
  * @param config     - Orchestrator config (optional; defaults to subdirectory mode)
+ * @param batchId    - Batch ID timestamp (e.g. "20260308T111750")
  */
 export function generateWorktreePath(
 	prefix: string,
@@ -75,12 +126,90 @@ export function generateWorktreePath(
 	repoRoot: string,
 	opId: string,
 	config?: OrchestratorConfig,
+	batchId?: string,
 ): string {
+	if (batchId) {
+		// New batch-scoped container layout
+		const containerPath = generateBatchContainerPath(opId, batchId, repoRoot, config);
+		return resolve(containerPath, `lane-${laneNumber}`);
+	}
+
+	// Legacy fallback (no batchId) — flat layout for backward compatibility
 	const effectiveConfig = config || DEFAULT_ORCHESTRATOR_CONFIG;
 	const basePath = resolveWorktreeBasePath(repoRoot, effectiveConfig);
 	return resolve(basePath, `${prefix}-${opId}-${laneNumber}`);
 }
 
+/**
+ * Generate the merge worktree path inside a batch container.
+ *
+ * Format: `{basePath}/{opId}-{batchId}/merge`
+ *
+ * Uses `generateBatchContainerPath()` for config-aware, base-path-consistent
+ * path resolution (respects `worktree_location` setting). This ensures
+ * the merge worktree is co-located with lane worktrees in the same
+ * batch container for unified cleanup.
+ *
+ * @param repoRoot - Absolute path to the main repository root
+ * @param opId     - Operator identifier (sanitized, e.g., "henrylach")
+ * @param batchId  - Batch ID timestamp (e.g. "20260308T111750")
+ * @param config   - Orchestrator config (optional; defaults to subdirectory mode)
+ */
+export function generateMergeWorktreePath(
+	repoRoot: string,
+	opId: string,
+	batchId: string,
+	config?: OrchestratorConfig,
+): string {
+	const containerPath = generateBatchContainerPath(opId, batchId, repoRoot, config);
+	return resolve(containerPath, "merge");
+}
+
+/**
+ * Ensure the batch container directory exists, creating it if necessary.
+ *
+ * @param containerPath - Absolute path to the container directory
+ */
+export function ensureBatchContainerDir(containerPath: string): void {
+	if (!existsSync(containerPath)) {
+		mkdirSync(containerPath, { recursive: true });
+	}
+}
+
+/**
+ * Remove a batch container directory if it exists and is empty.
+ *
+ * Safety rules:
+ * - Only removes the directory if it exists
+ * - Only removes the directory if it is empty (no files or subdirectories)
+ * - Never force-removes a non-empty container (partial failure safety)
+ * - Returns whether the container was removed
+ *
+ * Used after per-worktree removals in `removeAllWorktrees()` and
+ * `forceCleanupWorktree()` to clean up the container directory when
+ * all worktrees inside it have been removed.
+ *
+ * @param containerPath - Absolute path to the batch container directory
+ * @returns true if the container was removed, false otherwise
+ */
+export function removeBatchContainerIfEmpty(containerPath: string): boolean {
+	if (!existsSync(containerPath)) {
+		return false; // Already gone — no-op
+	}
+
+	try {
+		const entries = readdirSync(containerPath);
+		if (entries.length > 0) {
+			return false; // Non-empty — do not remove (partial failure safety)
+		}
+		rmSync(containerPath, { recursive: false });
+		return true;
+	} catch {
+		// If we can't read or remove — leave it alone (safe default)
+		return false;
+	}
+}
+
 /**
  * Parse `git worktree list --porcelain` output into structured entries.
  *
@@ -205,7 +334,7 @@ export function createWorktree(opts: CreateWorktreeOptions, repoRoot: string): W
 	const { laneNumber, batchId, baseBranch, prefix, opId, config } = opts;
 
 	const branch = generateBranchName(laneNumber, batchId, opId);
-	const worktreePath = generateWorktreePath(prefix, laneNumber, repoRoot, opId, config);
+	const worktreePath = generateWorktreePath(prefix, laneNumber, repoRoot, opId, config, batchId);
 
 	// ── Pre-check 1: Validate base branch exists ─────────────────
 	const baseBranchCheck = runGit(
@@ -265,6 +394,12 @@ export function createWorktree(opts: CreateWorktreeOptions, repoRoot: string): W
 		);
 	}
 
+	// ── Ensure batch container directory exists ──────────────────
+	// Placed after pre-checks so no empty container is left behind on
+	// validation failure (R004 review feedback).
+	const containerDir = resolve(worktreePath, "..");
+	ensureBatchContainerDir(containerDir);
+
 	// ── Create worktree ──────────────────────────────────────────
 	const createResult = runGit(
 		["worktree", "add", "-b", branch, worktreePath, baseBranch],
@@ -1041,13 +1176,16 @@ export function preserveBranch(
  * Parses `git worktree list --porcelain` via parseWorktreeList() and filters
  * entries whose path basename matches `{prefix}-{opId}-{N}` (where N is a number).
  *
- * Operator-scoped discovery: only returns worktrees belonging to the specified
- * operator. This prevents one operator from accidentally reusing or removing
- * another operator's active worktrees in concurrent team-scale scenarios.
+ * **Batch-scoped discovery:** When `batchId` is provided, only returns worktrees
+ * inside the specific batch container `{opId}-{batchId}/lane-{N}`. This prevents
+ * cross-batch interference when the same operator runs concurrent batches.
+ *
+ * **Operator-scoped discovery:** When `batchId` is omitted, returns ALL worktrees
+ * belonging to the operator (across all batches). This supports cleanup scenarios
+ * that need to discover all operator worktrees regardless of batch.
  *
- * For backward compatibility, also matches the legacy pattern `{prefix}-{N}`
- * (worktrees from prior batches without operator IDs), but only when `opId`
- * is `"op"` (the default fallback), to avoid capturing other operators' resources.
+ * For backward compatibility, also matches the legacy flat pattern `{prefix}-{opId}-{N}`
+ * and (when opId is "op") `{prefix}-{N}`. This supports transition from old naming.
  *
  * Lane number is extracted from the path basename pattern. Entries with
  * malformed/partial data (missing path, unparseable lane number) are
@@ -1056,12 +1194,15 @@ export function preserveBranch(
  * @param prefix   - Worktree directory prefix (e.g. "taskplane-wt")
  * @param repoRoot - Absolute path to the main repository root
  * @param opId     - Operator identifier for scoping (e.g., "henrylach")
+ * @param batchId  - Optional batch ID for batch-scoped filtering; when provided,
+ *                   only returns worktrees inside the `{opId}-{batchId}/` container
  * @returns        - WorktreeInfo[] sorted by laneNumber (ascending)
  */
-export function listWorktrees(prefix: string, repoRoot: string, opId: string): WorktreeInfo[] {
+export function listWorktrees(prefix: string, repoRoot: string, opId: string, batchId?: string): WorktreeInfo[] {
 	const entries = parseWorktreeList(repoRoot);
 	const results: WorktreeInfo[] = [];
 
+	// ── Legacy flat patterns ─────────────────────────────────────
 	// Primary pattern: {prefix}-{opId}-{N}
 	// Example: "taskplane-wt-henrylach-1"
 	const primaryPattern = new RegExp(`^${escapeRegex(prefix)}-${escapeRegex(opId)}-(\\d+)$`);
@@ -1072,27 +1213,60 @@ export function listWorktrees(prefix: string, repoRoot: string, opId: string): W
 		? new RegExp(`^${escapeRegex(prefix)}-(\\d+)$`)
 		: null;
 
+	// ── New batch-scoped nested pattern ──────────────────────────
+	// Basename: lane-{N}
+	// Parent directory: {opId}-{batchId} (e.g., "henrylach-20260308T111750")
+	// Full: {basePath}/{opId}-{batchId}/lane-{N}
+	const nestedLanePattern = /^lane-(\d+)$/;
+	// When batchId is provided, match only the exact container for batch isolation.
+	// When omitted, match any container belonging to this operator (all batches).
+	const containerPattern = batchId
+		? new RegExp(`^${escapeRegex(generateBatchContainerName(opId, batchId))}$`)
+		: new RegExp(`^${escapeRegex(opId)}-\\S+$`);
+
 	for (const entry of entries) {
 		if (!entry.path) continue;
 
-		// Extract basename from the worktree path
-		const entryBasename = basename(resolve(entry.path));
-
-		// Try primary pattern first
-		let match = entryBasename.match(primaryPattern);
-		if (!match && legacyPattern) {
-			match = entryBasename.match(legacyPattern);
+		const resolvedPath = resolve(entry.path);
+		const entryBasename = basename(resolvedPath);
+
+		// ── Try new nested pattern first ─────────────────────────
+		const nestedMatch = entryBasename.match(nestedLanePattern);
+		if (nestedMatch) {
+			// Verify the parent directory matches the container pattern
+			const parentDir = basename(resolve(resolvedPath, ".."));
+			if (containerPattern.test(parentDir)) {
+				const laneNumber = parseInt(nestedMatch[1], 10);
+				if (!isNaN(laneNumber) && laneNumber >= 1) {
+					results.push({
+						path: resolvedPath,
+						branch: entry.branch || "",
+						laneNumber,
+					});
+					continue;
+				}
+			}
 		}
-		if (!match) continue;
 
-		const laneNumber = parseInt(match[1], 10);
-		if (isNaN(laneNumber) || laneNumber < 1) continue;
-
-		results.push({
-			path: resolve(entry.path),
-			branch: entry.branch || "",
-			laneNumber,
-		});
+		// ── Try legacy flat patterns (only when not batch-scoped) ─
+		// When batchId is provided, skip legacy matching — the caller
+		// explicitly wants only this batch's worktrees.
+		if (!batchId) {
+			let match = entryBasename.match(primaryPattern);
+			if (!match && legacyPattern) {
+				match = entryBasename.match(legacyPattern);
+			}
+			if (match) {
+				const laneNumber = parseInt(match[1], 10);
+				if (!isNaN(laneNumber) && laneNumber >= 1) {
+					results.push({
+						path: resolvedPath,
+						branch: entry.branch || "",
+						laneNumber,
+					});
+				}
+			}
+		}
 	}
 
 	// Sort by laneNumber ascending (deterministic output)
@@ -1305,10 +1479,22 @@ export function ensureLaneWorktrees(
  * When `targetBranch` is provided, branches with unmerged commits are
  * preserved as `saved/<branch>` refs instead of being force-deleted.
  *
+ * **Batch-scoped cleanup:** When `batchId` is provided, only removes
+ * worktrees inside the specific batch container `{opId}-{batchId}/`.
+ * After removing all worktrees, attempts to remove the empty container
+ * directory. When `batchId` is omitted, removes all operator worktrees
+ * (all batches, including legacy flat-layout).
+ *
+ * **Container cleanup:** After per-worktree removals, each touched batch
+ * container directory is checked and removed if empty. Non-empty containers
+ * (from partial failures or active worktrees) are left intact.
+ *
  * @param prefix       - Worktree directory prefix (e.g. "taskplane-wt")
  * @param repoRoot     - Absolute path to the main repository root
  * @param opId         - Operator identifier for scoping (e.g., "henrylach")
  * @param targetBranch - Optional target branch for unmerged commit detection (e.g. "develop")
+ * @param batchId      - Optional batch ID for batch-scoped cleanup
+ * @param config       - Optional orchestrator config (needed for container path resolution when batchId is provided)
  * @returns            - RemoveAllWorktreesResult with per-worktree outcomes
  */
 export function removeAllWorktrees(
@@ -1316,8 +1502,10 @@ export function removeAllWorktrees(
 	repoRoot: string,
 	opId: string,
 	targetBranch?: string,
+	batchId?: string,
+	config?: OrchestratorConfig,
 ): RemoveAllWorktreesResult {
-	const worktrees = listWorktrees(prefix, repoRoot, opId);
+	const worktrees = listWorktrees(prefix, repoRoot, opId, batchId);
 	const outcomes: RemoveWorktreeOutcome[] = [];
 	const removed: WorktreeInfo[] = [];
 	const failed: RemoveWorktreeOutcome[] = [];
@@ -1360,6 +1548,30 @@ export function removeAllWorktrees(
 		}
 	}
 
+	// ── Container cleanup ────────────────────────────────────────
+	// After removing worktrees, attempt to remove empty batch container
+	// directories. Collect unique container paths from removed worktrees,
+	// then remove each one only if empty (partial failure safety).
+	const containerPaths = new Set<string>();
+	for (const wt of removed) {
+		const parentDir = resolve(wt.path, "..");
+		// Only consider directories that look like batch containers
+		// (i.e., parent is not the base worktree path itself)
+		const parentName = basename(parentDir);
+		if (parentName.startsWith(`${opId}-`)) {
+			containerPaths.add(parentDir);
+		}
+	}
+	// When batchId is explicitly provided, also add the expected container path
+	// even if no worktrees were found (cleanup of empty containers from prior runs)
+	if (batchId && config) {
+		const expectedContainer = generateBatchContainerPath(opId, batchId, repoRoot, config);
+		containerPaths.add(expectedContainer);
+	}
+	for (const containerPath of containerPaths) {
+		removeBatchContainerIfEmpty(containerPath);
+	}
+
 	return {
 		totalAttempted: worktrees.length,
 		removed,
@@ -1754,5 +1966,19 @@ export function forceCleanupWorktree(
 			});
 		}
 	}
+
+	// Step 4: Attempt to remove the batch container directory if empty
+	// The worktree path is {basePath}/{opId}-{batchId}/lane-{N}, so the
+	// container is the parent directory.
+	const containerDir = resolve(worktreePath, "..");
+	const containerName = basename(containerDir);
+	// Only attempt container cleanup if the parent looks like a batch container
+	// (contains a hyphen, indicating {opId}-{batchId} naming)
+	if (containerName.includes("-")) {
+		const containerRemoved = removeBatchContainerIfEmpty(containerDir);
+		if (containerRemoved) {
+			execLog("cleanup", `lane-${laneNumber}`, `removed empty batch container`, { path: containerDir });
+		}
+	}
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskplane",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "AI agent orchestration for pi — parallel task execution with checkpoint discipline",
   "keywords": [
     "pi-package",