@tmustier/pi-agent-teams 0.5.3 → 0.5.5

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.5.5] - 2026-05-07
+
+### Changed
+- Update Pi package imports, peer dependencies, and development dependencies to the new `@earendil-works` namespace.
+
+## 0.5.4
+
+### Fixes
+
+- **Clean branch-mode worker sessions** — teammates spawned with `contextMode=branch` now branch from the last stable pre-turn boundary, replay the active user request, preserve compaction entries, and materialize user-only fallbacks. This prevents workers from inheriting the leader's in-progress tool-use turn or reopening as blank sessions. (#35, #36)
+- **Accurate quality-gate completion notices** — leader completion and batch-complete messages now mention running quality gates only when hooks are actually enabled, instead of inferring that from the presence of an internal enqueue callback. (#37)
+
 ## 0.5.3
 
 ### Fixes

package/extensions/teams/activity-tracker.ts

@@ -1,4 +1,4 @@
-import type { AgentEvent } from "@mariozechner/pi-agent-core";
+import type { AgentEvent } from "@earendil-works/pi-agent-core";
 
 // ── Helpers ──
 
@@ -15,134 +15,6 @@ export type TranscriptEntry =
 	| { kind: "turn_end"; turnNumber: number; tokens: number; timestamp: number };
 
 const MAX_TRANSCRIPT = 200;
-const MAX_SUMMARY_LENGTH = 120;
-
-// ── Tool content summarization ──
-
-function truncateSummary(text: string): string {
-	if (text.length <= MAX_SUMMARY_LENGTH) return text;
-	return `${text.slice(0, MAX_SUMMARY_LENGTH - 1)}…`;
-}
-
-function summarizeToolArgs(toolName: string, args: unknown): string {
-	if (!isRecord(args)) return "";
-	const key = toolName.toLowerCase();
-
-	if (key === "read" || key === "write") {
-		const path = typeof args.path === "string" ? args.path : null;
-		if (!path) return "";
-		return truncateSummary(path);
-	}
-
-	if (key === "edit") {
-		const path = typeof args.path === "string" ? args.path : null;
-		if (!path) return "";
-		return truncateSummary(path);
-	}
-
-	if (key === "bash") {
-		const cmd = typeof args.command === "string" ? args.command : null;
-		if (!cmd) return "";
-		return truncateSummary(cmd.replace(/\s+/g, " ").trim());
-	}
-
-	if (key === "grep" || key === "glob") {
-		const pattern = typeof args.pattern === "string" ? args.pattern : null;
-		const path = typeof args.path === "string" ? args.path : null;
-		const parts: string[] = [];
-		if (pattern) parts.push(pattern);
-		if (path) parts.push(`in ${path}`);
-		return truncateSummary(parts.join(" "));
-	}
-
-	if (key === "webfetch" || key === "websearch") {
-		const url = typeof args.url === "string" ? args.url : null;
-		const query = typeof args.query === "string" ? args.query : null;
-		return truncateSummary(url ?? query ?? "");
-	}
-
-	if (key === "team_message") {
-		const recipient = typeof args.recipient === "string" ? args.recipient : null;
-		const message = typeof args.message === "string" ? args.message : null;
-		if (recipient && message) return truncateSummary(`→ ${recipient}: ${message.replace(/\s+/g, " ").trim()}`);
-		if (message) return truncateSummary(message.replace(/\s+/g, " ").trim());
-		return recipient ? truncateSummary(`→ ${recipient}`) : "";
-	}
-
-	if (key === "task" || key === "teams") {
-		const action = typeof args.action === "string" ? args.action : null;
-		return action ? truncateSummary(action) : "";
-	}
-
-	// Fallback: try to find a meaningful first-string arg
-	for (const v of Object.values(args)) {
-		if (typeof v === "string" && v.length > 0) return truncateSummary(v);
-	}
-	return "";
-}
-
-/**
- * Extract the first text content from a ToolResultMessage-shaped result.
- * The agent-loop emits `{ content: [{type: "text", text: "..."}], ... }`.
- */
-function extractContentText(result: Record<string, unknown>): string | null {
-	const content = result.content;
-	if (!Array.isArray(content)) return null;
-	for (const item of content) {
-		if (isRecord(item) && item.type === "text" && typeof item.text === "string") {
-			return item.text;
-		}
-	}
-	return null;
-}
-
-function summarizeToolResult(toolName: string, result: unknown, isError: boolean): string {
-	if (isError) {
-		if (typeof result === "string") return truncateSummary(result.replace(/\s+/g, " ").trim());
-		if (isRecord(result)) {
-			// Try content array first (ToolResultMessage shape)
-			const contentText = extractContentText(result);
-			if (contentText !== null) {
-				const trimmed = contentText.replace(/\s+/g, " ").trim();
-				return trimmed.length > 0 ? truncateSummary(trimmed) : "error";
-			}
-			const msg = typeof result.message === "string"
-				? result.message
-				: typeof result.error === "string"
-					? result.error
-					: null;
-			if (msg) return truncateSummary(msg.replace(/\s+/g, " ").trim());
-		}
-		return "error";
-	}
-
-	if (typeof result === "string") {
-		const compact = result.replace(/\s+/g, " ").trim();
-		if (compact.length === 0) return "(empty)";
-		return truncateSummary(compact);
-	}
-
-	if (isRecord(result)) {
-		// Try content array first (ToolResultMessage shape from agent-loop)
-		const contentText = extractContentText(result);
-		if (contentText !== null) {
-			const compact = contentText.replace(/\s+/g, " ").trim();
-			if (compact.length === 0) return "(empty)";
-			return truncateSummary(compact);
-		}
-		// Fallback: check for common structured result shapes
-		const status = typeof result.status === "string" ? result.status : null;
-		if (status) return truncateSummary(status);
-		const output = typeof result.output === "string" ? result.output : null;
-		if (output) return truncateSummary(output.replace(/\s+/g, " ").trim());
-	}
-
-	if (Array.isArray(result)) {
-		return `${String(result.length)} items`;
-	}
-
-	return "";
-}
 
 export class TranscriptLog {
 	private entries: TranscriptEntry[] = [];

package/extensions/teams/index.ts

@@ -1,4 +1,4 @@
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { runLeader } from "./leader.js";
 import { runWorker } from "./worker.js";
 

package/extensions/teams/leader-attach-commands.ts

@@ -1,4 +1,4 @@
-import type { ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { getTeamDir } from "./paths.js";
 import {
 	acquireTeamAttachClaim,

package/extensions/teams/leader-inbox.ts

@@ -1,4 +1,4 @@
-import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { popUnreadMessages, writeToMailbox } from "./mailbox.js";
 import { sanitizeName } from "./names.js";
 import {
@@ -91,12 +91,14 @@ export async function pollLeaderInbox(opts: {
 	style: TeamsStyle;
 	pendingPlanApprovals: Map<string, { requestId: string; name: string; taskId?: string }>;
 	enqueueHook?: (invocation: TeamsHookInvocation) => void;
+	hooksEnabled?: boolean;
 	sendLeaderLlmMessage?: SendLeaderLlmMessage;
 	/** Batch delegation tracker for all-tasks-complete auto-notify. */
 	delegationTracker?: DelegationTracker;
 }): Promise<void> {
-	const { ctx, teamId, teamDir, taskListId, leadName, style, pendingPlanApprovals, enqueueHook, sendLeaderLlmMessage, delegationTracker } = opts;
+	const { ctx, teamId, teamDir, taskListId, leadName, style, pendingPlanApprovals, enqueueHook, hooksEnabled, sendLeaderLlmMessage, delegationTracker } = opts;
 	const strings = getTeamsStrings(style);
+	const hooksActive = hooksEnabled ?? Boolean(enqueueHook);
 
 	let msgs: Awaited<ReturnType<typeof popUnreadMessages>>;
 	try {
@@ -173,38 +175,42 @@ export async function pollLeaderInbox(opts: {
 			const name = sanitizeName(idle.from);
 
 			// Hook: always emit "idle" (best-effort, non-blocking)
-			try {
-				enqueueHook?.({
-					event: "idle",
-					teamId,
-					teamDir,
-					taskListId,
-					style,
-					memberName: name,
-					timestamp: idle.timestamp,
-					completedTask: null,
-				});
-			} catch {
-				// ignore hook enqueue errors
-			}
-
-			// Hook: task completion / failure
-			if (idle.completedTaskId) {
-				const completedTask = await getTask(teamDir, taskListId, idle.completedTaskId);
+			if (hooksActive) {
 				try {
 					enqueueHook?.({
-						event: idle.completedStatus === "failed" ? "task_failed" : "task_completed",
+						event: "idle",
 						teamId,
 						teamDir,
 						taskListId,
 						style,
 						memberName: name,
 						timestamp: idle.timestamp,
-						completedTask,
+						completedTask: null,
 					});
 				} catch {
 					// ignore hook enqueue errors
 				}
+			}
+
+			// Hook: task completion / failure
+			if (idle.completedTaskId) {
+				const completedTask = await getTask(teamDir, taskListId, idle.completedTaskId);
+				if (hooksActive) {
+					try {
+						enqueueHook?.({
+							event: idle.completedStatus === "failed" ? "task_failed" : "task_completed",
+							teamId,
+							teamDir,
+							taskListId,
+							style,
+							memberName: name,
+							timestamp: idle.timestamp,
+							completedTask,
+						});
+					} catch {
+						// ignore hook enqueue errors
+					}
+				}
 
 				// Event-driven batch tracking: mark this task done and
 				// collect any batches that became fully complete.
@@ -319,7 +325,7 @@ export async function pollLeaderInbox(opts: {
 
 						if (allDone) {
 							lines.push("");
-							if (enqueueHook) {
+							if (hooksActive) {
 								// Hooks run asynchronously and may reopen tasks or create follow-ups.
 								lines.push(`All ${totalTasks} task(s) show completed — quality gates are still running and may change task states.`);
 							} else {
@@ -354,7 +360,7 @@ export async function pollLeaderInbox(opts: {
 	if (sendLeaderLlmMessage) {
 		for (const batch of batchCompletions) {
 			const taskRefs = batch.taskIds.map((id) => `#${id}`).join(", ");
-			const suffix = enqueueHook
+			const suffix = hooksActive
 				? "Quality gates are still running and may change task states."
 				: "Review the results and continue.";
 			const msg = `[Team] All delegated tasks completed (${taskRefs}). ${suffix}`;

package/extensions/teams/leader-info-commands.ts

@@ -1,4 +1,4 @@
-import type { ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { sanitizeName } from "./names.js";
 import { getTeamDir, getTeamsRootDir } from "./paths.js";
 import type { TeammateRpc } from "./teammate-rpc.js";

package/extensions/teams/leader-lifecycle-commands.ts

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type { ExtensionCommandContext, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { cleanupTeamDir, gcStaleTeamDirs } from "./cleanup.js";
 import { writeToMailbox } from "./mailbox.js";
 import { sanitizeName } from "./names.js";

package/extensions/teams/leader-messaging-commands.ts

@@ -1,4 +1,4 @@
-import type { ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { writeToMailbox } from "./mailbox.js";
 import { sanitizeName } from "./names.js";
 import { getTeamDir } from "./paths.js";

package/extensions/teams/leader-plan-commands.ts

@@ -1,4 +1,4 @@
-import type { ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { writeToMailbox } from "./mailbox.js";
 import { sanitizeName } from "./names.js";
 import { getTeamDir } from "./paths.js";

package/extensions/teams/leader-spawn-command.ts

@@ -1,5 +1,5 @@
-import type { ThinkingLevel } from "@mariozechner/pi-agent-core";
-import type { ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { pickAgentNames, pickNamesFromPool } from "./names.js";
 import type { TeammateRpc } from "./teammate-rpc.js";
 import type { TeamsStyle } from "./teams-style.js";

package/extensions/teams/leader-task-commands.ts

@@ -1,5 +1,5 @@
 import * as path from "node:path";
-import type { ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { writeToMailbox } from "./mailbox.js";
 import { sanitizeName } from "./names.js";
 import { getTeamDir } from "./paths.js";

package/extensions/teams/leader-team-command.ts

@@ -1,4 +1,4 @@
-import type { ExtensionCommandContext, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { getTeamDir } from "./paths.js";
 import {
 	handleTeamEnvCommand,

package/extensions/teams/leader-teams-tool.ts

@@ -1,8 +1,7 @@
 import { randomUUID } from "node:crypto";
-import type { AgentToolResult } from "@mariozechner/pi-agent-core";
-import { StringEnum } from "@mariozechner/pi-ai";
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import { Type, type Static } from "@sinclair/typebox";
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { writeToMailbox } from "./mailbox.js";
 import { pickAgentNames, pickNamesFromPool, sanitizeName } from "./names.js";
 import { getTeamDir } from "./paths.js";
@@ -52,7 +51,14 @@ function describeModelSource(source: TeammateModelSource): string {
 	return "teammate-default";
 }
 
-const TeamsActionSchema = StringEnum(
+function stringEnum<const Values extends readonly [string, ...string[]]>(
+	values: Values,
+	options: Record<string, unknown> = {},
+) {
+	return Type.Unsafe<Values[number]>({ type: "string", enum: [...values], ...options });
+}
+
+const TeamsActionSchema = stringEnum(
 	[
 		"delegate",
 		"task_assign",
@@ -83,30 +89,30 @@ const TeamsActionSchema = StringEnum(
 	},
 );
 
-const TeamsTaskStatusSchema = StringEnum(["pending", "in_progress", "completed"] as const, {
+const TeamsTaskStatusSchema = stringEnum(["pending", "in_progress", "completed"] as const, {
 	description: "Task status for action=task_set_status.",
 });
 
-const TeamsContextModeSchema = StringEnum(["fresh", "branch"] as const, {
+const TeamsContextModeSchema = stringEnum(["fresh", "branch"] as const, {
 	description: "How to initialize comrade session context. 'branch' clones the leader session branch.",
 	default: "fresh",
 });
 
-const TeamsWorkspaceModeSchema = StringEnum(["shared", "worktree"] as const, {
+const TeamsWorkspaceModeSchema = stringEnum(["shared", "worktree"] as const, {
 	description: "Workspace isolation mode. 'shared' matches Claude Teams; 'worktree' creates a git worktree per comrade.",
 	default: "shared",
 });
 
-const TeamsThinkingLevelSchema = StringEnum(["off", "minimal", "low", "medium", "high", "xhigh"] as const, {
+const TeamsThinkingLevelSchema = stringEnum(["off", "minimal", "low", "medium", "high", "xhigh"] as const, {
 	description:
 		"Thinking level to use for spawned comrades (defaults to the leader's current thinking level when omitted).",
 });
 
-const TeamsHookFailureActionSchema = StringEnum(["warn", "followup", "reopen", "reopen_followup"] as const, {
+const TeamsHookFailureActionSchema = stringEnum(["warn", "followup", "reopen", "reopen_followup"] as const, {
 	description: "Hook failure policy for hooks_policy_set.",
 });
 
-const TeamsHookFollowupOwnerSchema = StringEnum(["member", "lead", "none"] as const, {
+const TeamsHookFollowupOwnerSchema = stringEnum(["member", "lead", "none"] as const, {
 	description: "Follow-up owner policy for hooks_policy_set.",
 });
 

package/extensions/teams/leader.ts

@@ -1,8 +1,8 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@mariozechner/pi-coding-agent";
-import { SessionManager } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
 import { writeToMailbox } from "./mailbox.js";
 import { sanitizeName } from "./names.js";
 import { TEAM_MAILBOX_NS, taskAssignmentPayload } from "./protocol.js";
@@ -22,6 +22,7 @@ import { getTeamsStyleFromEnv, type TeamsStyle, formatMemberDisplayName, getTeam
 import { DelegationTracker, pollLeaderInbox as pollLeaderInboxImpl } from "./leader-inbox.js";
 import {
 	getHookBaseName,
+	areTeamsHooksEnabled,
 	getTeamsHookFailureAction,
 	getTeamsHookFollowupOwnerPolicy,
 	getTeamsHookMaxReopensPerTask,
@@ -34,6 +35,7 @@ import {
 import { handleTeamCommand } from "./leader-team-command.js";
 import { registerTeamsTool } from "./leader-teams-tool.js";
 import { getParentSessionId, shouldSilenceInheritedParentAttachClaimWarning } from "./session-parent.js";
+import { branchSelectionNote, ensureSessionFileMaterialized, resolveBranchLeafSelection } from "./session-branching.js";
 import type { ContextMode, SpawnTeammateFn, SpawnTeammateResult, WorkspaceMode } from "./spawn-types.js";
 
 function getTeamsExtensionEntryPath(): string | null {
@@ -90,12 +92,17 @@ async function createSessionForTeammate(
 
 	try {
 		const sm = SessionManager.open(parentSessionFile, teamSessionsDir);
-		const branched = sm.createBranchedSession(leafId);
+		const selection = resolveBranchLeafSelection(sm.getBranch(leafId), leafId);
+		const branched = sm.createBranchedSession(selection.leafId);
 		if (!branched) {
 			const fallback = SessionManager.create(ctx.cwd, teamSessionsDir);
 			return { sessionFile: fallback.getSessionFile(), note: "branch(failed->fresh)", warnings };
 		}
-		return { sessionFile: branched, note: "branch", warnings };
+		if (selection.replayUserMessage) {
+			sm.appendMessage(JSON.parse(JSON.stringify(selection.replayUserMessage)) as Parameters<typeof sm.appendMessage>[0]);
+		}
+		await ensureSessionFileMaterialized(sm, branched);
+		return { sessionFile: branched, note: branchSelectionNote(selection), warnings };
 	} catch (err) {
 		const msg = err instanceof Error ? err.message : String(err);
 		if (/Entry .* not found/i.test(msg)) {
@@ -702,6 +709,7 @@ export function runLeader(pi: ExtensionAPI): void {
 			style,
 			pendingPlanApprovals,
 			enqueueHook,
+			hooksEnabled: areTeamsHooksEnabled(process.env),
 			sendLeaderLlmMessage: (content, options) => {
 				pi.sendUserMessage(content, options);
 			},
@@ -778,78 +786,6 @@ export function runLeader(pi: ExtensionAPI): void {
 		inboxTimer.unref?.();
 	});
 
-	pi.on("session_switch", async (_event, ctx) => {
-		const prevTeamId = currentTeamId;
-		const prevCwd = currentCtx?.cwd;
-
-		if (currentCtx) {
-			await releaseActiveAttachClaim(currentCtx);
-			const strings = getTeamsStrings(style);
-			await stopAllTeammates(currentCtx, `The ${strings.teamNoun} is dissolved — leader moved on`);
-		}
-		stopLoops();
-		delegationTracker.clear();
-
-		// Clean up worktrees from the old session before switching.
-		// Only clean up teams this session owns — never attached teams.
-		const prevSessionId = currentCtx?.sessionManager.getSessionId();
-		if (prevTeamId && prevTeamId === prevSessionId) {
-			const teamDir = getTeamDir(prevTeamId);
-			try {
-				await cleanupWorktrees({ teamDir, teamId: prevTeamId, repoCwd: prevCwd });
-			} catch {
-				// Best-effort — don't block session switch.
-			}
-		}
-
-		currentCtx = ctx;
-		currentTeamId = currentCtx.sessionManager.getSessionId();
-		inheritedParentTeamId = getParentSessionId(currentCtx.sessionManager);
-		// Keep the task list aligned with the active session. If you want a shared namespace,
-		// use `/team task use <taskListId>` after switching.
-		taskListId = currentTeamId;
-		lastAttachClaimHeartbeatMs = 0;
-		// Clear any /team done suppression — new session context.
-		widgetSuppressed = false;
-		autoDoneNotified = false;
-
-		await ensureTeamConfig(getTeamDir(currentTeamId), {
-			teamId: currentTeamId,
-			taskListId: taskListId,
-			leadName: "team-lead",
-			style,
-		});
-
-		await refreshTasks();
-		renderWidget();
-
-		// Restart background refresh/poll loops for the new session.
-		refreshTimer = setInterval(async () => {
-			if (isStopping) return;
-			if (refreshInFlight) return;
-			refreshInFlight = true;
-			try {
-				await heartbeatActiveAttachClaim(ctx);
-				await refreshTasks();
-				renderWidget();
-			} finally {
-				refreshInFlight = false;
-			}
-		}, 1000);
-		refreshTimer.unref?.();
-
-		inboxTimer = setInterval(async () => {
-			if (isStopping) return;
-			if (inboxInFlight) return;
-			inboxInFlight = true;
-			try {
-				await pollLeaderInbox();
-			} finally {
-				inboxInFlight = false;
-			}
-		}, 700);
-		inboxTimer.unref?.();
-	});
 
 	pi.on("session_shutdown", async () => {
 		if (!currentCtx) return;

package/extensions/teams/paths.ts

@@ -1,5 +1,5 @@
 import * as path from "node:path";
-import { getAgentDir } from "@mariozechner/pi-coding-agent";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
 /**
  * Root directory for all team artifacts (config, sessions, mailboxes, tasks).

package/extensions/teams/session-branching.ts

@@ -0,0 +1,133 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { SessionEntry, SessionManager } from "@earendil-works/pi-coding-agent";
+
+export type BranchLeafSelection = {
+	leafId: string;
+	adjusted: boolean;
+	reason: "requested" | "clean-turn-replay" | "clean-turn-stable" | "clean-turn-user";
+	replayUserMessage?: UserMessageLike;
+};
+
+type MessageLike = Record<string, unknown> & { role: string };
+type UserMessageLike = MessageLike & { role: "user"; content: unknown; timestamp: number };
+
+type MessageEntryLike = SessionEntry & {
+	type: "message";
+	message: MessageLike;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function isMessageEntry(entry: SessionEntry): entry is MessageEntryLike {
+	if (entry.type !== "message") return false;
+	return isRecord(entry.message) && typeof entry.message.role === "string";
+}
+
+function isUserMessageEntry(entry: SessionEntry): entry is MessageEntryLike & { message: UserMessageLike } {
+	return isMessageEntry(entry) && entry.message.role === "user";
+}
+
+function isAssistantToolUseEntry(entry: SessionEntry): entry is MessageEntryLike & { message: MessageLike & { role: "assistant"; stopReason: "toolUse" } } {
+	return (
+		isMessageEntry(entry) &&
+		entry.message.role === "assistant" &&
+		typeof entry.message.stopReason === "string" &&
+		entry.message.stopReason === "toolUse"
+	);
+}
+
+function isStableAssistantEntry(entry: SessionEntry): entry is MessageEntryLike & { message: MessageLike & { role: "assistant" } } {
+	return (
+		isMessageEntry(entry) &&
+		entry.message.role === "assistant" &&
+		typeof entry.message.stopReason === "string" &&
+		entry.message.stopReason !== "toolUse"
+	);
+}
+
+/**
+ * When the leader is mid-turn, the current leaf may point into an unfinished
+ * assistant/tool-use path. Branching from that leaf causes workers to inherit
+ * the leader's in-progress turn instead of a clean conversation context.
+ *
+ * In that case, branch from the last stable turn boundary instead:
+ * - Prefer the latest completed assistant message (persists as a real branched file)
+ * - Otherwise fall back to the latest user message
+ */
+export function resolveBranchLeafSelection(path: SessionEntry[], requestedLeafId: string): BranchLeafSelection {
+	const lastAssistantIndex = [...path].map((entry, index) => ({ entry, index }))
+		.reverse()
+		.find(({ entry }) => isMessageEntry(entry) && entry.message.role === "assistant")?.index;
+
+	if (lastAssistantIndex === undefined) {
+		return { leafId: requestedLeafId, adjusted: false, reason: "requested" };
+	}
+
+	const lastAssistant = path[lastAssistantIndex];
+	if (!lastAssistant || !isAssistantToolUseEntry(lastAssistant)) {
+		return { leafId: requestedLeafId, adjusted: false, reason: "requested" };
+	}
+
+	let latestUserIndex = -1;
+	let latestUserBeforeActiveTurn: UserMessageLike | undefined;
+	for (let i = lastAssistantIndex - 1; i >= 0; i -= 1) {
+		const candidate = path[i];
+		if (!candidate) continue;
+		if (isUserMessageEntry(candidate)) {
+			latestUserIndex = i;
+			latestUserBeforeActiveTurn = candidate.message;
+			break;
+		}
+	}
+
+	if (latestUserIndex > 0 && latestUserBeforeActiveTurn) {
+		const boundary = path[latestUserIndex - 1];
+		if (boundary) {
+			return {
+				leafId: boundary.id,
+				adjusted: boundary.id !== requestedLeafId,
+				reason: "clean-turn-replay",
+				replayUserMessage: latestUserBeforeActiveTurn,
+			};
+		}
+	}
+
+	for (let i = lastAssistantIndex - 1; i >= 0; i -= 1) {
+		const candidate = path[i];
+		if (!candidate) continue;
+		if (isStableAssistantEntry(candidate)) {
+			return {
+				leafId: candidate.id,
+				adjusted: candidate.id !== requestedLeafId,
+				reason: "clean-turn-stable",
+			};
+		}
+		if (isUserMessageEntry(candidate)) {
+			return { leafId: candidate.id, adjusted: candidate.id !== requestedLeafId, reason: "clean-turn-user" };
+		}
+	}
+
+	return { leafId: requestedLeafId, adjusted: false, reason: "requested" };
+}
+
+export async function ensureSessionFileMaterialized(
+	sm: Pick<SessionManager, "getHeader" | "getEntries">,
+	sessionFile: string,
+): Promise<void> {
+	if (fs.existsSync(sessionFile)) return;
+	const header = sm.getHeader();
+	if (!header) return;
+	await fs.promises.mkdir(path.dirname(sessionFile), { recursive: true });
+	const lines = [JSON.stringify(header), ...sm.getEntries().map((entry) => JSON.stringify(entry))].join("\n") + "\n";
+	await fs.promises.writeFile(sessionFile, lines, "utf8");
+}
+
+export function branchSelectionNote(selection: BranchLeafSelection): string {
+	if (!selection.adjusted) return "branch";
+	if (selection.reason === "clean-turn-replay" || selection.reason === "clean-turn-stable") return "branch(clean-turn)";
+	if (selection.reason === "clean-turn-user") return "branch(clean-turn:user-fallback)";
+	return "branch";
+}