@pmelab/gtd 64.2.0 → 65.0.0

package/src/flows/index.ts

@@ -28,6 +28,7 @@ export {
   sections,
   settings,
   settingsOf,
+  ship,
   skillsFor,
   start,
   threads,
@@ -58,6 +59,7 @@ export {
   type ScopeOptions,
   type Section,
   type Settings,
+  type ShipOptions,
   type SkillsExport,
   type Steering,
   type SteeringOptions,

package/src/flows/runtime.ts

@@ -89,7 +89,20 @@ export type HumanOptions = HumanCommon &
       })
   )
 
-export type RunOptions = SteeringOptions
+export type RunOptions = SteeringOptions & {
+  /**
+   * `"rest"`: a non-zero exit is recorded in the tree and the process rests at
+   * the step as `stalled`; any tree change runs the script again, and only a
+   * zero exit advances. Without it a failing body lands and the flow carries on.
+   */
+  readonly onFail?: "rest" | undefined
+}
+
+/** A ship step rests on no steering file. */
+export type ShipOptions = SteeringCommon & {
+  readonly file?: undefined
+  readonly mode?: undefined
+}
 
 export type JudgePrimitive = "noul" | "choice" | "score"
 
@@ -204,6 +217,12 @@ export type StepRequest =
       readonly body: string
       readonly options: RunOptions
     }
+  | {
+      readonly kind: "ship"
+      readonly name: string
+      readonly message: string
+      readonly options: ShipOptions
+    }
   | {
       readonly kind: "judge"
       readonly name: string
@@ -344,6 +363,18 @@ export const human: Human = (
 export const run = (name: string, body: string, options: RunOptions = {}): Promise<void> =>
   ctx().step({ kind: "run", name, body, options }) as Promise<void>
 
+/**
+ * Squashes HEAD's tree, with `.gtd/` as the user's branch has it, into one commit on the user's branch
+ * with `message`, and moves that branch there; HEAD stays on `gtd/<b>`.
+ * Resolves to the new commit's hash, or `undefined` when nothing shipped.
+ */
+export const ship = (
+  name: string,
+  message: string,
+  options: ShipOptions = {},
+): Promise<string | undefined> =>
+  ctx().step({ kind: "ship", name, message, options }) as Promise<string | undefined>
+
 /** A judge gate: resolves to what the judge answered, for the flow to decide on. */
 export const judge = <const Q extends readonly JudgeQuestionInput[] = readonly JudgeQuestion[]>(
   name: string,

package/src/platform/RetainedHistory.ts

@@ -4,6 +4,9 @@ import type { GitOperations } from "./Git.js"
 /** Per-worktree (`refs/worktree/gtd/*`) so linked worktrees sharing one `.git` don't clobber each other's retained history. */
 export const HISTORY_REF = "refs/worktree/gtd/history"
 
+/** Set by an abandon that left `gtd/<b>` for `<b>`: only then does restore recreate `gtd/<b>`. */
+export const RESUME_BRANCH_REF = "refs/worktree/gtd/history-branch"
+
 /** One ref per finished process, kept past the branch's deletion; distinct from the per-worktree `HISTORY_REF`. */
 export const PROCESS_HISTORY_PREFIX = "refs/gtd/history/"
 

package/src/platform/index.ts

@@ -31,6 +31,7 @@ export * as NodeServices from "./NodeServices.js"
 export { loopLogPath } from "./WorktreeState.js"
 export {
   HISTORY_REF,
+  RESUME_BRANCH_REF,
   keptRef,
   processHistoryRef,
   PROCESS_HISTORY_PREFIX,

package/src/replay/Replay.test.ts

@@ -15,6 +15,7 @@ import {
   refuse,
   restart,
   run,
+  ship,
   scope,
   threads,
   type Flow,
@@ -647,6 +648,14 @@ describe("replay", () => {
     expect(outcome.kind === "failed" && outcome.message).toContain("shell script string")
   })
 
+  it("fails a ship step with an empty message", async () => {
+    const wf = async () => {
+      await ship("shipping", "  ")
+    }
+    const outcome = await replayOf(wf, new History())
+    expect(outcome.kind === "failed" && outcome.message).toContain("non-empty commit message")
+  })
+
   it("fails a flow that awaits something other than a step", async () => {
     const waiting = async () => {
       await new Promise((resolve) => setTimeout(resolve, 50))

package/src/replay/Replay.ts

@@ -20,7 +20,7 @@ import {
   threads,
 } from "../steering/index.js"
 import { accessShapeFault, foldAccess, sameAccess } from "./Access.js"
-import { globMatches, PIN_PATH } from "../wire/index.js"
+import { globMatches, PIN_PATH, RUN_FAILED_PATH } from "../wire/index.js"
 import { refNameFault } from "./RefName.js"
 import { diffTrees, isEmptyDiff, withoutPath, type TreeView } from "./Tree.js"
 import {
@@ -60,6 +60,8 @@ export interface Episode {
 export interface PendingTurn {
   readonly tree: TreeView
   readonly verdicts?: readonly JudgeVerdict[]
+  /** What a pending ship step resolves to: a stand-in hash when it will ship, the real one exists only once it landed. */
+  readonly shipped?: string
 }
 
 export interface ReplayInput {
@@ -90,7 +92,13 @@ export type StepKind = Exclude<StepRequest["kind"], "restart">
 type Actor = "agent" | "human" | "check" | "judge"
 
 const actorOfKind = (kind: StepKind): Actor =>
-  kind === "run" ? "check" : kind === "agent" ? "agent" : kind === "human" ? "human" : "judge"
+  kind === "run" || kind === "ship"
+    ? "check"
+    : kind === "agent"
+      ? "agent"
+      : kind === "human"
+        ? "human"
+        : "judge"
 
 /** One step replay reached, completed or not. */
 export interface ReachedStep {
@@ -316,10 +324,21 @@ const STEERING_OPTIONS = ["file", "mode", "label", "base"]
 const KNOWN_OPTIONS: Readonly<Record<StepKind, ReadonlySet<string>>> = {
   agent: new Set([...STEERING_OPTIONS, "model", "system", "allowEmpty", "keep"]),
   human: new Set([...STEERING_OPTIONS, "message", "acceptClean", "approve"]),
-  run: new Set(STEERING_OPTIONS),
+  run: new Set([...STEERING_OPTIONS, "onFail"]),
+  ship: new Set(["label", "base"]),
   judge: new Set([...STEERING_OPTIONS, "message"]),
 }
 
+const restsOnFail = (step: ReachedStep): boolean =>
+  step.request.kind === "run" && step.request.options.onFail === "rest"
+
+const onFailFault = (step: ReachedStep): string | undefined =>
+  step.request.kind === "run" &&
+  step.request.options.onFail !== undefined &&
+  step.request.options.onFail !== "rest"
+    ? `gtd: step "${step.name}": onFail must be "rest" in run() options`
+    : undefined
+
 const unknownOptions = (step: ReachedStep): string | undefined => {
   const unknown = Object.keys(step.request.options).filter(
     (key) => !KNOWN_OPTIONS[step.kind].has(key),
@@ -454,12 +473,13 @@ export const replay = async (raw: ReplayInput): Promise<ReplayOutcome> => {
   const scoped = (name: string): string =>
     [...scopes.flatMap((s) => (s.name === undefined ? [] : [s.name])), name].join(".")
 
-  const isAttemptAt = (commit: ParsedCommit, name: string): boolean =>
+  const isAttemptAt = (commit: ParsedCommit, step: ReachedStep): boolean =>
     commit.parsed.step === undefined &&
     commit.parsed.parsed !== undefined &&
     commit.parsed.parsed.from === undefined &&
-    commit.parsed.parsed.to === name &&
-    isEmptyDiff(diffTrees(position.tree, commit.tree))
+    commit.parsed.parsed.to === step.name &&
+    (isEmptyDiff(diffTrees(position.tree, commit.tree)) ||
+      (restsOnFail(step) && commit.tree.read(RUN_FAILED_PATH) !== undefined))
 
   const advance = (next: Position): void => {
     previousPosition = position
@@ -469,13 +489,16 @@ export const replay = async (raw: ReplayInput): Promise<ReplayOutcome> => {
   const replyFor = (
     request: Exclude<StepRequest, { kind: "restart" }>,
     verdicts: readonly JudgeVerdict[],
+    shipped: string | undefined,
   ): unknown =>
     request.kind === "judge"
       ? {
           answers: answersFrom(verdicts, request.questions),
           truncated: judgeCuts.get(request) ?? [],
         }
-      : undefined
+      : request.kind === "ship"
+        ? shipped
+        : undefined
 
   const judgeCuts = new WeakMap<object, readonly string[]>()
 
@@ -636,7 +659,11 @@ export const replay = async (raw: ReplayInput): Promise<ReplayOutcome> => {
       )
     }
     const error =
-      unknownOptions(step) ?? approveConflict(step) ?? modeWithoutFile(step) ?? checkIdentity(step)
+      unknownOptions(step) ??
+      onFailFault(step) ??
+      approveConflict(step) ??
+      modeWithoutFile(step) ??
+      checkIdentity(step)
     return error === undefined ? undefined : { kind: "failed", message: error }
   }
 
@@ -670,7 +697,7 @@ export const replay = async (raw: ReplayInput): Promise<ReplayOutcome> => {
     expectNextOf(commit)
     skipPins()
     noteKept(step, commit)
-    return replyFor(step.request, commit.parsed.judge)
+    return replyFor(step.request, commit.parsed.judge, commit.parsed.shipped)
   }
 
   // A turn that ends a pinned process names the unpin, which is no step.
@@ -699,11 +726,15 @@ export const replay = async (raw: ReplayInput): Promise<ReplayOutcome> => {
       keptTips.set(step.name, { hash: "", before: position.tree, after: pending.tree })
     }
     advance({ hash: "", tree: keeping ? position.tree : pending.tree })
-    return replyFor(step.request, pending.verdicts ?? [])
+    return replyFor(step.request, pending.verdicts ?? [], pending.shipped)
   }
 
   const answer = (step: ReachedStep): unknown => {
-    while (cursor < commits.length && isAttemptAt(commits[cursor]!, step.name)) {
+    while (cursor < commits.length && isAttemptAt(commits[cursor]!, step)) {
+      // An attempt that recorded a failure carries its tree; an empty one changes nothing.
+      if (!isEmptyDiff(diffTrees(position.tree, commits[cursor]!.tree))) {
+        advance({ hash: commits[cursor]!.hash, tree: commits[cursor]!.tree })
+      }
       cursor++
       skipPins()
     }
@@ -718,18 +749,31 @@ export const replay = async (raw: ReplayInput): Promise<ReplayOutcome> => {
         marks,
       })
     }
+    if (restsOnFail(step) && input.pending.tree.read(RUN_FAILED_PATH) !== undefined) {
+      return finish({ kind: "rest", rest: step, trace, landed, marks })
+    }
     return landPending(step, input.pending)
   }
 
+  const bodyFault = (request: Exclude<StepRequest, { kind: "restart" | "agent" }>) => {
+    if (
+      request.kind === "ship" &&
+      (typeof request.message !== "string" || request.message.trim() === "")
+    ) {
+      return `gtd: step "${scoped(request.name)}": a ship() message is a non-empty commit message`
+    }
+    if (request.kind === "run" && typeof request.body !== "string") {
+      return `gtd: step "${scoped(request.name)}": a run() body is a shell script string — decide in flow code, then render the script (see checkScript and friends)`
+    }
+    return undefined
+  }
+
   // gtd.config.ts is loaded without a type check.
   const requestFault = (request: Exclude<StepRequest, { kind: "restart" }>): string | undefined => {
     if (scoped(request.name).startsWith(ENGINE_PREFIX)) {
       return `gtd: step "${scoped(request.name)}": the "${ENGINE_PREFIX}" prefix is reserved for gtd's own beats — rename the step`
     }
-    if (request.kind === "run" && typeof request.body !== "string") {
-      return `gtd: step "${scoped(request.name)}": a run() body is a shell script string — decide in flow code, then render the script (see checkScript and friends)`
-    }
-    if (request.kind !== "agent") return undefined
+    if (request.kind !== "agent") return bodyFault(request)
     const name = scoped(request.name)
     if (request.options.keep === true) {
       // A clean allowEmpty keep would land an ordinary commit with no Gtd-Kept: a silent skip.

package/src/replay/Trailers.ts

@@ -118,6 +118,10 @@ export interface CommitMessage {
   readonly pin: PinChange | undefined
   /** `Gtd-Anchor`, on a repin's commit: replay sets aside every commit after this one; a non-hash value is skipped. */
   readonly anchor: string | undefined
+  /** `Gtd-Shipped`, on a ship step's landing: the commit it put on the user's branch. */
+  readonly shipped: string | undefined
+  /** `Gtd-Tip`, on a shipped commit: the process commit whose tree it carries. */
+  readonly tip: string | undefined
   readonly format: number
 }
 
@@ -178,6 +182,8 @@ interface Trailers {
   approved: Approval | undefined
   pin: PinChange | undefined
   anchor: string | undefined
+  shipped: string | undefined
+  tip: string | undefined
   readonly judge: JudgeVerdict[]
   readonly marks: Mark[]
   readonly vars: Record<string, string>
@@ -228,6 +234,12 @@ const TRAILER_READERS: Readonly<Record<string, (value: string, into: Trailers) =
   "Gtd-Anchor": (value, into) => {
     if (HASH_RE.test(value)) into.anchor ??= value
   },
+  "Gtd-Shipped": (value, into) => {
+    if (HASH_RE.test(value)) into.shipped ??= value
+  },
+  "Gtd-Tip": (value, into) => {
+    if (HASH_RE.test(value)) into.tip ??= value
+  },
   "Gtd-Format": (value, into) => {
     if (FORMAT_RE.test(value)) into.format ??= Number(value)
   },
@@ -250,6 +262,8 @@ export const parseCommitMessage = (message: string): CommitMessage => {
     approved: undefined,
     pin: undefined,
     anchor: undefined,
+    shipped: undefined,
+    tip: undefined,
     judge: [],
     marks: [],
     vars: {},

package/src/replay/index.ts

@@ -6,7 +6,7 @@ export {
   type ReachedStep,
   type ReplayOutcome,
 } from "./Replay.js"
-export { treeFromRecord, type TreeView } from "./Tree.js"
+export { diffTrees, treeFromRecord, type TreeView } from "./Tree.js"
 export {
   formatCommitMessage,
   formatStepId,

package/src/step/LandStep.ts

@@ -12,6 +12,18 @@ export type GitWrite =
   | { readonly kind: "commitClean"; readonly message: string }
   | { readonly kind: "updateRef"; readonly ref: string; readonly target: "HEAD" }
   | { readonly kind: "keepTurn"; readonly ref: string; readonly message: string }
+  | { readonly kind: "switchBranch"; readonly branch: string }
+  | { readonly kind: "switchTo"; readonly branch: string }
+  | { readonly kind: "pushRef"; readonly remote: string; readonly ref: string }
+  | ({ readonly kind: "ship"; readonly message: string } & ShipSpec)
+
+/** A ship step's squash: `shipMessage` on `branch`, CAS against `parent`, its `Gtd-History` naming `historyRef`. */
+export interface ShipSpec {
+  readonly branch: string
+  readonly parent: string
+  readonly shipMessage: string
+  readonly historyRef: string
+}
 
 /** A landed step's trailing report, rendered by `GitScript.ts` into a `printf` line. */
 export type Outcome =

package/src/step/RepoSnapshot.ts

@@ -1,5 +1,6 @@
 import type { CommitSpec } from "../replay/index.js"
 import type { PendingChange, StateName, StepDef } from "../workflow/index.js"
+import type { ShipSpec } from "./LandStep.js"
 
 /**
  * What landing the pending turn does, decided at the edge by replaying the
@@ -19,6 +20,16 @@ export type Landing =
       readonly keepHistory?: string
       /** The kept ref this landing's turn goes to; the branch gets a marker commit instead. */
       readonly keepTurn?: string
+      /** The `gtd/<b>` branch a starting landing switches to before it commits. */
+      readonly startBranch?: string
+      /** The user's branch `<b>` a finishing landing switches back to, after its history ref. */
+      readonly leaveBranch?: string
+      /** A remote the closing or shipping landing force-pushes its history ref to, after the commit. */
+      readonly pushHistory?: string
+      /** A ship step's squash onto the user's branch, made ahead of the landing commit. */
+      readonly ship?: ShipSpec
+      /** Printed after the landing: why a ship step shipped nothing. */
+      readonly note?: string
       /** The one path this landing commits; every other pending change stays pending. */
       readonly only?: string
     }

package/src/step/index.ts

@@ -1,6 +1,7 @@
 export { planStep, type JudgeVerdict } from "./planStep.js"
 export { accessRefusal } from "./accessRefusal.js"
 export { planStart } from "./planStart.js"
+export { startBranchFor, GTD_BRANCH_PREFIX, userBranchOf } from "./startBranch.js"
 export type { GitWrite, LandStep, Outcome } from "./LandStep.js"
 export type { Landing, RepoSnapshot } from "./RepoSnapshot.js"
 export { strayPaths } from "./strayPaths.js"

package/src/step/planStart.test.ts

@@ -108,7 +108,7 @@ describe("planStart", () => {
       repo.seedCommit("feat: ahead of main")
       const plan = await start(repo, "idle", "human", { ...REVIEW, vars: {} })
       if (plan.kind !== "start") throw new Error(`expected start, got ${JSON.stringify(plan)}`)
-      const write = plan.steps.find((s) => s.kind === "gitWrite")
+      const write = plan.steps.find((s) => s.kind === "gitWrite" && s.write.kind === "commitAll")
       if (write?.kind !== "gitWrite" || write.write.kind !== "commitAll")
         throw new Error("expected a gitWrite step")
       expect(write.write.message).toContain(`Gtd-Review-Base: ${fork}`)
@@ -125,7 +125,7 @@ describe("planStart", () => {
       repo.seedCommit("feat: my branch")
       const plan = await start(repo, "idle", "human", { ...REVIEW, vars: { base: "other" } })
       if (plan.kind !== "start") throw new Error(`expected start, got ${JSON.stringify(plan)}`)
-      const write = plan.steps.find((s) => s.kind === "gitWrite")
+      const write = plan.steps.find((s) => s.kind === "gitWrite" && s.write.kind === "commitAll")
       if (write?.kind !== "gitWrite" || write.write.kind !== "commitAll")
         throw new Error("expected a gitWrite step")
       expect(write.write.message).toContain(`Gtd-Review-Base: ${fork}`)
@@ -172,6 +172,7 @@ describe("planStart", () => {
     if (plan.kind !== "start") throw new Error(`expected start, got ${plan.kind}`)
     expect(plan.subject).toBe("gtd(human): work")
     expect(plan.steps).toEqual([
+      { kind: "gitWrite", write: { kind: "switchBranch", branch: "gtd/main" } },
       {
         kind: "gitWrite",
         write: {
@@ -191,7 +192,7 @@ describe("planStart", () => {
       vars: { base: "main" },
     })
     if (plan.kind !== "start") throw new Error(`expected start, got ${plan.kind}`)
-    const write = plan.steps.find((s) => s.kind === "gitWrite")
+    const write = plan.steps.find((s) => s.kind === "gitWrite" && s.write.kind === "commitAll")
     if (write?.kind !== "gitWrite" || write.write.kind !== "commitAll")
       throw new Error("expected a gitWrite step")
     expect(write.write.message).toBe(

package/src/step/planStart.ts

@@ -11,6 +11,7 @@ import {
 } from "../workflow/index.js"
 import { formatCommitMessage, formatSubject } from "../replay/index.js"
 import type { LandStep } from "./LandStep.js"
+import { startBranchFor } from "./startBranch.js"
 
 /** Just enough of the current rest for `planStart`'s checks. */
 export interface StartCurrent {
@@ -87,6 +88,7 @@ export const planStart = (
   Error,
   GitService | ConfigService | ConfigDiscovery | Workspace | Host | Narrator
 > =>
+  // fallow-ignore-next-line complexity
   Effect.gen(function* () {
     const { workflow, first, commandLabel, vars: varOverrides } = start
     const name = workflow.name
@@ -134,7 +136,12 @@ export const planStart = (
       ...(base !== undefined ? { reviewBase: base } : {}),
       vars,
     })
+    const onBranch = yield* startBranchFor(commandLabel)
+    if (onBranch.kind === "refusal") return refusal(onBranch.message)
     const steps: readonly LandStep[] = [
+      ...(onBranch.kind === "switch"
+        ? [{ kind: "gitWrite", write: { kind: "switchBranch", branch: onBranch.branch } } as const]
+        : []),
       { kind: "gitWrite", write: { kind: "commitAll", message } },
       { kind: "outcome", outcome: { kind: "commit", subject } },
     ]

package/src/step/planStep.ts

@@ -36,12 +36,16 @@ const uncheckStep = (snapshot: RepoSnapshot): readonly LandStep[] =>
     : []
 
 const gitWriteOf = (landing: Extract<Landing, { kind: "commit" }>, message: string): GitWrite => {
+  if (landing.ship !== undefined) return { kind: "ship", message, ...landing.ship }
   if (landing.only !== undefined) return { kind: "commitPath", path: landing.only, message }
   if (landing.keepTurn !== undefined) return { kind: "keepTurn", ref: landing.keepTurn, message }
   if (landing.spec.approved !== undefined) return { kind: "commitClean", message }
   return { kind: "commitAll", message }
 }
 
+const writeIf = (value: string | undefined, write: (value: string) => GitWrite): LandStep[] =>
+  value === undefined ? [] : [{ kind: "gitWrite", write: write(value) }]
+
 export const planStep = (
   snapshot: RepoSnapshot,
   opts: {
@@ -78,6 +82,7 @@ export const planStep = (
     ...(opts.judge !== undefined && opts.judge.length > 0 ? { judge: opts.judge } : {}),
   })
   const subject = message.split("\n")[0]!
+  const historyRef = landing.keepHistory ?? landing.ship?.historyRef
   const outcome: LandStep =
     landing.to === snapshot.state
       ? { kind: "outcome", outcome: { kind: "commit", subject } }
@@ -88,20 +93,20 @@ export const planStep = (
     to: landing.to,
     subject,
     steps: [
+      ...writeIf(landing.startBranch, (branch) => ({ kind: "switchBranch", branch })),
       ...uncheckStep(snapshot),
-      {
-        kind: "gitWrite",
-        write: gitWriteOf(landing, message),
-      },
-      ...(landing.keepHistory !== undefined
-        ? [
-            {
-              kind: "gitWrite",
-              write: { kind: "updateRef", ref: landing.keepHistory, target: "HEAD" },
-            } as const,
-          ]
-        : []),
+      { kind: "gitWrite", write: gitWriteOf(landing, message) },
+      ...writeIf(historyRef, (ref) => ({ kind: "updateRef", ref, target: "HEAD" })),
+      ...writeIf(landing.leaveBranch, (branch) => ({ kind: "switchTo", branch })),
       outcome,
+      ...(landing.note !== undefined
+        ? [{ kind: "outcome", outcome: { kind: "note", text: landing.note } } as const]
+        : []),
+      ...writeIf(historyRef !== undefined ? landing.pushHistory : undefined, (remote) => ({
+        kind: "pushRef",
+        remote,
+        ref: historyRef!,
+      })),
     ],
   }
 }

package/src/step/startBranch.ts

@@ -0,0 +1,54 @@
+import { Effect, Option } from "effect"
+import { GitService } from "../platform/index.js"
+import { PROCESS_HISTORY_PREFIX } from "../platform/index.js"
+
+export const GTD_BRANCH_PREFIX = "gtd/"
+
+/** `<b>` for a `gtd/<b>` branch name; `undefined` for any other. */
+export const userBranchOf = (branch: string): string | undefined =>
+  branch.startsWith(GTD_BRANCH_PREFIX) ? branch.slice(GTD_BRANCH_PREFIX.length) : undefined
+
+/** A branch already named `gtd/…` and a detached HEAD start in place. */
+export type StartBranch =
+  | { readonly kind: "inPlace" }
+  | { readonly kind: "switch"; readonly branch: string }
+  | { readonly kind: "refusal"; readonly message: string }
+
+/**
+ * Where a new process starts: on `gtd/<b>`, so `<b>` never carries its commits.
+ * An existing `gtd/<b>` is reused only when its tip is contained in `<b>` or in
+ * a kept history ref (a squash onto `<b>` never makes it an ancestor).
+ */
+export const startBranchFor = (
+  commandLabel: string,
+): Effect.Effect<StartBranch, Error, GitService> =>
+  Effect.gen(function* () {
+    const git = yield* GitService
+    const current = yield* git.currentBranch()
+    if (Option.isNone(current) || current.value.startsWith(GTD_BRANCH_PREFIX)) {
+      return { kind: "inPlace" } as const
+    }
+    if (!(yield* git.hasCommits())) return { kind: "inPlace" } as const
+    const branch = `${GTD_BRANCH_PREFIX}${current.value}`
+    const existing = yield* git.readRefOption(`refs/heads/${branch}`)
+    if (Option.isSome(existing)) {
+      const head = yield* git.resolveRef("HEAD")
+      let contained = yield* git.isAncestor(existing.value, head)
+      if (!contained) {
+        const kept = yield* git.listRefs(PROCESS_HISTORY_PREFIX)
+        for (const k of kept) {
+          if (yield* git.isAncestor(existing.value, k.hash)) {
+            contained = true
+            break
+          }
+        }
+      }
+      if (!contained) {
+        return {
+          kind: "refusal",
+          message: `${commandLabel}: branch ${branch} holds commits that are neither on ${current.value} nor in a kept history ref — merge or delete it first`,
+        } as const
+      }
+    }
+    return { kind: "switch", branch } as const
+  })