@snappedly-tools/shipyard 0.6.0 → 0.7.0-staging.36082887921

package/dist/sandboxes/docker.d.ts

@@ -1,5 +1,4 @@
-import { I as IsolatedSandboxProvider } from '../SandboxProvider-XJQqEdSf.js';
-import { M as MountConfig } from '../MountConfig-bZoCs4Dd.js';
+import { M as MountConfig, I as IsolatedSandboxProvider } from '../MountConfig-BHnKnA4h.js';
 
 /**
  * Shared mount utilities for the Docker sandbox provider.
@@ -16,7 +15,6 @@ import { M as MountConfig } from '../MountConfig-bZoCs4Dd.js';
  * - `false` — disable labeling entirely.
  */
 type SelinuxLabel = "z" | "Z" | false;
-
 /**
  * Derive the default image name from the repo directory.
  * Returns `shipyard:<dir-name>` where dir-name is the last path segment,

package/dist/sandboxes/docker.js

@@ -1,6 +1,4 @@
-export { docker } from '../chunk-WAXEMZUV.js';
-export { defaultImageName } from '../chunk-FDYOTN55.js';
-import '../chunk-KMGNFXKN.js';
-import '../chunk-ACD46ZM4.js';
+export { defaultImageName, docker } from '../chunk-44I2BL6E.js';
+import '../chunk-L6PX5QTU.js';
 //# sourceMappingURL=docker.js.map
 //# sourceMappingURL=docker.js.map

package/dist/templates/parallel-planner/main.mts

@@ -5,9 +5,59 @@ import { existsSync } from "node:fs";
 import * as shipyard from "@snappedly-tools/shipyard";
 import { docker } from "@snappedly-tools/shipyard/sandboxes/docker";
 import { z } from "zod";
+import { resolvePlannerBranch } from "./planner-branch.mjs";
 
 if (process.loadEnvFile && existsSync(".shipyard/.env"))
   process.loadEnvFile(".shipyard/.env");
+type ModelRole = "routine" | "strong";
+const CODEX_PROVIDER = true;
+const agentFactory = shipyard.codex;
+type AgentModel = Parameters<typeof agentFactory>[0];
+const readRoleModel = (role: ModelRole): string | undefined => {
+  const envName = `SHIPYARD_${role.toUpperCase()}_MODEL`;
+  const model = process.env[envName];
+  if (model !== undefined && model.trim().length === 0)
+    throw new Error(`${envName} must not be empty`);
+  return model;
+};
+const roleModels = {
+  routine: readRoleModel("routine"),
+  strong: readRoleModel("strong"),
+};
+const CODEX_REASONING_EFFORTS = shipyard.CODEX_REASONING_EFFORTS;
+type CodexReasoningEffort = shipyard.CodexReasoningEffort;
+const readCodexReasoningEffort = (
+  role: ModelRole,
+): CodexReasoningEffort | undefined => {
+  if (!CODEX_PROVIDER) return undefined;
+  const envName = `SHIPYARD_CODEX_${role.toUpperCase()}_REASONING_EFFORT`;
+  const effort = process.env[envName]?.trim();
+  if (!effort) return undefined;
+  if (!(CODEX_REASONING_EFFORTS as readonly string[]).includes(effort))
+    throw new Error(
+      `${envName} must be one of ${CODEX_REASONING_EFFORTS.join(", ")}; received "${effort}"`,
+    );
+  return effort as CodexReasoningEffort;
+};
+const roleEfforts = {
+  routine: readCodexReasoningEffort("routine"),
+  strong: readCodexReasoningEffort("strong"),
+};
+const readCodexRoleModel = (role: ModelRole, defaultModel: AgentModel) => {
+  if (!CODEX_PROVIDER || typeof defaultModel === "string") return defaultModel;
+  const envName = `SHIPYARD_CODEX_${role.toUpperCase()}_MODEL`;
+  const model = process.env[envName]?.trim();
+  return model ? { ...defaultModel, model } : defaultModel;
+};
+const roleAgent = (role: ModelRole, defaultModel: AgentModel) => {
+  const model = roleModels[role] ?? readCodexRoleModel(role, defaultModel);
+  const effort = roleEfforts[role];
+  if (typeof model !== "string")
+    return effort === undefined
+      ? agentFactory(model)
+      : agentFactory(model, { effort });
+  return agentFactory(model, { effort: effort ?? null });
+};
 const targetBranch = execFileSync("git", ["branch", "--show-current"], {
   encoding: "utf8",
 }).trim();
@@ -114,7 +164,7 @@ const runWorker = async (scope: Scope, ticket: Ticket) => {
     await sandbox.run({
       name: `triage #${ticket.id}`,
       maxIterations: 1,
-      agent: shipyard.codex(shipyard.CODEX_MODELS.strong),
+      agent: roleAgent("routine", shipyard.CODEX_MODELS.routine),
       promptFile: "./.shipyard/triage-prompt.md",
       promptArgs: { TASK_ID: ticket.id },
     });
@@ -122,7 +172,7 @@ const runWorker = async (scope: Scope, ticket: Ticket) => {
     const implementation = await sandbox.run({
       name: "implementer",
       maxIterations: 100,
-      agent: shipyard.codex(shipyard.CODEX_MODELS.routine),
+      agent: roleAgent("routine", shipyard.CODEX_MODELS.routine),
       promptFile: "./.shipyard/implement-prompt.md",
       promptArgs: {
         TASK_ID: ticket.id,
@@ -143,13 +193,21 @@ for (let iteration = 0; iteration < 10; iteration++) {
     execFileSync("node", [".shipyard/select-issues.mjs"], { encoding: "utf8" }),
   ) as Scope[];
   if (!scopes.length) break;
+  const localBranches = execFileSync(
+    "git",
+    ["for-each-ref", "--format=%(refname:short)", "refs/heads"],
+    { encoding: "utf8" },
+  )
+    .split(/\r?\n/)
+    .filter(Boolean);
+  const plannerBranch = await resolvePlannerBranch(localBranches);
   const plan = await shipyard.run({
     hooks,
     sandbox: docker(),
     name: "planner",
-    branchStrategy: { type: "branch", branch: "shipyard/planner" },
+    branchStrategy: { type: "branch", branch: plannerBranch },
     maxIterations: 1,
-    agent: shipyard.codex(shipyard.CODEX_MODELS.strong),
+    agent: roleAgent("strong", shipyard.CODEX_MODELS.strong),
     promptFile: "./.shipyard/plan-prompt.md",
     output: shipyard.Output.object({ tag: "plan", schema: planSchema }),
   });
@@ -277,7 +335,7 @@ for (let iteration = 0; iteration < 10; iteration++) {
                     const resolution = await wave.run({
                       name: "conflict-resolver",
                       maxIterations: 10,
-                      agent: shipyard.codex(shipyard.CODEX_MODELS.strong),
+                      agent: roleAgent("strong", shipyard.CODEX_MODELS.strong),
                       promptFile: "./.shipyard/conflict-prompt.md",
                       promptArgs: {
                         TASK_ID: ready[index]!.id,
@@ -331,7 +389,7 @@ for (let iteration = 0; iteration < 10; iteration++) {
               const integrated = await wave.run({
                 name: "spec-integrator",
                 maxIterations: 10,
-                agent: shipyard.codex(shipyard.CODEX_MODELS.strong),
+                agent: roleAgent("strong", shipyard.CODEX_MODELS.strong),
                 promptFile: "./.shipyard/spec-wave-prompt.md",
                 promptArgs: {
                   TASK_ID: id,
@@ -371,7 +429,7 @@ for (let iteration = 0; iteration < 10; iteration++) {
             await integration.run({
               name: `triage #${id}`,
               maxIterations: 1,
-              agent: shipyard.codex(shipyard.CODEX_MODELS.strong),
+              agent: roleAgent("routine", shipyard.CODEX_MODELS.routine),
               promptFile: "./.shipyard/triage-prompt.md",
               promptArgs: { TASK_ID: id },
             });
@@ -379,7 +437,7 @@ for (let iteration = 0; iteration < 10; iteration++) {
             const standalone = await integration.run({
               name: "implementer",
               maxIterations: 100,
-              agent: shipyard.codex(shipyard.CODEX_MODELS.routine),
+              agent: roleAgent("routine", shipyard.CODEX_MODELS.routine),
               promptFile: "./.shipyard/implement-prompt.md",
               promptArgs: {
                 TASK_ID: id,
@@ -393,7 +451,7 @@ for (let iteration = 0; iteration < 10; iteration++) {
           const final = await integration.run({
             name: "merger",
             maxIterations: 1,
-            agent: shipyard.codex(shipyard.CODEX_MODELS.strong),
+            agent: roleAgent("strong", shipyard.CODEX_MODELS.strong),
             promptFile: "./.shipyard/merge-prompt.md",
             promptArgs: {
               TASK_ID: id,

package/dist/templates/parallel-planner/planner-branch.mts

@@ -0,0 +1,151 @@
+import { execFileSync } from "node:child_process";
+import { createInterface } from "node:readline/promises";
+
+const PLANNER_BRANCH = "shipyard/planner";
+
+type BranchPrompt = (message: string) => Promise<string>;
+
+const askInTerminal: BranchPrompt = async (message) => {
+  const readline = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  try {
+    return await readline.question(message);
+  } finally {
+    readline.close();
+  }
+};
+
+const refsConflict = (left: string, right: string): boolean =>
+  left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
+
+const nextPlannerBranch = (localBranches: readonly string[]): string => {
+  for (let suffix = 2; ; suffix++) {
+    for (const candidate of [
+      `${PLANNER_BRANCH}-${suffix}`,
+      `shipyard-planner-${suffix}`,
+    ]) {
+      if (!localBranches.some((branch) => refsConflict(candidate, branch)))
+        return candidate;
+    }
+  }
+};
+
+const reusablePlannerBranch = (
+  localBranches: readonly string[],
+): string | undefined => {
+  const candidates = localBranches
+    .map((branch) => ({
+      branch,
+      suffix: /^(?:shipyard\/planner-|shipyard-planner-)(\d+)$/.exec(
+        branch,
+      )?.[1],
+    }))
+    .filter((candidate) => candidate.suffix !== undefined)
+    .sort((left, right) => Number(left.suffix) - Number(right.suffix));
+
+  return candidates.find(({ branch }) =>
+    localBranches.every(
+      (other) => other === branch || !refsConflict(branch, other),
+    ),
+  )?.branch;
+};
+
+export const resolvePlannerBranch = async (
+  localBranches: readonly string[],
+  options: {
+    isInteractive?: boolean;
+    ask?: BranchPrompt;
+    checkedOutBranches?: readonly string[];
+    mergedBranches?: readonly string[];
+    deleteBranches?: (branches: readonly string[]) => void;
+  } = {},
+): Promise<string> => {
+  const conflicts = localBranches.filter((branch) =>
+    refsConflict(PLANNER_BRANCH, branch),
+  );
+  if (conflicts.length === 0) return PLANNER_BRANCH;
+
+  const reusable = reusablePlannerBranch(localBranches);
+  if (reusable) return reusable;
+
+  const alternate = nextPlannerBranch(localBranches);
+
+  const conflictList = conflicts.map((branch) => `  - ${branch}`).join("\n");
+  const context =
+    `Planner branch '${PLANNER_BRANCH}' conflicts with local branch refs:\n${conflictList}\n` +
+    `Git cannot create both names. The listed local branches will be kept unless you choose deletion.`;
+  const isInteractive =
+    options.isInteractive ??
+    Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  if (!isInteractive) {
+    throw new Error(
+      `${context}\nRerun in an interactive terminal to keep them and use '${alternate}', or request local deletion after Git checks that they are merged and not checked out. No branches were changed.`,
+    );
+  }
+
+  const checkedOutBranches = new Set(
+    options.checkedOutBranches ??
+      execFileSync("git", ["worktree", "list", "--porcelain"], {
+        encoding: "utf8",
+      })
+        .split(/\r?\n/)
+        .filter((line) => line.startsWith("branch refs/heads/"))
+        .map((line) => line.slice("branch refs/heads/".length)),
+  );
+  const mergedBranches = new Set(
+    options.mergedBranches ??
+      execFileSync(
+        "git",
+        ["branch", "--merged", "HEAD", "--format=%(refname:short)"],
+        { encoding: "utf8" },
+      )
+        .split(/\r?\n/)
+        .filter(Boolean),
+  );
+  const branchesSafeToDelete = conflicts.every(
+    (branch) => !checkedOutBranches.has(branch) && mergedBranches.has(branch),
+  );
+  const unsafeDeleteReasons = conflicts.flatMap((branch) => {
+    if (checkedOutBranches.has(branch))
+      return [`'${branch}' is checked out in a worktree`];
+    if (!mergedBranches.has(branch))
+      return [`'${branch}' has commits not merged into HEAD`];
+    return [];
+  });
+
+  const ask = options.ask ?? askInTerminal;
+  const answer = await ask(
+    `${context}\n[Y] Keep them and use '${alternate}' (recommended)\n` +
+      `[d] Delete these local branches and use '${PLANNER_BRANCH}'${
+        branchesSafeToDelete
+          ? ""
+          : ` (unavailable: ${unsafeDeleteReasons.join("; ")})`
+      }\n` +
+      `[n] Abort without changes\nChoose [Y/d/n]: `,
+  );
+  const choice = answer.trim().toLowerCase();
+  if (choice === "" || choice === "y" || choice === "yes") return alternate;
+  if (choice === "d" || choice === "delete") {
+    if (!branchesSafeToDelete) {
+      throw new Error(
+        `Cannot safely delete the conflicting branches: ${unsafeDeleteReasons.join("; ")}. No branches were changed. Use '${alternate}' or inspect the listed refs manually.`,
+      );
+    }
+    const deleteBranches =
+      options.deleteBranches ??
+      ((branches: readonly string[]) => {
+        for (const branch of branches)
+          execFileSync("git", ["branch", "-d", branch], {
+            encoding: "utf8",
+          });
+      });
+    deleteBranches(conflicts);
+    return PLANNER_BRANCH;
+  }
+
+  throw new Error(
+    `Planner branch selection cancelled. No branches were changed. Inspect with 'git worktree list' and 'git branch --list "shipyard/planner*"', then rerun.`,
+  );
+};

package/dist/templates/parallel-planner-with-review/main.mts

@@ -5,9 +5,59 @@ import { existsSync } from "node:fs";
 import * as shipyard from "@snappedly-tools/shipyard";
 import { docker } from "@snappedly-tools/shipyard/sandboxes/docker";
 import { z } from "zod";
+import { resolvePlannerBranch } from "./planner-branch.mjs";
 
 if (process.loadEnvFile && existsSync(".shipyard/.env"))
   process.loadEnvFile(".shipyard/.env");
+type ModelRole = "routine" | "strong";
+const CODEX_PROVIDER = true;
+const agentFactory = shipyard.codex;
+type AgentModel = Parameters<typeof agentFactory>[0];
+const readRoleModel = (role: ModelRole): string | undefined => {
+  const envName = `SHIPYARD_${role.toUpperCase()}_MODEL`;
+  const model = process.env[envName];
+  if (model !== undefined && model.trim().length === 0)
+    throw new Error(`${envName} must not be empty`);
+  return model;
+};
+const roleModels = {
+  routine: readRoleModel("routine"),
+  strong: readRoleModel("strong"),
+};
+const CODEX_REASONING_EFFORTS = shipyard.CODEX_REASONING_EFFORTS;
+type CodexReasoningEffort = shipyard.CodexReasoningEffort;
+const readCodexReasoningEffort = (
+  role: ModelRole,
+): CodexReasoningEffort | undefined => {
+  if (!CODEX_PROVIDER) return undefined;
+  const envName = `SHIPYARD_CODEX_${role.toUpperCase()}_REASONING_EFFORT`;
+  const effort = process.env[envName]?.trim();
+  if (!effort) return undefined;
+  if (!(CODEX_REASONING_EFFORTS as readonly string[]).includes(effort))
+    throw new Error(
+      `${envName} must be one of ${CODEX_REASONING_EFFORTS.join(", ")}; received "${effort}"`,
+    );
+  return effort as CodexReasoningEffort;
+};
+const roleEfforts = {
+  routine: readCodexReasoningEffort("routine"),
+  strong: readCodexReasoningEffort("strong"),
+};
+const readCodexRoleModel = (role: ModelRole, defaultModel: AgentModel) => {
+  if (!CODEX_PROVIDER || typeof defaultModel === "string") return defaultModel;
+  const envName = `SHIPYARD_CODEX_${role.toUpperCase()}_MODEL`;
+  const model = process.env[envName]?.trim();
+  return model ? { ...defaultModel, model } : defaultModel;
+};
+const roleAgent = (role: ModelRole, defaultModel: AgentModel) => {
+  const model = roleModels[role] ?? readCodexRoleModel(role, defaultModel);
+  const effort = roleEfforts[role];
+  if (typeof model !== "string")
+    return effort === undefined
+      ? agentFactory(model)
+      : agentFactory(model, { effort });
+  return agentFactory(model, { effort: effort ?? null });
+};
 const targetBranch = execFileSync("git", ["branch", "--show-current"], {
   encoding: "utf8",
 }).trim();
@@ -124,7 +174,7 @@ const runWorker = async (scope: Scope, ticket: Ticket) => {
     await sandbox.run({
       name: `triage #${ticket.id}`,
       maxIterations: 1,
-      agent: shipyard.codex(shipyard.CODEX_MODELS.strong),
+      agent: roleAgent("routine", shipyard.CODEX_MODELS.routine),
       promptFile: "./.shipyard/triage-prompt.md",
       promptArgs: { TASK_ID: ticket.id },
     });
@@ -132,7 +182,7 @@ const runWorker = async (scope: Scope, ticket: Ticket) => {
     const implementation = await sandbox.run({
       name: "implementer",
       maxIterations: 100,
-      agent: shipyard.codex(shipyard.CODEX_MODELS.routine),
+      agent: roleAgent("routine", shipyard.CODEX_MODELS.routine),
       promptFile: "./.shipyard/implement-prompt.md",
       promptArgs: {
         TASK_ID: ticket.id,
@@ -145,7 +195,7 @@ const runWorker = async (scope: Scope, ticket: Ticket) => {
     const review = await sandbox.run({
       name: "reviewer",
       maxIterations: 1,
-      agent: shipyard.codex(shipyard.CODEX_MODELS.strong),
+      agent: roleAgent("strong", shipyard.CODEX_MODELS.strong),
       promptFile: "./.shipyard/review-prompt.md",
       promptArgs: {
         TASK_ID: ticket.id,
@@ -166,13 +216,21 @@ for (let iteration = 0; iteration < 10; iteration++) {
     execFileSync("node", [".shipyard/select-issues.mjs"], { encoding: "utf8" }),
   ) as Scope[];
   if (!scopes.length) break;
+  const localBranches = execFileSync(
+    "git",
+    ["for-each-ref", "--format=%(refname:short)", "refs/heads"],
+    { encoding: "utf8" },
+  )
+    .split(/\r?\n/)
+    .filter(Boolean);
+  const plannerBranch = await resolvePlannerBranch(localBranches);
   const plan = await shipyard.run({
     hooks,
     sandbox: docker(),
     name: "planner",
-    branchStrategy: { type: "branch", branch: "shipyard/planner" },
+    branchStrategy: { type: "branch", branch: plannerBranch },
     maxIterations: 1,
-    agent: shipyard.codex(shipyard.CODEX_MODELS.strong),
+    agent: roleAgent("strong", shipyard.CODEX_MODELS.strong),
     promptFile: "./.shipyard/plan-prompt.md",
     output: shipyard.Output.object({ tag: "plan", schema: planSchema }),
   });
@@ -300,7 +358,7 @@ for (let iteration = 0; iteration < 10; iteration++) {
                     const resolution = await wave.run({
                       name: "conflict-resolver",
                       maxIterations: 10,
-                      agent: shipyard.codex(shipyard.CODEX_MODELS.strong),
+                      agent: roleAgent("strong", shipyard.CODEX_MODELS.strong),
                       promptFile: "./.shipyard/conflict-prompt.md",
                       promptArgs: {
                         TASK_ID: ready[index]!.id,
@@ -354,7 +412,7 @@ for (let iteration = 0; iteration < 10; iteration++) {
               const integrated = await wave.run({
                 name: "spec-integrator",
                 maxIterations: 10,
-                agent: shipyard.codex(shipyard.CODEX_MODELS.strong),
+                agent: roleAgent("strong", shipyard.CODEX_MODELS.strong),
                 promptFile: "./.shipyard/spec-wave-prompt.md",
                 promptArgs: {
                   TASK_ID: id,
@@ -394,7 +452,7 @@ for (let iteration = 0; iteration < 10; iteration++) {
             await integration.run({
               name: `triage #${id}`,
               maxIterations: 1,
-              agent: shipyard.codex(shipyard.CODEX_MODELS.strong),
+              agent: roleAgent("routine", shipyard.CODEX_MODELS.routine),
               promptFile: "./.shipyard/triage-prompt.md",
               promptArgs: { TASK_ID: id },
             });
@@ -402,7 +460,7 @@ for (let iteration = 0; iteration < 10; iteration++) {
             const standalone = await integration.run({
               name: "implementer",
               maxIterations: 100,
-              agent: shipyard.codex(shipyard.CODEX_MODELS.routine),
+              agent: roleAgent("routine", shipyard.CODEX_MODELS.routine),
               promptFile: "./.shipyard/implement-prompt.md",
               promptArgs: {
                 TASK_ID: id,
@@ -416,7 +474,7 @@ for (let iteration = 0; iteration < 10; iteration++) {
           const review = await integration.run({
             name: "reviewer",
             maxIterations: 1,
-            agent: shipyard.codex(shipyard.CODEX_MODELS.strong),
+            agent: roleAgent("strong", shipyard.CODEX_MODELS.strong),
             promptFile: "./.shipyard/review-prompt.md",
             promptArgs: {
               TASK_ID: id,
@@ -429,7 +487,7 @@ for (let iteration = 0; iteration < 10; iteration++) {
           const final = await integration.run({
             name: "merger",
             maxIterations: 1,
-            agent: shipyard.codex(shipyard.CODEX_MODELS.strong),
+            agent: roleAgent("strong", shipyard.CODEX_MODELS.strong),
             promptFile: "./.shipyard/merge-prompt.md",
             promptArgs: {
               TASK_ID: id,
@@ -445,7 +503,7 @@ for (let iteration = 0; iteration < 10; iteration++) {
             const finalReview = await integration.run({
               name: "reviewer",
               maxIterations: 1,
-              agent: shipyard.codex(shipyard.CODEX_MODELS.strong),
+              agent: roleAgent("strong", shipyard.CODEX_MODELS.strong),
               promptFile: "./.shipyard/review-prompt.md",
               promptArgs: {
                 TASK_ID: id,

package/dist/templates/parallel-planner-with-review/planner-branch.mts

@@ -0,0 +1,151 @@
+import { execFileSync } from "node:child_process";
+import { createInterface } from "node:readline/promises";
+
+const PLANNER_BRANCH = "shipyard/planner";
+
+type BranchPrompt = (message: string) => Promise<string>;
+
+const askInTerminal: BranchPrompt = async (message) => {
+  const readline = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  try {
+    return await readline.question(message);
+  } finally {
+    readline.close();
+  }
+};
+
+const refsConflict = (left: string, right: string): boolean =>
+  left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
+
+const nextPlannerBranch = (localBranches: readonly string[]): string => {
+  for (let suffix = 2; ; suffix++) {
+    for (const candidate of [
+      `${PLANNER_BRANCH}-${suffix}`,
+      `shipyard-planner-${suffix}`,
+    ]) {
+      if (!localBranches.some((branch) => refsConflict(candidate, branch)))
+        return candidate;
+    }
+  }
+};
+
+const reusablePlannerBranch = (
+  localBranches: readonly string[],
+): string | undefined => {
+  const candidates = localBranches
+    .map((branch) => ({
+      branch,
+      suffix: /^(?:shipyard\/planner-|shipyard-planner-)(\d+)$/.exec(
+        branch,
+      )?.[1],
+    }))
+    .filter((candidate) => candidate.suffix !== undefined)
+    .sort((left, right) => Number(left.suffix) - Number(right.suffix));
+
+  return candidates.find(({ branch }) =>
+    localBranches.every(
+      (other) => other === branch || !refsConflict(branch, other),
+    ),
+  )?.branch;
+};
+
+export const resolvePlannerBranch = async (
+  localBranches: readonly string[],
+  options: {
+    isInteractive?: boolean;
+    ask?: BranchPrompt;
+    checkedOutBranches?: readonly string[];
+    mergedBranches?: readonly string[];
+    deleteBranches?: (branches: readonly string[]) => void;
+  } = {},
+): Promise<string> => {
+  const conflicts = localBranches.filter((branch) =>
+    refsConflict(PLANNER_BRANCH, branch),
+  );
+  if (conflicts.length === 0) return PLANNER_BRANCH;
+
+  const reusable = reusablePlannerBranch(localBranches);
+  if (reusable) return reusable;
+
+  const alternate = nextPlannerBranch(localBranches);
+
+  const conflictList = conflicts.map((branch) => `  - ${branch}`).join("\n");
+  const context =
+    `Planner branch '${PLANNER_BRANCH}' conflicts with local branch refs:\n${conflictList}\n` +
+    `Git cannot create both names. The listed local branches will be kept unless you choose deletion.`;
+  const isInteractive =
+    options.isInteractive ??
+    Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  if (!isInteractive) {
+    throw new Error(
+      `${context}\nRerun in an interactive terminal to keep them and use '${alternate}', or request local deletion after Git checks that they are merged and not checked out. No branches were changed.`,
+    );
+  }
+
+  const checkedOutBranches = new Set(
+    options.checkedOutBranches ??
+      execFileSync("git", ["worktree", "list", "--porcelain"], {
+        encoding: "utf8",
+      })
+        .split(/\r?\n/)
+        .filter((line) => line.startsWith("branch refs/heads/"))
+        .map((line) => line.slice("branch refs/heads/".length)),
+  );
+  const mergedBranches = new Set(
+    options.mergedBranches ??
+      execFileSync(
+        "git",
+        ["branch", "--merged", "HEAD", "--format=%(refname:short)"],
+        { encoding: "utf8" },
+      )
+        .split(/\r?\n/)
+        .filter(Boolean),
+  );
+  const branchesSafeToDelete = conflicts.every(
+    (branch) => !checkedOutBranches.has(branch) && mergedBranches.has(branch),
+  );
+  const unsafeDeleteReasons = conflicts.flatMap((branch) => {
+    if (checkedOutBranches.has(branch))
+      return [`'${branch}' is checked out in a worktree`];
+    if (!mergedBranches.has(branch))
+      return [`'${branch}' has commits not merged into HEAD`];
+    return [];
+  });
+
+  const ask = options.ask ?? askInTerminal;
+  const answer = await ask(
+    `${context}\n[Y] Keep them and use '${alternate}' (recommended)\n` +
+      `[d] Delete these local branches and use '${PLANNER_BRANCH}'${
+        branchesSafeToDelete
+          ? ""
+          : ` (unavailable: ${unsafeDeleteReasons.join("; ")})`
+      }\n` +
+      `[n] Abort without changes\nChoose [Y/d/n]: `,
+  );
+  const choice = answer.trim().toLowerCase();
+  if (choice === "" || choice === "y" || choice === "yes") return alternate;
+  if (choice === "d" || choice === "delete") {
+    if (!branchesSafeToDelete) {
+      throw new Error(
+        `Cannot safely delete the conflicting branches: ${unsafeDeleteReasons.join("; ")}. No branches were changed. Use '${alternate}' or inspect the listed refs manually.`,
+      );
+    }
+    const deleteBranches =
+      options.deleteBranches ??
+      ((branches: readonly string[]) => {
+        for (const branch of branches)
+          execFileSync("git", ["branch", "-d", branch], {
+            encoding: "utf8",
+          });
+      });
+    deleteBranches(conflicts);
+    return PLANNER_BRANCH;
+  }
+
+  throw new Error(
+    `Planner branch selection cancelled. No branches were changed. Inspect with 'git worktree list' and 'git branch --list "shipyard/planner*"', then rerun.`,
+  );
+};