@pmelab/gtd 27.6.0 → 27.7.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gtd",
-  "version": "27.6.0",
+  "version": "27.7.1",
   "description": "Drive the gtd loop inside Claude Code: agent turns run as subagents, gtd decides every beat",
   "author": {
     "name": "Philipp Melab"

package/README.md

@@ -324,18 +324,26 @@ Then, in any repository:
 /gtd Add a --json flag to the export command
 ```
 
-That starts a process from your requirements and drives it until it needs you.
-`/gtd fix` and `/gtd review [base]` take the two doors described below. At every
-human rest Claude itself takes over: it walks you through the open questions one
-at a time, answers your own questions about the plan or the diff, records what
-you decide in the steering file the way the step asks, and moves the process on
-only when you say so. While a step runs you can keep asking; requests for
-changes wait for the next rest. When the process finishes, Claude offers to
-squash it into one commit and open its pull request (or run `/gtd ship`). A
-process can change hands at any gate: ask Claude to hand it off (or run
-`/gtd throw @dev`) and it opens a draft pull request assigned to them, and
-`/gtd catch <pr>` picks it up exactly where it waits, so whoever wrote the
-requirements can hand the architecture to someone else. See
+That starts a process from your requirements and drives it until it needs you. A
+long, multi-line requirements paste still starts a process; if Claude Code never
+expanded the paste, gtd says it could not read it, and you write the
+requirements to `.gtd/TODO.md` and run `/gtd`. `/gtd fix` and
+`/gtd review [base]` take the two doors described below. At every human rest
+Claude itself takes over: it walks you through the open questions one at a time,
+answers your own questions about the plan or the diff, records what you decide
+in the steering file the way the step asks, and moves the process on only when
+you say so; a review you leave untouched signs off. While a step runs you can
+keep asking; requests for changes wait for the next rest. When the process
+finishes, Claude offers to squash it into one commit and open its pull request
+(or run `/gtd ship`). A process can change hands at any gate: ask Claude to hand
+it off (or run `/gtd throw @dev`) and it opens a draft pull request assigned to
+them, and `/gtd catch <pr>` picks it up exactly where it waits, so whoever wrote
+the requirements can hand the architecture to someone else. Ship, hand-off and
+throw answer at once and run in the background, with progress on the status
+line; they report by waking Claude, a toast, a transcript line and a push
+notification, and a failed push or `gh` call reports as a failure. While a ship
+or hand-off runs or is queued, `/gtd catch`, the doors, `/gtd <requirements>`
+and bare `/gtd` wait for its report. See
 [Inside Claude Code](https://github.com/pmelab/gtd/blob/main/docs/driver.md#inside-claude-code-the-gtd-mod).
 
 ### Then let an agent build your own
@@ -416,7 +424,7 @@ noted in steps 3 and 4 below.
    `gtd judge run --provider jev` asks TypeSafe's Jev instead, with the key in
    `TYPESAFE_API_KEY` and `JEV_BASE_URL` optionally overriding the endpoint;
    `gtd judge run --provider llm` asks the `claude` CLI on `PATH` (Claude Code
-   users only; model `haiku`, `--model <name>` overrides) and reuses its login.
+   users only; model `sonnet`; `--model <name>` overrides) and reuses its login.
    With no `--provider`, `gtd judge run` picks jev when `TYPESAFE_API_KEY` is
    set and non-empty and no `--model` is given, else llm — never falling back
    across them; the `GTD_JUDGE_PROVIDER` / `GTD_JUDGE_MODEL` environment
@@ -431,7 +439,8 @@ noted in steps 3 and 4 below.
 
    gtd itself never calls a judge: `gtd loop`, the Claude Code mod and the
    reference driver answer these through `gtd judge run` (auto selection: jev
-   when `TYPESAFE_API_KEY` is set, else `llm` via `claude`, default model haiku,
+   when `TYPESAFE_API_KEY` is set, else `llm` via `claude`, default model
+   sonnet, while the Claude Code mod's own judge subagent stays on `haiku` —
    `--model <name>` overrides); if that fails it shows you the message and
    stops. **The `llm` provider's `p` is self-reported by the model, not a
    measured probability, so a confidently wrong verdict can clear the 0.7 floor
@@ -576,6 +585,8 @@ Two more bundled workflows retire a release flag:
 `gtd --workflow cleanup --var flag=<name>` removes it afterwards. See
 [Feature flags](docs/configuration.md#rolling-out-and-cleaning-up-a-release-flag).
 
+The delivery model these workflows implement: [Delivery model](SDLC.md).
+
 ## Checking a range for stray files
 
 ```sh

package/claude/hooks/assist.ts

@@ -5,7 +5,9 @@
 
 import type { Stop } from "../types"
 import { RELOAD_CUT_SCRIPT } from "./wording"
-import { TOOL } from "./tools"
+import type { Shipped } from "./ship"
+import { JOB_NAME, TOOL } from "./tools"
+import type { JobName } from "./tools"
 
 export type Asked = {
   id: string
@@ -35,7 +37,13 @@ export function wakes(stop: Stop, branch: string | undefined): boolean {
 
 const step = (s: Stop) => s.label ?? s.state ?? "the current step"
 
-const fence = (text: string) => `~~~~text\n${text.trim()}\n~~~~`
+// The text can come from commit messages anyone on the branch wrote: the fence
+// is longer than any run of ~ inside it, so the text cannot close it early.
+const fence = (text: string) => {
+  const body = text.trim()
+  const bar = "~".repeat(Math.max(4, ...[...body.matchAll(/~+/g)].map((m) => m[0].length + 1)))
+  return `${bar}text\n${body}\n${bar}`
+}
 
 const RULES = `Ground rules:
 - gtd decides what happens next. Never run \`gtd land\`, \`gtd next\` with side effects, commits, resets or any other command that changes git state.
@@ -133,3 +141,28 @@ export function wakePrompt(w: Wake): string {
   const extras = `Only when the person asks: ${TOOL.handoff} hands the process to someone else, ${TOOL.browser} opens gtd's browser view of this step.`
   return [...body, ...notes, RULES, extras].join("\n\n")
 }
+
+// The wake after a background ship or hand-off ended: the model only relays it.
+export function jobPrompt(job: JobName, outcome: Shipped): string {
+  const name = JOB_NAME[job]
+  if (outcome.ok) {
+    return [
+      `The ${name} the person asked for finished. gtd's report:`,
+      fence(outcome.text),
+      "Relay the result to the person in a line or two, with any link in it. Do nothing else.",
+    ].join("\n\n")
+  }
+  const lines = [
+    `The ${name} the person asked for failed. gtd reports the failed step:`,
+    fence(outcome.text),
+  ]
+  if (job === "ship") {
+    lines.push(
+      `If the commits were already squashed, they stay squashed: running /gtd ship again pushes the already-squashed branch.`,
+    )
+  }
+  lines.push(
+    "Tell the person what failed in plain words and what to try. Do not retry it yourself.",
+  )
+  return lines.join("\n\n")
+}

package/claude/hooks/delegate.ts

@@ -0,0 +1,22 @@
+export type AnswerIo = {
+  ended: Promise<{ ok: boolean }>
+  deadline: Promise<unknown>
+  read(): Promise<string>
+  remove(): Promise<unknown>
+}
+
+export async function collectAnswer(io: AnswerIo): Promise<string | undefined> {
+  const ended = await Promise.race([io.ended, io.deadline.then(() => undefined)])
+  if (!ended) {
+    // The agent may still write the file: remove it only once its turn ends.
+    void io.ended.then(io.remove).catch(() => undefined)
+    return undefined
+  }
+  try {
+    return ended.ok ? await io.read() : undefined
+  } catch {
+    return undefined
+  } finally {
+    await io.remove()
+  }
+}

package/claude/hooks/handoff.ts

@@ -43,11 +43,17 @@ export async function throwTo(
     if (assigned) return fail(assigned)
   }
   const to = handle ? `to @${handle}` : "to anyone"
-  await io.run(
+  const commented = await io.run(
     ["gh", "pr", "comment", String(pr.number), "--body-file", "-"],
     `Thrown ${to} at **${at}**. Catch it with \`/gtd catch ${on.branch}\`.\n`,
   )
-  return { ok: true, text: `Thrown ${to}: ${pr.url}` }
+  // The hand-off already happened: failing here would keep the run open locally
+  // while the pull request is someone else's.
+  const warning =
+    commented.code === 0
+      ? ""
+      : `\nWarning: gh pr comment failed; no catch hint was posted.\n${commented.err}`
+  return { ok: true, text: `Thrown ${to}: ${pr.url}${warning}` }
 }
 
 // The catcher checks out what origin holds, so a throw describing local HEAD
@@ -141,8 +147,11 @@ async function draft(
   // A pull request someone opened for review keeps its own description and
   // stays ready: only ship marks a draft ready again, and only a thrown one.
   if (pr.body?.includes(THROWN)) {
-    await io.run(["gh", "pr", "edit", String(pr.number), "--body-file", "-"], body)
-    await io.run(["gh", "pr", "ready", String(pr.number), "--undo"])
+    const edited = await io.run(["gh", "pr", "edit", String(pr.number), "--body-file", "-"], body)
+    if (edited.code !== 0) return `gh pr edit failed; the pull request is unchanged.\n${edited.err}`
+    const undone = await io.run(["gh", "pr", "ready", String(pr.number), "--undo"])
+    if (undone.code !== 0)
+      return `gh pr ready --undo failed; ${pr.url} is not a draft again.\n${undone.err}`
   }
   return pr
 }

package/claude/hooks/jobs.ts

@@ -0,0 +1,67 @@
+// The one background slot ship and hand-off share: both push the branch, so
+// two at once would race. No global deadline on purpose: a deadline that freed
+// the slot while the work still ran would let a second push overwrite the first.
+
+import type { Shipped } from "./ship"
+import type { JobName } from "./tools"
+import { JOB_NAME } from "./tools"
+
+export type Jobs = {
+  // Claims the slot now; `work` starts at once or, `isInTurn`, at the next
+  // `flush`. `done` runs when it ends, either way, and owns the job's effect
+  // and report. Answers at once: the started text, or a refusal when a job is
+  // running or queued.
+  start(
+    job: JobName,
+    work: () => Promise<Shipped>,
+    isInTurn: boolean,
+    done: (outcome: Shipped) => Promise<void>,
+  ): string
+  flush(): void
+  busy(): JobName | undefined
+}
+
+export function jobs(): Jobs {
+  let current:
+    | {
+        job: JobName
+        work: () => Promise<Shipped>
+        done: (outcome: Shipped) => Promise<void>
+        isRunning: boolean
+      }
+    | undefined
+
+  const launch = () => {
+    const slot = current
+    if (!slot || slot.isRunning) return
+    slot.isRunning = true
+    void (async () => {
+      let outcome: Shipped
+      try {
+        outcome = await slot.work()
+      } catch (err) {
+        outcome = { ok: false, text: err instanceof Error ? err.message : String(err) }
+      } finally {
+        current = undefined
+      }
+      try {
+        await slot.done(outcome)
+      } catch {
+        // a failed report must not become an unhandled rejection
+      }
+    })()
+  }
+
+  return {
+    start(job, work, isInTurn, done) {
+      if (current) {
+        return `A ${JOB_NAME[current.job]} is already being prepared; wait for its report.`
+      }
+      current = { job, work, done, isRunning: false }
+      if (!isInTurn) launch()
+      return `The ${JOB_NAME[job]} has started in the background; its outcome is reported here when it ends.`
+    },
+    flush: launch,
+    busy: () => current?.job,
+  }
+}

package/claude/hooks/paste.ts

@@ -0,0 +1,17 @@
+export type Pasted = { arg: string } | { lost: string }
+
+const PLACEHOLDER = /\[Pasted text #\d+[^\]]*\]/
+
+// The mod cannot recover an unexpanded paste: Claude Code's paste cache is keyed
+// by a hash it does not expose.
+export function pastedCommand(text: string): Pasted | undefined {
+  const m = /^\/gtd\s+([\s\S]*)$/.exec(text)
+  const arg = m?.[1]?.trim()
+  if (!arg) return undefined
+  if (PLACEHOLDER.test(arg)) {
+    return {
+      lost: "The pasted requirements did not arrive whole. Write them to .gtd/TODO.md and run /gtd.",
+    }
+  }
+  return { arg }
+}

package/claude/hooks/register.tsx

@@ -4,22 +4,28 @@ import type { EngineInterface, Register } from "claude-code"
 import type { Run, Stop } from "../types"
 import { accessDenial, mainDenial } from "./access"
 import type { AccessDef } from "./access"
-import { wakePrompt, wakes } from "./assist"
+import { jobPrompt, wakePrompt, wakes } from "./assist"
 import { afterReload, drive, isTrue } from "./drive"
 import type { Io, Opening, Turn, TurnEnd } from "./drive"
 import { doors, enter } from "./doors"
 import { subagentModel } from "./models"
+import { pastedCommand } from "./paste"
 import { personaSpec, resumable } from "./persona"
 import { JUDGE_SYSTEM, judgePrompt, judgeQuestions, judgeRunEnv, toVerdicts } from "./judge"
 import type { Judgment } from "./judge"
 import { catchFrom, throwTo } from "./handoff"
+import { jobs } from "./jobs"
 import { documents, readDocument } from "./schema"
 import { READ_ONLY_GIT, ship } from "./ship"
-import type { ShipIo } from "./ship"
-import { decideContinue, restId, TOOLS } from "./tools"
+import type { Shipped, ShipIo } from "./ship"
+import { collectAnswer } from "./delegate"
+import { decideCommand, decideContinue, decideJob, restId, TOOLS } from "./tools"
+import type { JobName } from "./tools"
 import {
   beatLine,
   headline,
+  jobHeadline,
+  jobPushText,
   pushText,
   restartLine,
   RELOAD_CUT_SCRIPT,
@@ -52,7 +58,6 @@ let stepStartedAt = Date.now()
 // Set before the first await of `start`, so two Continue presses arriving
 // together cannot both pass the isRunning check and start two drivers.
 let isDriving = false
-let isShipping = false
 // bumped by every stop, so a queued continue that was mid-check sees it
 let stopCount = 0
 // subagents answering into a file: what each may touch (see tool.call)
@@ -219,7 +224,7 @@ async function head($: $) {
 }
 
 async function start($: $, opening: Opening = {}) {
-  if (isDriving) return
+  if (isDriving || background.busy()) return
   isDriving = true
   closeUi()
   moveOn($)
@@ -371,45 +376,75 @@ async function browse($: $) {
 
 // A gate is news even when nobody watches the terminal: a push reaches the
 // phone over Remote Control, and the engine drops it while the person is here.
+const repoName = () => root.split("/").pop() ?? "gtd"
+
 async function push($: $, stop: Stop, url?: string) {
-  const repo = root.split("/").pop() ?? "gtd"
+  await notify($, pushText(stop, repoName(), url))
+}
+
+async function notify($: $, message: string) {
   try {
-    await $.tool.call({
-      tool: "PushNotification",
-      message: pushText(stop, repo, url),
-      status: "proactive",
-    })
+    await $.tool.call({ tool: "PushNotification", message, status: "proactive" })
   } catch {
     // no push channel: the dialog and the band still say it
   }
 }
 
-async function throwNow($: $, target: string | undefined) {
-  if ((await read($, run)).isRunning) return "Stop the loop first: /gtd stop."
-  closeUi()
-  moveOn($)
-  const b = await docs($).next()
-  $.ui.status("handing off…")
-  const rest = {
-    state: b.state,
-    label: b.label,
-    content: b.content,
-    isIdle: isTrue(b.idle),
-  }
-  const thrown = await throwTo(shipIo($), rest, target, new Date().toISOString()).catch(
-    (err: unknown) => ({ ok: false, text: String(err) }),
+const background = jobs()
+
+// A job asked from the model's tool call waits for that turn to end; one asked
+// from the command starts right after, off the hook, so the command answers in
+// budget. Either way the slot is claimed now, with the job's own effect.
+function startJob(
+  $: $,
+  job: JobName,
+  isInTurn: boolean,
+  work: () => Promise<Shipped>,
+  then?: (outcome: Shipped) => Promise<void>,
+) {
+  const answer = background.start(job, work, true, async (outcome) => {
+    if (then) await then(outcome)
+    $.ui.status(undefined)
+    for (const line of outcome.text.split("\n")) $.ui.log(line)
+    $.ui.toast(jobHeadline(job, outcome))
+    await notify($, jobPushText(job, outcome, repoName()))
+    const text = jobPrompt(job, outcome)
+    $.clock.after(0, () => void $.prompt.submit({ text }))
+  })
+  if (!isInTurn) $.clock.after(0, () => background.flush())
+  return answer
+}
+
+async function throwNow($: $, target: string | undefined, isInTurn: boolean) {
+  const refused = decideJob(await read($, run), "handoff")
+  if (refused) return refused
+  return startJob(
+    $,
+    "handoff",
+    isInTurn,
+    async () => {
+      closeUi()
+      moveOn($)
+      const b = await docs($).next()
+      $.ui.status("handing off…")
+      const rest = {
+        state: b.state,
+        label: b.label,
+        content: b.content,
+        isIdle: isTrue(b.idle),
+      }
+      return throwTo(shipIo($), rest, target, new Date().toISOString())
+    },
+    async (thrown) => {
+      if (!thrown.ok) return
+      await update($, run, (r) => ({
+        ...r,
+        url: undefined,
+        uiNote: undefined,
+        stop: { kind: "stopped" as const, text: thrown.text },
+      }))
+    },
   )
-  $.ui.status(undefined)
-  for (const line of thrown.text.split("\n")) $.ui.log(line)
-  if (thrown.ok) {
-    await update($, run, (r) => ({
-      ...r,
-      url: undefined,
-      uiNote: undefined,
-      stop: { kind: "stopped" as const, text: thrown.text },
-    }))
-  }
-  return thrown.text
 }
 
 async function enterNow($: $, door: string, args: string[]) {
@@ -499,15 +534,14 @@ async function delegate($: $, who: Delegate, prompt: string, model: string, deli
   if (!id) return undefined
   ours.add(id)
   delegates.set(id, { file, mayRun: who.mayRun })
-  const ended = await turnEnd(id)
-  delegates.delete(id)
-  try {
-    return ended.ok ? await $.fs.read(file) : undefined
-  } catch {
-    return undefined
-  } finally {
-    await $.process.run(["rm", "-f", file])
-  }
+  // A timed-out agent may still be running: it keeps its tool limits until its
+  // turn ends, where turn.complete drops them.
+  return collectAnswer({
+    ended: turnEnd(id),
+    deadline: $.clock.sleep(TEN_MINUTES),
+    read: () => $.fs.read(file),
+    remove: () => $.process.run(["rm", "-f", file]),
+  })
 }
 
 async function writer($: $, prompt: string) {
@@ -544,25 +578,28 @@ function shipIo($: $): ShipIo {
     complete: (prompt) => writer($, prompt),
     log: (line) => {
       for (const l of line.split("\n")) $.ui.log(l)
+      if (background.busy()) $.ui.status(line.split("\n")[0]!)
     },
     today: () => new Date().toISOString().slice(0, 10),
   }
 }
 
-async function shipNow($: $, isDry: boolean) {
-  if (isShipping) return "A pull request is already being prepared."
-  isShipping = true
-  await dismiss($)
-  $.ui.status(isDry ? "previewing the pull request…" : "opening the pull request…")
-  const shipped = await ship(shipIo($), isDry).catch((err: unknown) => ({
-    ok: false,
-    text: String(err),
-  }))
-  isShipping = false
-  $.ui.status(undefined)
-  for (const line of shipped.text.split("\n")) $.ui.log(line)
-  $.ui.toast(shipped.ok ? "pull request ready" : "opening the pull request failed")
-  return shipped.text
+async function shipNow($: $, isDry: boolean, isInTurn: boolean) {
+  const refused = decideJob(await read($, run), "ship")
+  if (refused) return refused
+  return startJob(
+    $,
+    "ship",
+    isInTurn,
+    async () => {
+      $.ui.status(isDry ? "previewing the pull request…" : "opening the pull request…")
+      return ship(shipIo($), isDry)
+    },
+    async (shipped) => {
+      // a failed ship leaves the run as it was; a dry run changes nothing
+      if (shipped.ok && !isDry) await dismiss($)
+    },
+  )
 }
 
 // Turns a missing CLI or a wrong directory into an instruction, not a stack trace.
@@ -641,6 +678,7 @@ async function proceed(
   const go = await decideContinue(r, rest, verdicts, {
     current: () => currentRest($, r.stop?.state),
     validate: () => validateRest($),
+    busy: background.busy(),
     judgment: async () => {
       const doc = await gtd($, ["judge", "--json"]).catch(() => undefined)
       return doc === undefined ? undefined : readDocument<Judgment>("judge --json", doc)
@@ -765,6 +803,8 @@ async function stopNow($: $) {
 // `/gtd [verb] …`; anything that is not a verb is a new process's requirements.
 async function command($: $, arg: string): Promise<string | undefined> {
   if (arg === "stop") return stopNow($)
+  const busy = decideCommand(arg, background.busy())
+  if (busy) return busy
   const problem = await preflight($)
   if (problem) return problem
   const [verb = "", ...rest] = arg.split(/\s+/)
@@ -772,7 +812,7 @@ async function command($: $, arg: string): Promise<string | undefined> {
     case "status":
       return gtd($, ["next"])
     case "throw":
-      return throwNow($, rest[0])
+      return throwNow($, rest[0], false)
     case "ui":
       return browse($)
     case "catch":
@@ -780,7 +820,7 @@ async function command($: $, arg: string): Promise<string | undefined> {
         ? catchNow($, rest[0])
         : "Name the pull request or branch: /gtd catch <number|branch>."
     case "ship":
-      return shipNow($, rest[0] === "-n" || rest[0] === "--dry-run")
+      return shipNow($, rest[0] === "-n" || rest[0] === "--dry-run", false)
     case "":
       return resume($)
     default:
@@ -912,10 +952,14 @@ export const register: Register = (on) => {
   }).catch(($, e, next) => ({ text: next.error.message }))
 
   on("turn.complete", ($, e, next) => {
-    if (!e.agentId) void launchPending($)
+    if (!e.agentId) {
+      background.flush()
+      void launchPending($)
+    }
     if (e.agentId && ours.has(e.agentId)) {
       const end: TurnEnd =
         e.reason === "answer" ? { ok: true } : { ok: false, why: `agent turn ended: ${e.reason}` }
+      delegates.delete(e.agentId)
       const resolve = waiting.get(e.agentId)
       waiting.delete(e.agentId)
       if (resolve) resolve(end)
@@ -943,7 +987,24 @@ export const register: Register = (on) => {
   // A subagent's hand-back arrives as a prompt to the main session, whose model
   // would then act on it. gtd reads the turn's result from git instead.
   on("prompt.submit", async ($, e, next) => {
-    if (!e.origin || e.origin.kind === "composer" || e.origin.kind === "bridge") return next(e)
+    if (!e.origin || e.origin.kind === "composer" || e.origin.kind === "bridge") {
+      const pasted = pastedCommand(e.text)
+      if (!pasted) return next(e)
+      // Off the hook: preflight may install gtd's runtime and outlast its budget.
+      const say = (text: string) => {
+        for (const line of text.split("\n")) $.ui.log(line)
+        $.ui.toast(text.split("\n")[0]!)
+      }
+      if ("lost" in pasted) say(pasted.lost)
+      else {
+        $.clock.after(0, () => {
+          void command($, pasted.arg)
+            .then((text) => text && say(text))
+            .catch((err) => say(err instanceof Error ? err.message : String(err)))
+        })
+      }
+      return { drop: "gtd took the command" }
+    }
     if ([...ours].some((id) => e.text.includes(`from="${id}"`))) {
       return { drop: DROPPED }
     }
@@ -957,10 +1018,10 @@ export const register: Register = (on) => {
     answer(await note($, String(e.text ?? "")), true),
   )
   on("tool.call", { tool: "mcp__gtd__handoff" }, async ($, e) =>
-    answer(await throwNow($, typeof e.to === "string" && e.to ? e.to : undefined), true),
+    answer(await throwNow($, typeof e.to === "string" && e.to ? e.to : undefined, true), true),
   )
   on("tool.call", { tool: "mcp__gtd__ship" }, async ($, e) =>
-    answer(await shipNow($, e.dryRun === true), true),
+    answer(await shipNow($, e.dryRun === true, true), true),
   )
   on("tool.call", { tool: "mcp__gtd__browser" }, async ($) => answer(await browse($), true))
 

package/claude/hooks/ship.ts

@@ -334,13 +334,18 @@ ${await git("diff", "--stat", `${mergeBase}..HEAD`)}`
   const head = await git("rev-parse", "HEAD")
   if (thrown) {
     const n = String(thrown.number)
+    // Ready first: a failure here leaves the THROWN marker, so a retry comes back.
+    const ready = await io.run(["gh", "pr", "ready", n])
+    if (ready.code !== 0)
+      return fail(`gh pr ready failed; ${thrown.url} is unchanged.\n${ready.err}`)
     const edited = await io.run(
       ["gh", "pr", "edit", n, "--title", title, "--body-file", "-"],
       body + "\n",
     )
     if (edited.code !== 0)
-      return fail(`gh pr edit failed; the pull request is unchanged.\n${edited.err}`)
-    await io.run(["gh", "pr", "ready", n])
+      return fail(
+        `gh pr edit failed; ${thrown.url} is marked ready but keeps its thrown title and description.\n${edited.err}`,
+      )
     await io.run(["git", "config", "--local", `branch.${branch}.prSyncHead`, head])
     return { ok: true, text: `Rewrote ${thrown.url} and marked it ready for review.` }
   }

package/claude/hooks/tools.ts

@@ -71,6 +71,37 @@ export type ContinueIo = {
   // the rest's own `gtd validate` script, run; ok when there is nothing to check
   validate(): Promise<{ ok: boolean; out: string }>
   judgment(): Promise<Judgment | undefined>
+  // a ship or hand-off running or queued: it writes the tree the driver would
+  busy?: JobName
+}
+
+export type JobName = "ship" | "handoff"
+
+export const JOB_NAME: Record<JobName, string> = { ship: "ship", handoff: "hand-off" }
+
+const busyText = (job: JobName) => `A ${JOB_NAME[job]} is still running: wait for its report.`
+
+// Only these leave the tree alone (ship and throw refuse for themselves); any
+// other verb, unknown ones included, may switch branch or write .gtd/. `stop`
+// is not here: `command` takes the bare word itself, and `stop <words>` is a
+// requirement. `ui` is not: its page writes steering files.
+const WHILE_BUSY = new Set(["status", "throw", "ship"])
+
+export function decideCommand(arg: string, busy: JobName | undefined): string | undefined {
+  if (!busy) return undefined
+  const verb = arg.trim().split(/\s+/)[0] ?? ""
+  return WHILE_BUSY.has(verb) ? undefined : busyText(busy)
+}
+
+// Pure: a refused job leaves the run, and so `continue`, as it was.
+export function decideJob(run: Run, job: JobName): string | undefined {
+  if (run.isRunning) return "gtd is running a step: wait for it to rest."
+  if (run.pending) return "A continue is already waiting for this turn to end."
+  const kind = run.stop?.kind
+  if (job === "ship" && (kind === "gate" || kind === "stalled" || kind === "error")) {
+    return "gtd still waits on the person at this step: answer it with continue first."
+  }
+  return undefined
 }
 
 // What `continue` may do from here. `rest` undefined is the band's Continue,
@@ -82,6 +113,7 @@ export async function decideContinue(
   io: ContinueIo,
 ): Promise<Proceed> {
   if (run.isRunning) return { refuse: "gtd is already running a step." }
+  if (io.busy) return { refuse: busyText(io.busy) }
   const stop = run.stop
   if (!stop) return { refuse: "Nothing is waiting: gtd has no rest open. /gtd drives it." }
   if (stop.kind === "done") {