@pmelab/gtd 64.3.0 → 65.0.0

package/src/edge/Edge.ts

@@ -39,6 +39,7 @@ import {
   formatCommitMessage,
   scopeRunStart,
   setAsideBy,
+  diffTrees,
   treeFromRecord,
   type EpisodeCommit,
   type JudgeVerdict,
@@ -51,10 +52,11 @@ import {
 } from "../replay/index.js"
 import type { Mark, ScopeAccess, SummaryContext } from "../flows/index.js"
 import { steeringFormatFor } from "../steering/index.js"
-import { pinScript, unpinScript } from "../emit/index.js"
+import { failRestScript, noteOutcome, pinScript, unpinScript } from "../emit/index.js"
 import {
   judgeJson,
   PIN_PATH,
+  RUN_FAILED_PATH,
   UNATTRIBUTED_MODEL,
   type ApprovalEntry,
   type ModelCost,
@@ -63,6 +65,7 @@ import {
 
 import { GTD_VERSION } from "../install/index.js"
 import { keptRef, processHistoryRef } from "../platform/index.js"
+import { GTD_BRANCH_PREFIX, startBranchFor, userBranchOf } from "../step/index.js"
 import { accessRefusal, type Landing, type RepoSnapshot } from "../step/index.js"
 
 export { UNATTRIBUTED_MODEL }
@@ -478,21 +481,38 @@ const runAtTip = (
     return yield* runOf([...before, ...closing], { ...location }, tip.hash)
   })
 
-const runAtHead = (git: GitOperations, def: WorkflowDefinition) =>
-  Effect.gen(function* () {
-    // Cheap: just HEAD's own subject, never the commits before it.
-    return yield* runAtTip(git, def, (yield* git.subjectHistory(1, 0))[0])
-  })
-
-/** The process HEAD closes or sits inside — `gtd summary`'s run. */
+/**
+ * The process HEAD closes or sits inside — `gtd summary`'s run. On `<b>`, where
+ * a finished process leaves HEAD, it is the one `gtd/<b>`'s tip closes, while
+ * `<b>` holds nothing since: its start, or its last ship.
+ */
 export const summaryRun: Effect.Effect<ProcessRun, Error, ConfigRequirements> = Effect.gen(
   function* () {
     const git = yield* GitService
     const def = (yield* (yield* ConfigService).load).workflow
-    return yield* runAtHead(git, def)
+    const head = (yield* git.subjectHistory(1, 0))[0]
+    const left = head === undefined ? undefined : yield* leftProcessTip(git, head)
+    return yield* runAtTip(git, def, left ?? head)
   },
 )
 
+const leftProcessTip = (
+  git: GitOperations,
+  head: { readonly hash: string; readonly subject: string },
+) =>
+  Effect.gen(function* () {
+    if (parseCommitMessage(head.subject).parsed !== undefined) return undefined
+    const current = yield* git.currentBranch()
+    if (Option.isNone(current) || userBranchOf(current.value) !== undefined) return undefined
+    const tip = yield* git.readRefOption(`refs/heads/${GTD_BRANCH_PREFIX}${current.value}`)
+    if (Option.isNone(tip)) return undefined
+    const message = yield* git.lastCommitMessage(tip.value)
+    if (parseCommitMessage(message).parsed?.to === undefined) return undefined
+    const since = parseCommitMessage(yield* git.lastCommitMessage(head.hash)).tip ?? head.hash
+    if (!(yield* git.isAncestor(since, tip.value))) return undefined
+    return { hash: tip.value, subject: message.split("\n")[0]! }
+  })
+
 // ── Trees ───────────────────────────────────────────────────────────────────
 
 const commitTree = (workspace: WorkspaceOps, hash: string): TreeView => {
@@ -653,7 +673,11 @@ interface ReplaySetup {
 
 const replayFor = (
   setup: ReplaySetup,
-  pending?: { readonly tree: TreeView; readonly verdicts?: readonly JudgeVerdict[] },
+  pending?: {
+    readonly tree: TreeView
+    readonly verdicts?: readonly JudgeVerdict[]
+    readonly shipped?: string
+  },
 ): Promise<ReplayOutcome> =>
   replay({
     flow: setup.def.flow,
@@ -744,7 +768,19 @@ const promptDef = (
 const scriptDef = (common: StepCommon, request: RequestOf<"run">): StepDef => ({
   ...common,
   kind: "script",
-  content: request.body,
+  content:
+    request.options.onFail === "rest"
+      ? failRestScript(request.body, RUN_FAILED_PATH)
+      : request.body,
+  ...optional("onFail", request.options.onFail),
+})
+
+const SHIP_CONTENT = noteOutcome("gtd: landing this step ships the process onto your branch")
+
+const shipDef = (common: StepCommon): StepDef => ({
+  ...common,
+  kind: "script",
+  content: SHIP_CONTENT,
 })
 
 const judgeDef = (common: StepCommon, request: RequestOf<"judge">, step: ReachedStep): StepDef => {
@@ -777,6 +813,8 @@ const stepDefOf = (step: ReachedStep): StepDef => {
       return promptDef(common, request, step.skills, step.access)
     case "run":
       return scriptDef(common, request)
+    case "ship":
+      return shipDef(common)
     case "judge":
       return judgeDef(common, request, step)
     case "human":
@@ -885,6 +923,8 @@ interface Rest extends ResolvedRest {
   /** Total recorded cost of the process, and its per-model breakdown. */
   readonly cost: { readonly total: number; readonly byModel: readonly ModelCost[] }
   readonly setup: ReplaySetup
+  /** At a ship step on a clean tree: why landing it would be refused. */
+  readonly shipBlocked?: string
 }
 
 /** Per-model token totals, highest-cost first (ties broken by model name). */
@@ -1054,6 +1094,8 @@ export const restAt = (
       yield* (yield* Narrator).warn(
         `gtd: notice: the live config differs from the pinned one (${config.drift.join(", ")}); \`gtd repin\` to switch`,
       )
+    const shipBlocked =
+      ref === undefined ? yield* shipBlockedAt(setup, pin, step, changes) : undefined
     return {
       def,
       workflowName: resolved.name,
@@ -1073,6 +1115,7 @@ export const restAt = (
       hints: hintsOf(stepDef),
       cost: costTotals(run.costEntries),
       setup,
+      ...(shipBlocked !== undefined ? { shipBlocked } : {}),
     }
   })
 
@@ -1246,6 +1289,8 @@ export interface RenderedRest extends RestHints {
   readonly memory?: string
   readonly memoryResumed: boolean
   readonly pin?: PinChange
+  readonly failure?: string
+  readonly blocked?: string
 }
 
 export const renderRest = (rest: Rest): Effect.Effect<RenderedRest, Error> =>
@@ -1255,6 +1300,10 @@ export const renderRest = (rest: Rest): Effect.Effect<RenderedRest, Error> =>
     kind: rest.stepDef.kind,
     content: rest.stepDef.content,
     ...rest.hints,
+    ...(failedRunStalled(rest)
+      ? { failure: rest.setup.workspace.readSync(RUN_FAILED_PATH) ?? "" }
+      : {}),
+    ...(rest.shipBlocked !== undefined ? { blocked: rest.shipBlocked } : {}),
     ...(rest.memory !== undefined ? { memory: rest.memory } : {}),
     memoryResumed: rest.memoryResumed,
     ...(rest.pin !== undefined ? { pin: rest.pin } : {}),
@@ -1265,13 +1314,25 @@ export const renderRest = (rest: Rest): Effect.Effect<RenderedRest, Error> =>
  * attempt at this very agent rest, and another dispatch would repeat it.
  */
 export const stalledAt = (rest: Rest): boolean =>
+  failedRunStalled(rest) ||
+  rest.shipBlocked !== undefined ||
+  (rest.changes.length === 0 &&
+    rest.stepDef.kind === "prompt" &&
+    rest.stepDef.allowEmpty !== true &&
+    rest.run.headTurn?.state === rest.state &&
+    rest.run.headTurn.actor === rest.actor &&
+    !rest.run.headTurn.step &&
+    rest.run.headTurn.empty)
+
+/** A `run(…, { onFail: "rest" })` step whose last turn recorded a failure, on a clean tree. */
+const failedRunStalled = (rest: Rest): boolean =>
   rest.changes.length === 0 &&
-  rest.stepDef.kind === "prompt" &&
-  rest.stepDef.allowEmpty !== true &&
+  rest.stepDef.onFail === "rest" &&
   rest.run.headTurn?.state === rest.state &&
-  rest.run.headTurn.actor === rest.actor &&
   !rest.run.headTurn.step &&
-  rest.run.headTurn.empty
+  // Read from the (clean) tree, not the commit's touched paths: a retry that
+  // fails with identical output touches nothing yet must still stall.
+  rest.setup.workspace.readSync(RUN_FAILED_PATH) !== undefined
 
 /** No process is underway: the default workflow's first step, first visit — a dirty tree there is a turn not yet landed, not a process. */
 export const noProcessUnderway = (rest: Rest): boolean =>
@@ -1487,7 +1548,9 @@ const decideLanding = (
   verdicts: readonly JudgeVerdict[] | undefined,
   branch: Option.Option<string>,
   approver: Option.Option<AuthorIdent>,
+  shipped?: string,
 ): Effect.Effect<Landing, Error> =>
+  // fallow-ignore-next-line complexity
   Effect.gen(function* () {
     if (rest.pin !== undefined) return pinLanding(rest, rest.pin, branch)
     const unapproved = approvalRefusal(rest, approver)
@@ -1498,14 +1561,20 @@ const decideLanding = (
       const message = accessRefusal(rest.changes, rest.stepDef.access.write)
       if (message !== undefined) return { kind: "refusal", message }
     }
+    const landing = pendingTree(
+      rest.setup.workspace,
+      rest.setup.pendingWorktree(),
+      reviewGateRewrite(rest.stepDef),
+    )
+    // A recorded failure lands as an attempt: the process stays at the step.
+    if (rest.stepDef.onFail === "rest" && landing.read(RUN_FAILED_PATH) !== undefined) {
+      return { kind: "attempt", subject: formatSubject(rest.actor, rest.state) }
+    }
     const outcome = yield* Effect.promise(() =>
       replayFor(rest.setup, {
-        tree: pendingTree(
-          rest.setup.workspace,
-          rest.setup.pendingWorktree(),
-          reviewGateRewrite(rest.stepDef),
-        ),
+        tree: landing,
         ...(verdicts !== undefined ? { verdicts } : {}),
+        ...(shipped !== undefined ? { shipped } : {}),
       }),
     )
     const to = yield* landingTarget(outcome, rest)
@@ -1513,31 +1582,227 @@ const decideLanding = (
     return landingTo(rest, to, branch, approver, outcomeMarks(outcome))
   })
 
+/** The user's branch: `<b>` for a process on `gtd/<b>` while `<b>` still exists; any other branch as is. */
+const userBranch = (git: GitOperations): Effect.Effect<Option.Option<string>, Error> =>
+  Effect.gen(function* () {
+    const current = yield* git.currentBranch()
+    const name = Option.isSome(current) ? userBranchOf(current.value) : undefined
+    if (name === undefined) return current
+    const there = yield* git.readRefOption(`refs/heads/${name}`)
+    return Option.isSome(there) ? Option.some(name) : current
+  })
+
+/** `<b>` for a process on `gtd/<b>` while `<b>` exists: where a finishing landing leaves HEAD. */
+const returnBranch = Effect.gen(function* () {
+  const git = yield* GitService
+  const current = yield* git.currentBranch()
+  const name = Option.isSome(current) ? userBranchOf(current.value) : undefined
+  if (name === undefined) return undefined
+  return Option.isSome(yield* git.readRefOption(`refs/heads/${name}`)) ? name : undefined
+})
+
+/** A starting landing moves onto `gtd/<b>` first. */
+const withBranchAndPush = (landing: Landing) =>
+  Effect.gen(function* () {
+    if (landing.kind !== "commit") return landing
+    let out = landing
+    if (landing.spec.vars !== undefined) {
+      const start = yield* startBranchFor("gtd land")
+      if (start.kind === "refusal") return { kind: "refusal", message: start.message } as Landing
+      if (start.kind === "switch") out = { ...out, startBranch: start.branch }
+    }
+    return yield* withHistory(out)
+  })
+
+/** A closing landing switches back to `<b>`; it and a shipping one push their history ref. */
+const withHistory = (landing: Landing & { kind: "commit" }) =>
+  Effect.gen(function* () {
+    let out = landing
+    const back = landing.keepHistory === undefined ? undefined : yield* returnBranch
+    if (back !== undefined) out = { ...out, leaveBranch: back }
+    if (landing.keepHistory === undefined && landing.ship === undefined) return out
+    const remote = (yield* (yield* ConfigService).load).historyRemote
+    return remote === undefined ? out : { ...out, pushHistory: remote }
+  })
+
 /** Where landing the pending turn would leave the process, or `undefined` when it would land nothing. */
 export const previewLanding = (rest: Rest): Effect.Effect<StateName | undefined> =>
-  decideLanding(rest, undefined, Option.none(), Option.none()).pipe(
+  decideLanding(
+    rest,
+    undefined,
+    Option.none(),
+    Option.none(),
+    // Assumes the ship ships: deciding that needs git, and a preview reads none.
+    rest.step.request.kind === "ship" ? SHIPPED_STAND_IN : undefined,
+  ).pipe(
     Effect.map((landing) => (landing.kind === "commit" ? landing.to : undefined)),
     Effect.catch(() => Effect.succeed(undefined)),
   )
 
+const snapshotOf = (rest: Rest, landing: Landing): RepoSnapshot => ({
+  stepDef: rest.stepDef,
+  state: rest.state,
+  actor: rest.actor,
+  changes: rest.changes,
+  file: rest.hints.file,
+  landing,
+})
+
+const refusedSnapshot = (rest: Rest, message: string): RepoSnapshot =>
+  snapshotOf(rest, { kind: "refusal", message })
+
+// The squash's hash exists only once the landing script ran; the flow deciding
+// the landing's target sees this instead, and every later replay the real one.
+const SHIPPED_STAND_IN = "0".repeat(40)
+
+const SHIP_EXCLUDED = ".gtd/"
+
+type ShipDecision =
+  | { readonly kind: "ship"; readonly branch: string; readonly parent: string }
+  | { readonly kind: "skip"; readonly note: string }
+  | { readonly kind: "blocked"; readonly message: string }
+
+const shippedPaths = (before: TreeView, after: TreeView): readonly string[] => {
+  const diff = diffTrees(before, after)
+  return [...diff.added, ...diff.modified, ...diff.deleted].filter(
+    (path) => !path.startsWith(SHIP_EXCLUDED),
+  )
+}
+
+const noTarget = (why: string): ShipDecision => ({
+  kind: "skip",
+  note: `gtd: no branch to ship to: ${why}`,
+})
+
+/** `<b>` and its tip, for a process on `gtd/<b>`; why there is none otherwise. */
+const shipTarget = (git: GitOperations) =>
+  Effect.gen(function* () {
+    const current = yield* git.currentBranch()
+    if (Option.isNone(current)) return noTarget("HEAD is detached")
+    const branch = userBranchOf(current.value)
+    if (branch === undefined) return noTarget(`${current.value} is no gtd/ branch`)
+    if (userBranchOf(branch) !== undefined) {
+      return noTarget(`${current.value} records no user branch`)
+    }
+    const parent = yield* git.readRefOption(`refs/heads/${branch}`)
+    if (Option.isNone(parent)) return noTarget(`${branch} does not exist`)
+    return { kind: "ship", branch, parent: parent.value } as const
+  })
+
+/**
+ * The paths `<b>` changed outside this process that shipping `tree` would
+ * revert. A path the working tree changed since HEAD counts as brought in:
+ * whether it carries `<b>`'s change is the person's call, not a merge gtd redoes.
+ */
+const revertedPaths = (
+  git: GitOperations,
+  workspace: WorkspaceOps,
+  parent: string,
+  tree: TreeView,
+  changed: ReadonlySet<string>,
+) =>
+  Effect.gen(function* () {
+    const head = yield* git.resolveRef("HEAD")
+    const shipped = parseCommitMessage(yield* git.lastCommitMessage(parent)).tip
+    if (shipped !== undefined && (yield* git.isAncestor(shipped, head))) return []
+    const fork = yield* git.mergeBase(parent, head)
+    const foreign = Option.isNone(fork)
+      ? [...changed]
+      : shippedPaths(commitTree(workspace, fork.value), commitTree(workspace, parent))
+    const committed = commitTree(workspace, head)
+    return foreign.filter((path) => changed.has(path) && tree.read(path) === committed.read(path))
+  })
+
+/**
+ * Whether landing a ship step with `tree` would ship, and onto what. The squash
+ * replaces the user's branch's tree with `tree`, so it is blocked while that
+ * branch carries a change `tree` would revert: one made since the last ship
+ * (whose `Gtd-Tip` HEAD descends from), or since it forked from HEAD.
+ */
+const decideShip = (
+  workspace: WorkspaceOps,
+  tree: TreeView,
+): Effect.Effect<ShipDecision, Error, GitService> =>
+  Effect.gen(function* () {
+    const git = yield* GitService
+    const target = yield* shipTarget(git)
+    if (target.kind !== "ship") return target
+    const { branch, parent } = target
+    const changed = new Set(shippedPaths(commitTree(workspace, parent), tree))
+    const reverted = yield* revertedPaths(git, workspace, parent, tree, changed)
+    if (reverted.length > 0) {
+      return {
+        kind: "blocked",
+        message: `gtd: ${branch} changed outside this process, and shipping would revert ${reverted.join(", ")} — bring those changes into the working tree (\`git merge --squash --no-commit ${branch}\`, or by hand) and land`,
+      }
+    }
+    return changed.size === 0
+      ? { kind: "skip", note: `gtd: nothing to ship: ${branch} already has this tree` }
+      : target
+  })
+
+const shipBlockedAt = (
+  setup: ReplaySetup,
+  pin: PinChange | undefined,
+  step: ReachedStep,
+  changes: readonly PendingChange[],
+) =>
+  Effect.gen(function* () {
+    if (pin !== undefined || step.request.kind !== "ship" || changes.length > 0) return undefined
+    const head = yield* (yield* GitService).resolveRef("HEAD")
+    const decision = yield* decideShip(setup.workspace, commitTree(setup.workspace, head))
+    return decision.kind === "blocked" ? decision.message : undefined
+  })
+
+const shipSnapshot = (
+  rest: Rest,
+  message: string,
+  verdicts: readonly JudgeVerdict[] | undefined,
+  branch: Option.Option<string>,
+  approver: Option.Option<AuthorIdent>,
+) =>
+  Effect.gen(function* () {
+    const tree = pendingTree(rest.setup.workspace, rest.setup.pendingWorktree(), undefined)
+    const decision = yield* decideShip(rest.setup.workspace, tree)
+    if (decision.kind === "blocked") return refusedSnapshot(rest, decision.message)
+    const shipping = decision.kind === "ship"
+    const decided = yield* decideLanding(
+      rest,
+      verdicts,
+      branch,
+      approver,
+      shipping ? SHIPPED_STAND_IN : undefined,
+    )
+    if (decided.kind !== "commit") return snapshotOf(rest, decided)
+    const landing: Landing = shipping
+      ? {
+          ...decided,
+          ship: {
+            branch: decision.branch,
+            parent: decision.parent,
+            shipMessage: message,
+            historyRef: processHistoryRef(rest.run.startHash),
+          },
+        }
+      : { ...decided, note: decision.note }
+    return snapshotOf(rest, yield* withBranchAndPush(landing))
+  })
+
 /** Every fact the pure landing planner needs, read once: the rest, its steering file, and the landing decision. */
 export const snapshotFromRest = (
   rest: Rest,
   verdicts?: readonly JudgeVerdict[],
-): Effect.Effect<RepoSnapshot, Error, Workspace | GitService> =>
+): Effect.Effect<RepoSnapshot, Error, Workspace | GitService | RestRequirements> =>
   Effect.gen(function* () {
     const git = yield* GitService
-    const branch = yield* git.currentBranch()
+    const branch = yield* userBranch(git)
     const approver = rest.stepDef.approve === true ? yield* git.authorIdent() : Option.none()
-    const landing = yield* decideLanding(rest, verdicts, branch, approver)
-    return {
-      stepDef: rest.stepDef,
-      state: rest.state,
-      actor: rest.actor,
-      changes: rest.changes,
-      file: rest.hints.file,
-      landing,
+    const request = rest.step.request
+    if (rest.pin === undefined && request.kind === "ship") {
+      return yield* shipSnapshot(rest, request.message, verdicts, branch, approver)
     }
+    const decided = yield* decideLanding(rest, verdicts, branch, approver)
+    return snapshotOf(rest, yield* withBranchAndPush(decided))
   })
 
 // ── Summary ─────────────────────────────────────────────────────────────────

package/src/emit/GitScript.ts

@@ -12,8 +12,11 @@ export const pathspec = (paths: ReadonlyArray<string>): string => paths.map(shel
  * output rather than the exit code, so a genuinely rejected commit (a lint
  * error, a commit-msg hook) still fails.
  */
-const commitAllowEmpty = (message: string, only?: string): string => {
-  const m = shellQuote(message)
+const commitAllowEmpty = (message: string, only?: string): string =>
+  commitWordAllowEmpty(shellQuote(message), only)
+
+/** `commitAllowEmpty` over a message that is already a shell word. */
+const commitWordAllowEmpty = (m: string, only?: string): string => {
   const paths = only === undefined ? "" : ` -- ${shellQuote(only)}`
   return [
     `if ! out=$(git commit --allow-empty -m ${m}${paths} 2>&1); then`,
@@ -36,6 +39,29 @@ export const commitAll = (message: string): string =>
 export const commitPath = (path: string, message: string): string =>
   `git add -A -- ${shellQuote(path)} || exit 1\n${commitAllowEmpty(message, path)}`
 
+/**
+ * A `run()` body that records its own failure instead of failing the beat: the
+ * status and the last 50 output lines go to `path`, and the script exits zero
+ * so the turn lands. The file is COMMITTED (and force-pushed with a history
+ * remote), hence the cap.
+ */
+export const failRestScript = (body: string, path: string): string => {
+  const p = shellQuote(path)
+  const slash = path.lastIndexOf("/")
+  return [
+    `rm -f -- ${p}`,
+    `gtd_run_status=0`,
+    `gtd_run_out="$( {`,
+    body,
+    `} 2>&1 )" || gtd_run_status=$?`,
+    `printf '%s\\n' "$gtd_run_out"`,
+    `if [ "$gtd_run_status" -ne 0 ]; then`,
+    `  mkdir -p ${shellQuote(path.slice(0, slash))}`,
+    `  printf 'exit %s\\n%s\\n' "$gtd_run_status" "$(printf '%s\\n' "$gtd_run_out" | tail -n 50)" >${p}`,
+    `fi`,
+  ].join("\n")
+}
+
 /** A pin beat's script. A failed `gtd bundle` leaves no half-written pin behind. */
 export const pinScript = (path: string): string => {
   const p = shellQuote(path)
@@ -123,6 +149,77 @@ export const keepTurn = (refPrefix: string, message: string): string => {
   ].join("\n")
 }
 
+/** `git switch -C <branch> [<start>]`: create or reset the branch, carrying pending changes over. */
+export const switchBranchTo = (branch: string, start?: string): string =>
+  `git switch -q -C ${shellQuote(branch)}${start === undefined ? "" : ` ${shellQuote(start)}`}`
+
+/** `git switch <branch>`: an existing branch, carrying pending changes over. */
+export const switchTo = (branch: string): string => `git switch -q ${shellQuote(branch)}`
+
+/** `switchTo` that, when pending changes block it, stays put and says so: the landing already happened. */
+export const switchBack = (branch: string): string =>
+  [
+    `if ! git switch -q ${shellQuote(branch)} 2>/dev/null; then`,
+    `  printf '%s\\n' ${shellQuote(`gtd: pending changes keep HEAD off ${branch}; switch to it once they are committed or stashed`)}`,
+    `fi`,
+  ].join("\n")
+
+export const deleteBranch = (branch: string): string => `git branch -q -D ${shellQuote(branch)}`
+
+/**
+ * Force-pushes one ref to a remote. A failed push exits non-zero with the retry
+ * on stderr: it runs after the closing commit has landed, so the commit stands.
+ */
+export const pushRef = (remote: string, ref: string): string => {
+  const retry = `git push --force ${shellQuote(remote)} ${shellQuote(`${ref}:${ref}`)}`
+  return [
+    `if ! ${retry}; then`,
+    `  printf '%s\\n' ${shellQuote(`gtd: pushing ${ref} failed — retry: ${retry}`)} >&2`,
+    `  exit 1`,
+    `fi`,
+  ].join("\n")
+}
+
+/**
+ * A ship step's landing, in one block because the landing commit's
+ * `Gtd-Shipped` trailer names the squash it makes first. The squash carries
+ * the staged tree with `.gtd/` as `<branch>` has it, built in a scratch index; `<branch>` moves by
+ * compare-and-swap against `parent`, so a branch moved since the decision
+ * fails the script before the landing commits. `commit-tree` ignores
+ * `commit.gpgSign`, so it is read here.
+ */
+export const shipCommit = (
+  branch: string,
+  parent: string,
+  shipMessage: string,
+  historyRef: string,
+  message: string,
+): string =>
+  [
+    `gtd_ship_parent=${shellQuote(parent)}`,
+    `gtd_ship_branch=${shellQuote(branch)}`,
+    `gtd_ship_history=${shellQuote(historyRef)}`,
+    `gtd_ship_message=${shellQuote(shipMessage)}`,
+    `gtd_land_message=${shellQuote(message)}`,
+    `git add -A || exit 1`,
+    `gtd_sign_cfg=$(git config --type=bool --default=false commit.gpgSign) || exit 1`,
+    `if [ "$gtd_sign_cfg" = true ]; then gtd_sign=-S; else gtd_sign=--no-gpg-sign; fi`,
+    `gtd_head=$(git rev-parse --verify HEAD) || exit 1`,
+    `gtd_tree=$(git write-tree) || exit 1`,
+    `gtd_index=$(git rev-parse --git-path gtd-ship-index) || exit 1`,
+    `rm -f -- "$gtd_index"`,
+    `GIT_INDEX_FILE="$gtd_index" git read-tree "$gtd_tree" || exit 1`,
+    `GIT_INDEX_FILE="$gtd_index" git rm -r -q --cached --ignore-unmatch -- .gtd || exit 1`,
+    `git ls-tree -r "$gtd_ship_parent" -- .gtd | GIT_INDEX_FILE="$gtd_index" git update-index --index-info || exit 1`,
+    `gtd_ship_tree=$(GIT_INDEX_FILE="$gtd_index" git write-tree) || exit 1`,
+    `rm -f -- "$gtd_index"`,
+    `gtd_ship_trailers=$(printf "Gtd-History: %s\\nGtd-Tip: %s" "$gtd_ship_history" "$gtd_head")`,
+    `gtd_shipped=$(git commit-tree "$gtd_sign" "$gtd_ship_tree" -p "$gtd_ship_parent" -m "$gtd_ship_message" -m "$gtd_ship_trailers") || exit 1`,
+    `git update-ref -m "gtd: ship" "refs/heads/$gtd_ship_branch" "$gtd_shipped" "$gtd_ship_parent" || exit 1`,
+    `gtd_message=$(printf "%s\\nGtd-Shipped: %s" "$gtd_land_message" "$gtd_shipped")`,
+    commitWordAllowEmpty(`"$gtd_message"`),
+  ].join("\n")
+
 export const updateRef = (ref: string, hash: string): string =>
   `git update-ref ${shellQuote(ref)} ${shellQuote(hash)}`
 
@@ -170,21 +267,25 @@ const renderOutcome = (outcome: Outcome): string => {
   }
 }
 
-const renderGitWrite = (write: GitWrite): string => {
-  switch (write.kind) {
-    case "commitAll":
-      return commitAll(write.message)
-    case "commitPath":
-      return commitPath(write.path, write.message)
-    case "commitClean":
-      return commitClean(write.message)
-    case "updateRef":
-      return updateRef(write.ref, write.target)
-    case "keepTurn":
-      return keepTurn(write.ref, write.message)
-  }
+type Renderers = {
+  readonly [K in GitWrite["kind"]]: (write: Extract<GitWrite, { kind: K }>) => string
+}
+
+const GIT_WRITES: Renderers = {
+  commitAll: (w) => commitAll(w.message),
+  commitPath: (w) => commitPath(w.path, w.message),
+  commitClean: (w) => commitClean(w.message),
+  updateRef: (w) => updateRef(w.ref, w.target),
+  keepTurn: (w) => keepTurn(w.ref, w.message),
+  switchBranch: (w) => switchBranchTo(w.branch),
+  switchTo: (w) => switchBack(w.branch),
+  pushRef: (w) => pushRef(w.remote, w.ref),
+  ship: (w) => shipCommit(w.branch, w.parent, w.shipMessage, w.historyRef, w.message),
 }
 
+const renderGitWrite = (write: GitWrite): string =>
+  (GIT_WRITES[write.kind] as (write: GitWrite) => string)(write)
+
 /**
  * Wraps `command` so a non-zero exit prints `prompt` plus the command's
  * captured output before propagating that exit code — mirrors `Emit.ts`'s

package/src/emit/index.ts

@@ -18,6 +18,7 @@ export {
   commitClean,
   commitPath,
   pinScript,
+  failRestScript,
   repinScript,
   unpinScript,
   CHANGED_SINCE_LAND,
@@ -28,6 +29,12 @@ export {
   updateRef,
   keepTurn,
   deleteRef,
+  switchBranchTo,
+  switchBack,
+  switchTo,
+  deleteBranch,
+  pushRef,
+  shipCommit,
   fetchHistoryRefs,
   type RunnableScript,
   ScriptSurface,

package/src/flows/config.ts

@@ -21,6 +21,8 @@ export interface GtdConfig {
   readonly ui?: UiSettings
   readonly skills?: Readonly<Record<string, readonly string[]>>
   readonly access?: Readonly<Record<string, ScopeAccess>>
+  /** A remote name: every finished or abandoned process force-pushes its history ref there. */
+  readonly historyRemote?: string
 }
 
 export interface ConfigProblem {
@@ -28,7 +30,7 @@ export interface ConfigProblem {
   readonly message: string
 }
 
-const CONFIG_KEYS = ["modes", "ui", "skills", "access"] as const
+const CONFIG_KEYS = ["modes", "ui", "skills", "access", "historyRemote"] as const
 const MODE_KEYS = ["format", "validate"] as const
 const UI_KEYS = ["port", "host", "cert", "key", "format"] as const
 
@@ -113,6 +115,10 @@ export const configProblems = (value: unknown): readonly ConfigProblem[] => {
     ...unknownKeys(value, CONFIG_KEYS, []),
     ...(value.modes === undefined ? [] : recordOf(value.modes, ["modes"], "modes", modeProblems)),
     ...(value.ui === undefined ? [] : uiProblems(value.ui, ["ui"])),
+    ...(value.historyRemote === undefined ||
+    (typeof value.historyRemote === "string" && value.historyRemote.trim() !== "")
+      ? []
+      : [{ path: ["historyRemote"], message: "must be a non-empty remote name" }]),
     ...(value.skills === undefined
       ? []
       : recordOf(value.skills, ["skills"], "skill-name arrays", (v, path) =>

package/src/flows/index.test.ts

@@ -53,6 +53,7 @@ describe("@pmelab/gtd/flows", () => {
         "sections",
         "settings",
         "settingsOf",
+        "ship",
         "showScript",
         "skillsFor",
         "start",