@nseng-ai/ccc 0.1.1

package/package.json

@@ -0,0 +1,48 @@
+{
+	"name": "@nseng-ai/ccc",
+	"version": "0.1.1",
+	"type": "module",
+	"files": [
+		"src"
+	],
+	"engines": {
+		"node": ">=24.12.0",
+		"pnpm": ">=11.8.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"bin": {
+		"ccc": "src/ns/cli.ts"
+	},
+	"exports": {
+		".": "./src/api/index.ts",
+		"./api": "./src/api/handlers.ts",
+		"./autoslot": "./src/ns/autoslot.ts",
+		"./cli": "./src/ns/cli.ts",
+		"./land": "./src/ns/land.ts",
+		"./trunk-pull": "./src/ns/trunk-pull.ts",
+		"./pi": "./src/pi/index.ts",
+		"./pi/extension": "./src/pi/extension.ts"
+	},
+	"dependencies": {
+		"@nseng-ai/branch-context": "0.1.1",
+		"@nseng-ai/capability-kit": "0.1.1",
+		"@nseng-ai/clinkr": "0.1.1",
+		"@nseng-ai/foundation": "0.1.1",
+		"@nseng-ai/flow": "0.1.1",
+		"@nseng-ai/ns": "0.1.1",
+		"@nseng-ai/objectives": "0.1.1",
+		"@nseng-ai/plans": "0.1.1",
+		"@nseng-ai/slots": "0.1.1",
+		"zod": "^4.4.3"
+	},
+	"peerDependencies": {
+		"@nseng-ai/pi": "*"
+	},
+	"peerDependenciesMeta": {
+		"@nseng-ai/pi": {
+			"optional": true
+		}
+	}
+}

package/src/api/handlers.ts

@@ -0,0 +1,75 @@
+export { CCC_PACKAGE_IDENTITY } from "./index.ts";
+
+// Canonical ns:ccc:* command surface names
+export {
+	CCC_CLAUDE_PLAN_TAB_COMMAND_NAME,
+	CCC_COMMAND_NAMES,
+	CCC_SIDEBAR_BRANCH_STATE_SUMMARY_COMMAND_NAME,
+	CCC_SIDEBAR_OBJECTIVE_SUMMARY_COMMAND_NAME,
+	CCC_SIDEBAR_SESSION_SUMMARY_COMMAND_NAME,
+	CCC_SURFACE_DISPATCH_PLAN_COMMAND_NAME,
+	CCC_WORKSPACE_DISPATCH_FROM_TRUNK_COMMAND_NAME,
+	CCC_WORKSPACE_DISPATCH_PLAN_COMMAND_NAME,
+	CCC_WORKSPACE_DISPATCH_PROMPT_COMMAND_NAME,
+	CCC_WORKSPACE_OPEN_BRANCH_COMMAND_NAME,
+} from "../cmux/command-surfaces.ts";
+
+// Dispatch prompt
+export {
+	handleCccSlotDispatchPrompt,
+	resolveDispatchPromptPayloadOptions,
+	type DispatchPromptPayloadOptions,
+	type HandleCccSlotDispatchPromptOptions,
+} from "../cmux/dispatch-prompt.ts";
+
+// Claude plan tab
+export {
+	handleCccClaudePlanTab,
+	extractLastAssistantText,
+	buildClaudePlanTabTitle,
+	buildClaudePlanLaunchCommand,
+} from "../cmux/claude-plan-tab.ts";
+
+// Prompt file utilities
+export {
+	resolvePromptFileOptions,
+	writeTimestampedPromptFile,
+	type PromptFileOptions,
+	type ResolvedPromptFileOptions,
+} from "../cmux/prompt-file.ts";
+
+// Dispatch from trunk
+export {
+	handleCccSlotDispatchFromTrunk,
+	createTrackedBranchFromTrunkForPrompt,
+} from "../cmux/dispatch-from-trunk.ts";
+
+// Slot open branch
+export {
+	handleCccSlotOpenBranch,
+	getBranchCompletions,
+	extractCommandArgumentPrefix,
+	type HandleCccSlotOpenBranchOptions,
+	type CccSlotOpenBranchOptions,
+} from "../cmux/slot-open-branch.ts";
+
+// Slot dispatch plan
+export {
+	handleCccSlotDispatchPlan,
+	type CccSlotDispatchPlanOptions,
+	type DispatchPlanConfig,
+	type DispatchDestination,
+} from "../cmux/slot-dispatch-plan.ts";
+
+// Sidebar
+export {
+	createCccSidebarController,
+	getCallerWorkspaceId,
+	buildCmuxSessionSidebarPrompt,
+	buildCmuxBranchStateSidebarPrompt,
+	type CccSidebarController,
+	type ObjectiveSidebarHandlerOptions,
+} from "../cmux/sidebar.ts";
+
+// Slot client
+export type { SlotClient } from "@nseng-ai/slots/api";

package/src/api/index.ts

@@ -0,0 +1,11 @@
+export const CCC_PACKAGE_IDENTITY = {
+	packageName: "@nseng-ai/ccc",
+	vocabularyName: "CCC",
+	expandedName: "Cmux Command and Control",
+	visibility: "private-workspace",
+	ownedConcerns: [
+		"cmux-workspace-orchestration",
+		"graphite-stack-orchestration",
+		"worktree-flow-coordination",
+	],
+} as const;

package/src/cmux/branch-slug.ts

@@ -0,0 +1,174 @@
+import {
+	finalizeBranchSlug,
+	MAX_BRANCH_SLUG_LENGTH,
+	sanitizeBranchName,
+	trimBranchSlugToLength,
+} from "@nseng-ai/foundation/branch-slug";
+import type { TextResult } from "@nseng-ai/foundation/primitives";
+import type { ExtensionAPI } from "@nseng-ai/capability-kit/cmux/types";
+
+export { finalizeBranchSlug, MAX_BRANCH_SLUG_LENGTH, sanitizeBranchName, trimBranchSlugToLength };
+
+const GPT_NANO_PROVIDER = "openai";
+const GPT_NANO_MODEL = "gpt-5.4-nano";
+const SLUG_PROMPT_TIMEOUT_MS = 60_000;
+const SUMMARY_PROMPT_TIMEOUT_MS = 60_000;
+const MAX_SLUG_INPUT_CHARS = 12_000;
+const MAX_SUMMARY_INPUT_CHARS = 16_000;
+
+export type BranchSlugContentKind = "task" | "plan";
+
+type BranchSlugRuntime = Pick<ExtensionAPI, "exec">;
+
+export async function generateBranchSlug(
+	pi: BranchSlugRuntime,
+	cwd: string,
+	input: {
+		kind: BranchSlugContentKind;
+		content: string;
+		sourceLabel?: string;
+		fallbackText?: string;
+	},
+): Promise<TextResult> {
+	const prompt = buildSlugPrompt(input);
+	const result = await runGptNanoText(pi, cwd, prompt, SLUG_PROMPT_TIMEOUT_MS);
+	if (!result.ok) {
+		return {
+			ok: false,
+			message: `Could not generate branch slug with GPT Nano: ${result.message}`,
+		};
+	}
+
+	const slug =
+		sanitizeBranchName(result.text) || sanitizeBranchName(input.fallbackText ?? input.content);
+	if (!slug) {
+		return { ok: false, message: "Could not derive a usable branch slug." };
+	}
+
+	return { ok: true, text: slug };
+}
+
+export async function summarizePlanWithGptNano(
+	pi: BranchSlugRuntime,
+	cwd: string,
+	input: {
+		content: string;
+		sourceLabel?: string;
+	},
+): Promise<TextResult> {
+	const result = await runGptNanoText(
+		pi,
+		cwd,
+		buildPlanSummaryPrompt(input),
+		SUMMARY_PROMPT_TIMEOUT_MS,
+	);
+	if (!result.ok) {
+		return { ok: false, message: `Could not summarize plan with GPT Nano: ${result.message}` };
+	}
+
+	const summary = stripResponseFence(result.text).trim();
+	if (!summary) {
+		return { ok: false, message: "GPT Nano did not return a usable bullet summary." };
+	}
+	return { ok: true, text: summary };
+}
+
+async function runGptNanoText(
+	pi: BranchSlugRuntime,
+	cwd: string,
+	prompt: string,
+	timeout: number,
+): Promise<TextResult> {
+	const result = await pi.exec("pi", buildGptNanoTextArgs(prompt), { cwd, timeout });
+	if (result.code !== 0) {
+		const details = result.stderr.trim() || result.stdout.trim();
+		return { ok: false, message: details };
+	}
+	return { ok: true, text: result.stdout.trim() };
+}
+
+export function buildGptNanoTextArgs(prompt: string): string[] {
+	return [
+		"--provider",
+		GPT_NANO_PROVIDER,
+		"--model",
+		GPT_NANO_MODEL,
+		"--thinking",
+		"low",
+		"--no-session",
+		"--no-extensions",
+		"--no-skills",
+		"--no-prompt-templates",
+		"--no-context-files",
+		"--no-tools",
+		"--mode",
+		"text",
+		"--print",
+		prompt,
+	];
+}
+
+export function buildSlugPrompt(input: {
+	kind: BranchSlugContentKind;
+	content: string;
+	sourceLabel?: string;
+}): string {
+	const kindDescription =
+		input.kind === "plan"
+			? "an implementation plan that will be stashed on a new branch"
+			: "a user task prompt that will run in a new branch workspace";
+	const contentLabel = input.sourceLabel ? `Source: ${input.sourceLabel}` : undefined;
+
+	return [
+		"Generate a concise git branch slug for this work item.",
+		`The content is ${kindDescription}.`,
+		"Infer the actual code/product change or outcome. Do not name the document, prompt, plan, context, storage workflow, or how this work item was initiated.",
+		"Ignore metadata and provenance such as saved-plan filenames, source labels, suggested slugs, objective-next output, branch-create handoff text, and brmem storage details.",
+		"If a command name appears only because it generated or initiated the plan, do not include it. Include command/product names only when the proposed work directly changes that command/product.",
+		"Rules:",
+		"- Return only the slug, with no quotes, markdown, or explanation.",
+		"- Use kebab-case: lowercase ASCII words separated by hyphens.",
+		`- Keep it at or under ${MAX_BRANCH_SLUG_LENGTH} characters.`,
+		"- Lead with a verb when natural, such as add-, fix-, refactor-, migrate-, rename-, remove-, or update-.",
+		"- Do not use spaces, underscores, slashes, punctuation, or special characters.",
+		"- Do not include generic suffixes like -plan, -prompt, -context, -branch, -task, or -suggestion unless they are the real feature name.",
+		"- Prefer concrete deliverables and specific nouns from the work item over broad words like changes, cleanup, or improvements.",
+		"",
+		contentLabel,
+		"Content:",
+		truncateForPrompt(input.content, MAX_SLUG_INPUT_CHARS),
+	]
+		.filter((line): line is string => line !== undefined)
+		.join("\n");
+}
+
+function buildPlanSummaryPrompt(input: { content: string; sourceLabel?: string }): string {
+	const contentLabel = input.sourceLabel ? `Source: ${input.sourceLabel}` : undefined;
+	return [
+		"Summarize this implementation plan for display after it is persisted on a branch.",
+		"Return only 3 to 5 markdown bullet lines.",
+		"Each bullet must start with '- '. No heading, intro, code fence, or closing prose.",
+		"Focus on concrete implementation work, important scope boundaries, and validation steps.",
+		"Do not mention that the plan was stashed, persisted, saved, or stored.",
+		"",
+		contentLabel,
+		"Plan:",
+		truncateForPrompt(input.content, MAX_SUMMARY_INPUT_CHARS),
+	]
+		.filter((line): line is string => line !== undefined)
+		.join("\n");
+}
+
+function truncateForPrompt(text: string, maxChars: number): string {
+	if (text.length <= maxChars) {
+		return text;
+	}
+	return `${text.slice(0, maxChars)}\n...[truncated]`;
+}
+
+function stripResponseFence(value: string): string {
+	return value
+		.replace(/^```[a-zA-Z0-9_-]*\n?/, "")
+		.replace(/\n?```$/, "")
+		.trim();
+}

package/src/cmux/claude-plan-tab.ts

@@ -0,0 +1,124 @@
+import { formatShellArg } from "@nseng-ai/foundation/command";
+import { formatErrorMessage } from "@nseng-ai/foundation/primitives";
+import {
+	launchFocusedCmuxTab,
+	type FocusedCmuxTabLaunchResult,
+} from "@nseng-ai/capability-kit/cmux/focused-terminal-tab";
+import { isRecord, stringField } from "@nseng-ai/foundation/primitives";
+import { writeTimestampedPromptFile, type ResolvedPromptFileOptions } from "./prompt-file.ts";
+import type { CommandContext, ExtensionAPI } from "@nseng-ai/capability-kit/cmux/types";
+
+const TITLE_PREFIX = "claude-plan: ";
+const MAX_TITLE_SEED_CHARS = 40;
+
+export async function handleCccClaudePlanTab(options: {
+	pi: ExtensionAPI;
+	ctx: CommandContext;
+	args: string;
+	promptOptions: ResolvedPromptFileOptions;
+}): Promise<void> {
+	const { pi, ctx, promptOptions } = options;
+	await ctx.waitForIdle();
+
+	const seed = resolveClaudePlanSeed(ctx, options.args);
+	if (seed === undefined) {
+		ctx.ui.notify("No assistant message found in this session to use as a seed plan.", "error");
+		return;
+	}
+
+	let promptFile: string;
+	try {
+		promptFile = await writeTimestampedPromptFile({
+			...promptOptions,
+			stem: "claude-plan",
+			content: seed,
+		});
+	} catch (error) {
+		ctx.ui.notify(`Failed to write Claude plan prompt file: ${formatErrorMessage(error)}`, "error");
+		return;
+	}
+
+	const launched = await launchFocusedCmuxTab({
+		host: pi,
+		cwd: ctx.cwd,
+		tabTitle: buildClaudePlanTabTitle(seed),
+		command: buildClaudePlanLaunchCommand(promptFile),
+		signal: undefined,
+	});
+	if (launched.type === "failed") {
+		ctx.ui.notify(launched.message, "error");
+		return;
+	}
+
+	ctx.ui.notify(formatClaudePlanTabLaunchSuccess(launched, promptFile), "info");
+}
+
+export function extractLastAssistantText(entries: unknown[]): string | undefined {
+	for (let index = entries.length - 1; index >= 0; index -= 1) {
+		const entry = entries[index];
+		if (!isRecord(entry) || entry.type !== "message" || !isRecord(entry.message)) continue;
+		if (stringField(entry.message, "role") !== "assistant") continue;
+
+		return textFromAssistantMessage(entry.message);
+	}
+
+	return undefined;
+}
+
+export function buildClaudePlanLaunchCommand(promptFilePath: string): string {
+	return `claude --permission-mode plan "$(cat ${formatShellArg(promptFilePath)})"`;
+}
+
+function resolveClaudePlanSeed(ctx: CommandContext, args: string): string | undefined {
+	if (args.trim().length > 0) return args;
+
+	const entries = ctx.sessionManager?.getBranch?.() ?? ctx.sessionManager?.getEntries?.() ?? [];
+	return extractLastAssistantText(entries);
+}
+
+export function buildClaudePlanTabTitle(seed: string): string {
+	const firstLine = seed
+		.split(/\r?\n/)
+		.map((line) => line.trim())
+		.find((line) => line.length > 0);
+	const titleSeed = truncateTitleSeed(firstLine ?? "seed plan");
+	return `${TITLE_PREFIX}${titleSeed}`;
+}
+
+function formatClaudePlanTabLaunchSuccess(
+	result: Extract<FocusedCmuxTabLaunchResult, { type: "launched" }>,
+	promptFile: string,
+): string {
+	return [
+		"Opened Claude plan tab.",
+		`Tab title: ${result.tabTitle}`,
+		`Surface: ${result.surfaceId}`,
+		`Workspace: ${result.workspaceId}`,
+		`Prompt file: ${promptFile}`,
+		`Command: ${result.command}`,
+	].join("\n");
+}
+
+function textFromAssistantMessage(message: Record<string, unknown>): string | undefined {
+	const text = textFromAssistantContent(message.content);
+	if (text === undefined) return undefined;
+	if (text.trim().length === 0) return undefined;
+	return text;
+}
+
+function textFromAssistantContent(content: unknown): string | undefined {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return undefined;
+	return content.map(textFromContentBlock).join("");
+}
+
+function textFromContentBlock(block: unknown): string {
+	if (!isRecord(block) || stringField(block, "type") !== "text") return "";
+	return stringField(block, "text") ?? "";
+}
+
+function truncateTitleSeed(seed: string): string {
+	const chars = Array.from(seed);
+	if (chars.length <= MAX_TITLE_SEED_CHARS) return seed;
+	return `${chars.slice(0, MAX_TITLE_SEED_CHARS - 1).join("")}…`;
+}

package/src/cmux/command-surfaces.ts

@@ -0,0 +1,51 @@
+import { nsCommandSurface } from "@nseng-ai/foundation/command";
+
+// Canonical catalog of ns:ccc:* command surfaces. Pi command registration and
+// cmux extension commands share these names; import from here instead of
+// spelling out raw `ns:ccc:*` literals.
+
+export const CCC_WORKSPACE_DISPATCH_PLAN_COMMAND_NAME = nsCommandSurface(
+	"ccc",
+	"workspace:dispatch-plan",
+);
+export const CCC_SURFACE_DISPATCH_PLAN_COMMAND_NAME = nsCommandSurface(
+	"ccc",
+	"surface:dispatch-plan",
+);
+export const CCC_WORKSPACE_OPEN_BRANCH_COMMAND_NAME = nsCommandSurface(
+	"ccc",
+	"workspace:open-branch",
+);
+export const CCC_WORKSPACE_DISPATCH_PROMPT_COMMAND_NAME = nsCommandSurface(
+	"ccc",
+	"workspace:dispatch-prompt",
+);
+export const CCC_WORKSPACE_DISPATCH_FROM_TRUNK_COMMAND_NAME = nsCommandSurface(
+	"ccc",
+	"workspace:dispatch-from-trunk",
+);
+export const CCC_CLAUDE_PLAN_TAB_COMMAND_NAME = nsCommandSurface("ccc", "claude-plan-tab");
+export const CCC_SIDEBAR_SESSION_SUMMARY_COMMAND_NAME = nsCommandSurface(
+	"ccc",
+	"sidebar:session-summary",
+);
+export const CCC_SIDEBAR_BRANCH_STATE_SUMMARY_COMMAND_NAME = nsCommandSurface(
+	"ccc",
+	"sidebar:branch-state-summary",
+);
+export const CCC_SIDEBAR_OBJECTIVE_SUMMARY_COMMAND_NAME = nsCommandSurface(
+	"ccc",
+	"sidebar:objective-summary",
+);
+
+export const CCC_COMMAND_NAMES = [
+	CCC_CLAUDE_PLAN_TAB_COMMAND_NAME,
+	CCC_SIDEBAR_BRANCH_STATE_SUMMARY_COMMAND_NAME,
+	CCC_SIDEBAR_OBJECTIVE_SUMMARY_COMMAND_NAME,
+	CCC_SIDEBAR_SESSION_SUMMARY_COMMAND_NAME,
+	CCC_SURFACE_DISPATCH_PLAN_COMMAND_NAME,
+	CCC_WORKSPACE_DISPATCH_FROM_TRUNK_COMMAND_NAME,
+	CCC_WORKSPACE_DISPATCH_PLAN_COMMAND_NAME,
+	CCC_WORKSPACE_DISPATCH_PROMPT_COMMAND_NAME,
+	CCC_WORKSPACE_OPEN_BRANCH_COMMAND_NAME,
+] as const;

package/src/cmux/dispatch-from-trunk.ts

@@ -0,0 +1,177 @@
+import {
+	commandSucceeded,
+	execApiToCommandRunner,
+	formatCommand,
+	formatCommandFailure,
+	piExecApiToCommandExecApi,
+} from "@nseng-ai/foundation/command";
+import { firstNonEmptyLine } from "@nseng-ai/foundation/text-normalization";
+import {
+	planLocalBranchRefreshFromWorktrees,
+	type LocalBranchRefreshPlan,
+} from "@nseng-ai/capability-kit/git";
+import { runGraphiteCommand } from "@nseng-ai/capability-kit/graphite/branch";
+import { optionalEntry } from "@nseng-ai/foundation/primitives";
+
+import { CCC_WORKSPACE_DISPATCH_FROM_TRUNK_COMMAND_NAME } from "./command-surfaces.ts";
+import {
+	buildLaunchPrompt,
+	createTrackedBranchFromResolvedParent,
+	dispatchTrackedBranchPrompt,
+	resolveDispatchPromptPayloadOptions,
+	runText,
+	type BranchCreateResult,
+} from "./dispatch-prompt.ts";
+import type { SlotClient } from "@nseng-ai/slots/api";
+import type { CommandContext, ExtensionAPI } from "@nseng-ai/capability-kit/cmux/types";
+
+const COMMAND_NAME = CCC_WORKSPACE_DISPATCH_FROM_TRUNK_COMMAND_NAME;
+const GIT_TRUNK_REFRESH_TIMEOUT_MS = 2 * 60 * 1000;
+const TRUNK_DISPATCH_CONTEXT_NOTE =
+	"This branch was created from refreshed Graphite trunk and is intentionally unrelated to the caller's current stack.";
+
+export async function handleCccSlotDispatchFromTrunk(options: {
+	pi: Pick<ExtensionAPI, "exec" | "getThinkingLevel">;
+	payloadOptions: ReturnType<typeof resolveDispatchPromptPayloadOptions>;
+	args: string;
+	ctx: CommandContext;
+	slotClient?: SlotClient;
+	notifyProgress: (message: string) => void;
+}): Promise<void> {
+	const { pi, payloadOptions, args, ctx } = options;
+	const prompt = args.trim();
+	if (prompt.length === 0) {
+		ctx.ui.notify(`Usage: /${COMMAND_NAME} <prompt>`, "error");
+		return;
+	}
+
+	options.notifyProgress("Resolving Graphite trunk…");
+	await ctx.waitForIdle();
+	const branch = await createTrackedBranchFromTrunkForPrompt({
+		pi,
+		cwd: ctx.cwd,
+		prompt,
+		notify: options.notifyProgress,
+	});
+	if ("error" in branch) {
+		ctx.ui.notify(branch.error, "error");
+		return;
+	}
+
+	await dispatchTrackedBranchPrompt({
+		pi,
+		ctx,
+		branch,
+		content: buildLaunchPrompt(prompt, TRUNK_DISPATCH_CONTEXT_NOTE),
+		description: `dispatch-from-trunk from ${branch.parentBranch}`,
+		payloadOptions,
+		...optionalEntry("slotClient", options.slotClient),
+		notifyProgress: options.notifyProgress,
+	});
+}
+
+export async function createTrackedBranchFromTrunkForPrompt(options: {
+	pi: Pick<ExtensionAPI, "exec">;
+	cwd: string;
+	prompt: string;
+	notify?: (message: string) => void;
+}): Promise<BranchCreateResult | { error: string }> {
+	const { pi, cwd, prompt, notify } = options;
+	notify?.("Resolving Graphite trunk…");
+	const trunk = await runGraphiteCommand(execApiToCommandRunner(piExecApiToCommandExecApi(pi)), {
+		cwd,
+		args: ["trunk", "--no-interactive"],
+	});
+	if (!commandSucceeded(trunk)) {
+		return {
+			error: formatCommandFailure(
+				"Could not resolve Graphite trunk.",
+				"gt trunk --no-interactive",
+				trunk,
+			),
+		};
+	}
+	const trunkBranch = firstNonEmptyLine(trunk.stdout);
+	if (trunkBranch === undefined) {
+		return { error: "gt trunk --no-interactive returned no branch." };
+	}
+
+	notify?.("Refreshing Graphite trunk…");
+	const refresh = await refreshLocalTrunkBranch({ pi, cwd, trunkBranch });
+	if (!refresh.ok) {
+		return {
+			error: [
+				`Graphite trunk refresh failed for ${trunkBranch}; no branch was created.`,
+				refresh.message,
+			].join("\n"),
+		};
+	}
+
+	const startPoint = await runText(pi, cwd, "git", ["rev-parse", trunkBranch]);
+	if (!startPoint.ok) {
+		return { error: `Could not resolve refreshed trunk ${trunkBranch}: ${startPoint.message}` };
+	}
+
+	notify?.("Generating branch name…");
+	return createTrackedBranchFromResolvedParent({
+		pi,
+		cwd,
+		prompt,
+		parentBranch: trunkBranch,
+		startPoint: startPoint.text,
+		startRef: trunkBranch,
+		createFailureContext: `from refreshed trunk ${trunkBranch}`,
+	});
+}
+
+async function refreshLocalTrunkBranch(options: {
+	pi: Pick<ExtensionAPI, "exec">;
+	cwd: string;
+	trunkBranch: string;
+}): Promise<{ ok: true } | { ok: false; message: string }> {
+	const { pi, cwd, trunkBranch } = options;
+	const worktrees = await pi.exec("git", ["worktree", "list", "--porcelain"], {
+		cwd,
+		timeout: GIT_TRUNK_REFRESH_TIMEOUT_MS,
+	});
+	if (!commandSucceeded(worktrees)) {
+		return {
+			ok: false,
+			message: formatCommandFailure(
+				"Could not inspect Git worktrees.",
+				"git worktree list --porcelain",
+				worktrees,
+			),
+		};
+	}
+
+	const plan = planLocalBranchRefreshFromWorktrees({
+		branch: trunkBranch,
+		cwd,
+		worktreePorcelain: worktrees.stdout,
+	});
+	const refresh = await pi.exec("git", plan.args, {
+		cwd: plan.cwd,
+		timeout: GIT_TRUNK_REFRESH_TIMEOUT_MS,
+	});
+	if (commandSucceeded(refresh)) return { ok: true };
+	return {
+		ok: false,
+		message: [
+			formatCommandFailure(
+				formatTrunkRefreshFailureTitle(plan, trunkBranch),
+				formatCommand("git", plan.args),
+				refresh,
+			),
+			`Cwd: ${plan.cwd}`,
+		].join("\n"),
+	};
+}
+
+function formatTrunkRefreshFailureTitle(plan: LocalBranchRefreshPlan, trunkBranch: string): string {
+	if (plan.type === "pull-checked-out-branch") {
+		return `Could not pull checked-out trunk branch ${trunkBranch}.`;
+	}
+
+	return `Could not fetch trunk branch ${trunkBranch}.`;
+}