@pmelab/gtd 64.2.0 → 65.0.0

package/dist/chunks/{testkit-BwCH8ky6.mjs → testkit-CgrLmpdJ.mjs}

@@ -1,5 +1,5 @@
-import { C as moveScript, D as revertScript, E as restoreScript, H as installContext, K as markedOptions, O as showScript, S as checkScript, T as removeScript, Y as protocolMismatch, i as configure, k as writeScript$1, n as configProblems, o as isFactoryWorkflow, p as numeric, s as answered, t as flows_exports, x as applyScript } from "./flows-dnIE_qbe.mjs";
-import { M as renderFormat, O as ACCESS_REFUSAL, a as renderScriptJson, d as renderLandPlain, f as DEMAND_BRIEFING, g as statusOf, h as renderBeatJson, i as judgeJson, k as PIN_PATH, l as noopText, m as beatDocument, n as resolveSession, o as scriptFields, p as renderBeatPlain, r as selectPath, s as landFields, t as globMatches, u as renderLandJson, v as beatKindOf, y as demandOf } from "./wire-CaPJ9Tme.mjs";
+import { C as moveScript, D as revertScript, E as restoreScript, H as installContext, K as markedOptions, O as showScript, S as checkScript, T as removeScript, Y as protocolMismatch, i as configure, k as writeScript$1, n as configProblems, o as isFactoryWorkflow, p as numeric, s as answered, t as flows_exports, x as applyScript } from "./flows-DGs0W3HI.mjs";
+import { A as RUN_FAILED_PATH, N as renderFormat, O as ACCESS_REFUSAL, a as renderScriptJson, d as renderLandPlain, f as DEMAND_BRIEFING, g as statusOf, h as renderBeatJson, i as judgeJson, k as PIN_PATH, l as noopText, m as beatDocument, n as resolveSession, o as scriptFields, p as renderBeatPlain, r as selectPath, s as landFields, t as globMatches, u as renderLandJson, v as beatKindOf, y as demandOf } from "./wire-BNS8ciNu.mjs";
 import { F as headingSectionBodies, I as formatFinding, a as sections, c as openThreads, d as formatFromSpec, i as sectionBodies, l as steeringFormatFor, o as threads, r as openQuestions, s as BUILT_IN_MODE_NAMES, t as parseCodeThreads, u as unansweredQuestions } from "./steering-DEh_MS40.mjs";
 import { createRequire, isBuiltin } from "node:module";
 import * as Crypto from "node:crypto";
@@ -3306,6 +3306,44 @@ const fromNullishOr = (a) => a == null ? none() : some(a);
 */
 const getOrUndefined$1 = /*#__PURE__*/ getOrElse(constUndefined);
 /**
+* Extracts the value from a `Some`, or throws a default `Error` for `None`.
+*
+* **When to use**
+*
+* Use when you need quick fail-fast unwrapping of an `Option` and a generic
+* error is acceptable.
+*
+* **Details**
+*
+* - `Some` → returns the inner value
+* - `None` → throws `new Error("getOrThrow called on a None")`
+*
+* **Example** (Throwing a default error)
+*
+* ```ts import.meta.vitest
+* import { Option, Result } from "effect"
+*
+* Option.getOrThrow(Option.some(1)) // => 1
+*
+* const failure = Result.try({
+*   try: () => Option.getOrThrow(Option.none()),
+*   catch: (error) => (error as Error).message
+* })
+* Result.getFailure(failure).pipe(Option.getOrElse(() => "no error")) // => "getOrThrow called on a None"
+* ```
+*
+* @see {@link getOrThrowWith} for a custom error
+* @see {@link getOrElse} for a non-throwing alternative
+*
+* @stability stable
+* @category converting
+* @since 2.0.0
+*/
+const getOrThrow$1 = /*#__PURE__*/ (/* @__PURE__ */ dual(2, (self, onNone) => {
+	if (isSome(self)) return self.value;
+	throw onNone();
+}))(() => /* @__PURE__ */ new Error("getOrThrow called on a None"));
+/**
 * Transforms the value inside a `Some` using the provided function, leaving
 * `None` unchanged.
 *
@@ -22479,6 +22517,8 @@ const loopLogPath = gen(function* () {
 // src/platform/RetainedHistory.ts
 /** Per-worktree (`refs/worktree/gtd/*`) so linked worktrees sharing one `.git` don't clobber each other's retained history. */
 const HISTORY_REF = "refs/worktree/gtd/history";
+/** Set by an abandon that left `gtd/<b>` for `<b>`: only then does restore recreate `gtd/<b>`. */
+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`. */
 const PROCESS_HISTORY_PREFIX = "refs/gtd/history/";
 const processHistoryRef = (hash) => `${PROCESS_HISTORY_PREFIX}${hash}`;
@@ -23514,6 +23554,12 @@ const TRAILER_READERS = {
 	"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);
 	},
@@ -23538,6 +23584,8 @@ const parseCommitMessage = (message) => {
 		approved: void 0,
 		pin: void 0,
 		anchor: void 0,
+		shipped: void 0,
+		tip: void 0,
 		judge: [],
 		marks: [],
 		vars: {},
@@ -23579,7 +23627,7 @@ const namesUnpin = (commit) => {
 	const unpin = pinStateIn(commit.parsed.format, "remove");
 	return unpin !== void 0 && commit.parsed.parsed?.to === unpin;
 };
-const actorOfKind = (kind) => kind === "run" ? "check" : kind === "agent" ? "agent" : kind === "human" ? "human" : "judge";
+const actorOfKind = (kind) => kind === "run" || kind === "ship" ? "check" : kind === "agent" ? "agent" : kind === "human" ? "human" : "judge";
 const memoryScopeOf = (name) => {
 	const dot = name.lastIndexOf(".");
 	return dot === -1 ? "" : name.slice(0, dot);
@@ -23713,9 +23761,12 @@ const KNOWN_OPTIONS = {
 		"acceptClean",
 		"approve"
 	]),
-	run: new Set(STEERING_OPTIONS),
+	run: /* @__PURE__ */ new Set([...STEERING_OPTIONS, "onFail"]),
+	ship: /* @__PURE__ */ new Set(["label", "base"]),
 	judge: /* @__PURE__ */ new Set([...STEERING_OPTIONS, "message"])
 };
+const restsOnFail = (step) => step.request.kind === "run" && step.request.options.onFail === "rest";
+const onFailFault = (step) => step.request.kind === "run" && step.request.options.onFail !== void 0 && step.request.options.onFail !== "rest" ? `gtd: step "${step.name}": onFail must be "rest" in run() options` : void 0;
 const unknownOptions = (step) => {
 	const unknown = Object.keys(step.request.options).filter((key) => !KNOWN_OPTIONS[step.kind].has(key));
 	if (unknown.length === 0) return void 0;
@@ -23826,15 +23877,15 @@ const replay = async (raw) => {
 		return calls;
 	};
 	const scoped = (name) => [...scopes.flatMap((s) => s.name === void 0 ? [] : [s.name]), name].join(".");
-	const isAttemptAt = (commit, name) => commit.parsed.step === void 0 && commit.parsed.parsed !== void 0 && commit.parsed.parsed.from === void 0 && commit.parsed.parsed.to === name && isEmptyDiff(diffTrees$1(position.tree, commit.tree));
+	const isAttemptAt = (commit, step) => commit.parsed.step === void 0 && commit.parsed.parsed !== void 0 && commit.parsed.parsed.from === void 0 && commit.parsed.parsed.to === step.name && (isEmptyDiff(diffTrees$1(position.tree, commit.tree)) || restsOnFail(step) && commit.tree.read(".gtd/run-failed.txt") !== void 0);
 	const advance = (next) => {
 		previousPosition = position;
 		position = next;
 	};
-	const replyFor = (request, verdicts) => request.kind === "judge" ? {
+	const replyFor = (request, verdicts, shipped) => request.kind === "judge" ? {
 		answers: answersFrom(verdicts, request.questions),
 		truncated: judgeCuts.get(request) ?? []
-	} : void 0;
+	} : request.kind === "ship" ? shipped : void 0;
 	const judgeCuts = /* @__PURE__ */ new WeakMap();
 	const resolveScoped = (memory, pick, configured, bundled) => {
 		const own = /* @__PURE__ */ new Map();
@@ -23948,7 +23999,7 @@ const replay = async (raw) => {
 		expectedNext = void 0;
 		anchorPending = false;
 		if (expected !== void 0 && expected.name !== step.name) return diverged(`gtd: commit ${short(expected.hash)} names "${expected.name}" as the next step, but replay reached "${step.name}"`, step);
-		const error = unknownOptions(step) ?? approveConflict(step) ?? modeWithoutFile(step) ?? checkIdentity(step);
+		const error = unknownOptions(step) ?? onFailFault(step) ?? approveConflict(step) ?? modeWithoutFile(step) ?? checkIdentity(step);
 		return error === void 0 ? void 0 : {
 			kind: "failed",
 			message: error
@@ -23974,7 +24025,7 @@ const replay = async (raw) => {
 		expectNextOf(commit);
 		skipPins();
 		noteKept(step, commit);
-		return replyFor(step.request, commit.parsed.judge);
+		return replyFor(step.request, commit.parsed.judge, commit.parsed.shipped);
 	};
 	const expectNextOf = (commit) => {
 		const to = commit.parsed.parsed?.to;
@@ -24005,10 +24056,14 @@ const replay = async (raw) => {
 			hash: "",
 			tree: keeping ? position.tree : pending.tree
 		});
-		return replyFor(step.request, pending.verdicts ?? []);
+		return replyFor(step.request, pending.verdicts ?? [], pending.shipped);
 	};
 	const answer = (step) => {
-		while (cursor < commits.length && isAttemptAt(commits[cursor], step.name)) {
+		while (cursor < commits.length && isAttemptAt(commits[cursor], step)) {
+			if (!isEmptyDiff(diffTrees$1(position.tree, commits[cursor].tree))) advance({
+				hash: commits[cursor].hash,
+				tree: commits[cursor].tree
+			});
 			cursor++;
 			skipPins();
 		}
@@ -24021,12 +24076,22 @@ const replay = async (raw) => {
 			landed,
 			marks
 		});
+		if (restsOnFail(step) && input.pending.tree.read(".gtd/run-failed.txt") !== void 0) return finish({
+			kind: "rest",
+			rest: step,
+			trace,
+			landed,
+			marks
+		});
 		return landPending(step, input.pending);
 	};
+	const bodyFault = (request) => {
+		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)`;
+	};
 	const requestFault = (request) => {
 		if (scoped(request.name).startsWith("gtd:")) 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 void 0;
+		if (request.kind !== "agent") return bodyFault(request);
 		const name = scoped(request.name);
 		if (request.options.keep === true) {
 			if (request.options.allowEmpty === true) return `gtd: step "${name}": keep: true cannot be combined with allowEmpty — a turn that changes nothing has nothing to keep`;
@@ -24199,6 +24264,7 @@ const compileConfig = (value, origin) => {
 	return {
 		modes,
 		...config.ui !== void 0 ? { ui: config.ui } : {},
+		...config.historyRemote !== void 0 ? { historyRemote: config.historyRemote } : {},
 		skills: Object.assign(Object.create(null), config.skills),
 		access: Object.assign(Object.create(null), config.access),
 		diagnostics: []
@@ -24512,6 +24578,7 @@ const load = gen(function* () {
 			return entry === void 0 ? void 0 : resolve(name, entry);
 		},
 		...compiled.ui !== void 0 ? { ui: compiled.ui } : {},
+		...compiled.historyRemote !== void 0 ? { historyRemote: compiled.historyRemote } : {},
 		warnings: diagnostics.filter((d) => d.severity === "warning"),
 		fingerprint: pinned?.fingerprint ?? configFingerprint(nodeSyncIo, paths, loaded.file.dependencyFiles, host.root, module.read ?? readFromDisk),
 		drift: pinned === void 0 ? [] : changedConfigFiles(pinned.fingerprint, configFingerprint(nodeSyncIo, paths, Object.keys(pinned.fingerprint).map((file) => paths.resolve(host.root, file)), host.root, readFromDisk))
@@ -25212,8 +25279,9 @@ const shellQuote = (value) => `'${value.replace(/'/g, "'\\''")}'`;
 * output rather than the exit code, so a genuinely rejected commit (a lint
 * error, a commit-msg hook) still fails.
 */
-const commitAllowEmpty = (message, only) => {
-	const m = shellQuote(message);
+const commitAllowEmpty = (message, only) => commitWordAllowEmpty(shellQuote(message), only);
+/** `commitAllowEmpty` over a message that is already a shell word. */
+const commitWordAllowEmpty = (m, only) => {
 	const paths = only === void 0 ? "" : ` -- ${shellQuote(only)}`;
 	return [
 		`if ! out=$(git commit --allow-empty -m ${m}${paths} 2>&1); then`,
@@ -25229,6 +25297,28 @@ const CHANGED_SINCE_LAND = "gtd: the working tree changed since `gtd land` — r
 const commitAll = (message) => `git add -A || exit 1\n${commitAllowEmpty(message)}`;
 /** Commits `path` alone, as the worktree has it; every other pending change stays pending. */
 const commitPath = (path, message) => `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.
+*/
+const failRestScript = (body, path) => {
+	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. */
 const pinScript = (path) => {
 	const p = shellQuote(path);
@@ -25304,6 +25394,62 @@ const keepTurn = (refPrefix, message) => {
 		`git reset --hard HEAD`
 	].join("\n");
 };
+/** `git switch -C <branch> [<start>]`: create or reset the branch, carrying pending changes over. */
+const switchBranchTo = (branch, start) => `git switch -q -C ${shellQuote(branch)}${start === void 0 ? "" : ` ${shellQuote(start)}`}`;
+/** `git switch <branch>`: an existing branch, carrying pending changes over. */
+const switchTo = (branch) => `git switch -q ${shellQuote(branch)}`;
+/** `switchTo` that, when pending changes block it, stays put and says so: the landing already happened. */
+const switchBack = (branch) => [
+	`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");
+const deleteBranch = (branch) => `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.
+*/
+const pushRef = (remote, ref) => {
+	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.
+*/
+const shipCommit = (branch, parent, shipMessage, historyRef, message) => [
+	`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");
 const updateRef = (ref, hash) => `git update-ref ${shellQuote(ref)} ${shellQuote(hash)}`;
 /** `git update-ref -d <ref>` — idempotent: deleting a missing ref is already a no-op in real git. */
 const deleteRef = (ref) => `git update-ref -d ${shellQuote(ref)}`;
@@ -25332,15 +25478,18 @@ const renderOutcome = (outcome) => {
 		case "note": return printfLine$1("%s\n", [shellQuote(outcome.text)]);
 	}
 };
-const renderGitWrite = (write) => {
-	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);
-	}
+const GIT_WRITES = {
+	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) => GIT_WRITES[write.kind](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
@@ -25731,6 +25880,11 @@ const uncheckStep = (snapshot) => snapshot.stepDef.actor === "human" && snapshot
 	file: snapshot.file
 }] : [];
 const gitWriteOf = (landing, message) => {
+	if (landing.ship !== void 0) return {
+		kind: "ship",
+		message,
+		...landing.ship
+	};
 	if (landing.only !== void 0) return {
 		kind: "commitPath",
 		path: landing.only,
@@ -25750,6 +25904,10 @@ const gitWriteOf = (landing, message) => {
 		message
 	};
 };
+const writeIf = (value, write) => value === void 0 ? [] : [{
+	kind: "gitWrite",
+	write: write(value)
+}];
 const planStep = (snapshot, opts = {}) => {
 	const landing = snapshot.landing;
 	if (landing.kind === "refusal") return {
@@ -25797,6 +25955,7 @@ const planStep = (snapshot, opts = {}) => {
 		...opts.judge !== void 0 && opts.judge.length > 0 ? { judge: opts.judge } : {}
 	});
 	const subject = message.split("\n")[0];
+	const historyRef = landing.keepHistory ?? landing.ship?.historyRef;
 	const outcome = landing.to === snapshot.state ? {
 		kind: "outcome",
 		outcome: {
@@ -25817,20 +25976,37 @@ const planStep = (snapshot, opts = {}) => {
 		to: landing.to,
 		subject,
 		steps: [
+			...writeIf(landing.startBranch, (branch) => ({
+				kind: "switchBranch",
+				branch
+			})),
 			...uncheckStep(snapshot),
 			{
 				kind: "gitWrite",
 				write: gitWriteOf(landing, message)
 			},
-			...landing.keepHistory !== void 0 ? [{
-				kind: "gitWrite",
-				write: {
-					kind: "updateRef",
-					ref: landing.keepHistory,
-					target: "HEAD"
+			...writeIf(historyRef, (ref) => ({
+				kind: "updateRef",
+				ref,
+				target: "HEAD"
+			})),
+			...writeIf(landing.leaveBranch, (branch) => ({
+				kind: "switchTo",
+				branch
+			})),
+			outcome,
+			...landing.note !== void 0 ? [{
+				kind: "outcome",
+				outcome: {
+					kind: "note",
+					text: landing.note
 				}
 			}] : [],
-			outcome
+			...writeIf(historyRef !== void 0 ? landing.pushHistory : void 0, (remote) => ({
+				kind: "pushRef",
+				remote,
+				ref: historyRef
+			}))
 		]
 	};
 };
@@ -25850,6 +26026,42 @@ const accessRefusal = (changes, write) => {
 		`allowed: ${write.length === 0 ? "(nothing)" : write.join(", ")}`
 	].join("\n");
 };
+// src/step/startBranch.ts
+const GTD_BRANCH_PREFIX = "gtd/";
+/** `<b>` for a `gtd/<b>` branch name; `undefined` for any other. */
+const userBranchOf = (branch) => branch.startsWith("gtd/") ? branch.slice(4) : void 0;
+/**
+* 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).
+*/
+const startBranchFor = (commandLabel) => gen(function* () {
+	const git = yield* GitService;
+	const current = yield* git.currentBranch();
+	if (isNone(current) || current.value.startsWith("gtd/")) return { kind: "inPlace" };
+	if (!(yield* git.hasCommits())) return { kind: "inPlace" };
+	const branch = `${GTD_BRANCH_PREFIX}${current.value}`;
+	const existing = yield* git.readRefOption(`refs/heads/${branch}`);
+	if (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`
+		};
+	}
+	return {
+		kind: "switch",
+		branch
+	};
+});
 // src/step/planStart.ts
 const refusal = (message) => ({
 	kind: "refusal",
@@ -25890,29 +26102,42 @@ const planStart = (current, actor, start) => gen(function* () {
 	const base = template === void 0 ? void 0 : yield* resolveBase(commandLabel, template);
 	if (typeof base === "object") return base;
 	const subject = formatSubject(actor, firstStep);
+	const message = formatCommitMessage({
+		actor,
+		to: firstStep,
+		workflow: name,
+		...base !== void 0 ? { reviewBase: base } : {},
+		vars
+	});
+	const onBranch = yield* startBranchFor(commandLabel);
+	if (onBranch.kind === "refusal") return refusal(onBranch.message);
 	return {
 		kind: "start",
 		workflow: name,
 		subject,
-		steps: [{
-			kind: "gitWrite",
-			write: {
-				kind: "commitAll",
-				message: formatCommitMessage({
-					actor,
-					to: firstStep,
-					workflow: name,
-					...base !== void 0 ? { reviewBase: base } : {},
-					vars
-				})
-			}
-		}, {
-			kind: "outcome",
-			outcome: {
-				kind: "commit",
-				subject
+		steps: [
+			...onBranch.kind === "switch" ? [{
+				kind: "gitWrite",
+				write: {
+					kind: "switchBranch",
+					branch: onBranch.branch
+				}
+			}] : [],
+			{
+				kind: "gitWrite",
+				write: {
+					kind: "commitAll",
+					message
+				}
+			},
+			{
+				kind: "outcome",
+				outcome: {
+					kind: "commit",
+					subject
+				}
 			}
-		}]
+		]
 	};
 });
 /**
@@ -26156,14 +26381,32 @@ const runAtTip = (git, def, tip) => gen(function* () {
 	if (closing.length === 0) closing = yield* git.commitHistory(void 0, tip.hash);
 	return yield* runOf([...before, ...closing], { ...location }, tip.hash);
 });
-const runAtHead = (git, def) => gen(function* () {
-	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.
+*/
 const summaryRun = 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 === void 0 ? void 0 : yield* leftProcessTip(git, head);
+	return yield* runAtTip(git, def, left ?? head);
+});
+const leftProcessTip = (git, head) => gen(function* () {
+	if (parseCommitMessage(head.subject).parsed !== void 0) return void 0;
+	const current = yield* git.currentBranch();
+	if (isNone(current) || userBranchOf(current.value) !== void 0) return void 0;
+	const tip = yield* git.readRefOption(`refs/heads/${GTD_BRANCH_PREFIX}${current.value}`);
+	if (isNone(tip)) return void 0;
+	const message = yield* git.lastCommitMessage(tip.value);
+	if (parseCommitMessage(message).parsed?.to === void 0) return void 0;
+	const since = parseCommitMessage(yield* git.lastCommitMessage(head.hash)).tip ?? head.hash;
+	if (!(yield* git.isAncestor(since, tip.value))) return void 0;
+	return {
+		hash: tip.value,
+		subject: message.split("\n")[0]
+	};
 });
 const commitTree = (workspace, hash) => {
 	let entries;
@@ -26297,7 +26540,14 @@ const promptDef = (common, request, skills, access) => ({
 const scriptDef = (common, request) => ({
 	...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) => ({
+	...common,
+	kind: "script",
+	content: SHIP_CONTENT
 });
 const judgeDef = (common, request, step) => {
 	const message = request.options.message ?? DEFAULT_JUDGE_MESSAGE;
@@ -26321,6 +26571,7 @@ const stepDefOf = (step) => {
 	switch (request.kind) {
 		case "agent": 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": return messageDef(common, request, step);
 	}
@@ -26474,6 +26725,7 @@ const restAt = (ref, startOverrides = {}) => gen(function* () {
 		path: e.path
 	})) : [];
 	if (ref === void 0 && config.drift.length > 0) yield* (yield* Narrator).warn(`gtd: notice: the live config differs from the pinned one (${config.drift.join(", ")}); \`gtd repin\` to switch`);
+	const shipBlocked = ref === void 0 ? yield* shipBlockedAt(setup, pin, step, changes) : void 0;
 	return {
 		def,
 		workflowName: resolved.name,
@@ -26492,7 +26744,8 @@ const restAt = (ref, startOverrides = {}) => gen(function* () {
 		memoryResumed: memory.resumed,
 		hints: hintsOf(stepDef),
 		cost: costTotals(run.costEntries),
-		setup
+		setup,
+		...shipBlocked !== void 0 ? { shipBlocked } : {}
 	};
 });
 const currentRest = restAt(void 0);
@@ -26621,6 +26874,8 @@ const renderRest = (rest) => succeed$1({
 	kind: rest.stepDef.kind,
 	content: rest.stepDef.content,
 	...rest.hints,
+	...failedRunStalled(rest) ? { failure: rest.setup.workspace.readSync(".gtd/run-failed.txt") ?? "" } : {},
+	...rest.shipBlocked !== void 0 ? { blocked: rest.shipBlocked } : {},
 	...rest.memory !== void 0 ? { memory: rest.memory } : {},
 	memoryResumed: rest.memoryResumed,
 	...rest.pin !== void 0 ? { pin: rest.pin } : {}
@@ -26629,7 +26884,9 @@ const renderRest = (rest) => succeed$1({
 * Derived, restart-proof stall detection: the tree is clean, HEAD is an empty
 * attempt at this very agent rest, and another dispatch would repeat it.
 */
-const stalledAt = (rest) => 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;
+const stalledAt = (rest) => failedRunStalled(rest) || rest.shipBlocked !== void 0 || 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.changes.length === 0 && rest.stepDef.onFail === "rest" && rest.run.headTurn?.state === rest.state && !rest.run.headTurn.step && rest.setup.workspace.readSync(".gtd/run-failed.txt") !== void 0;
 /** 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. */
 const noProcessUnderway = (rest) => rest.pin === void 0 && !underwayAt(rest.run, rest.step, rest.def);
 /** `idle` means exactly one thing: no process underway, clean tree. */
@@ -26794,7 +27051,7 @@ const outcomeMarks = (outcome) => outcome.kind === "rest" || outcome.kind === "e
 * replay with the working tree as the pending turn. The target step is
 * computed by replaying, never matched.
 */
-const decideLanding = (rest, verdicts, branch, approver) => gen(function* () {
+const decideLanding = (rest, verdicts, branch, approver, shipped) => gen(function* () {
 	if (rest.pin !== void 0) return pinLanding(rest, rest.pin, branch);
 	const unapproved = approvalRefusal(rest, approver);
 	if (unapproved !== void 0) return unapproved;
@@ -26807,30 +27064,183 @@ const decideLanding = (rest, verdicts, branch, approver) => gen(function* () {
 			message
 		};
 	}
+	const landing = pendingTree(rest.setup.workspace, rest.setup.pendingWorktree(), reviewGateRewrite(rest.stepDef));
+	if (rest.stepDef.onFail === "rest" && landing.read(".gtd/run-failed.txt") !== void 0) return {
+		kind: "attempt",
+		subject: formatSubject(rest.actor, rest.state)
+	};
 	const outcome = yield* promise(() => replayFor(rest.setup, {
-		tree: pendingTree(rest.setup.workspace, rest.setup.pendingWorktree(), reviewGateRewrite(rest.stepDef)),
-		...verdicts !== void 0 ? { verdicts } : {}
+		tree: landing,
+		...verdicts !== void 0 ? { verdicts } : {},
+		...shipped !== void 0 ? { shipped } : {}
 	}));
 	const to = yield* landingTarget(outcome, rest);
 	if (typeof to !== "string") return to;
 	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) => gen(function* () {
+	const current = yield* git.currentBranch();
+	const name = isSome(current) ? userBranchOf(current.value) : void 0;
+	if (name === void 0) return current;
+	const there = yield* git.readRefOption(`refs/heads/${name}`);
+	return isSome(there) ? some(name) : current;
+});
+/** `<b>` for a process on `gtd/<b>` while `<b>` exists: where a finishing landing leaves HEAD. */
+const returnBranch = gen(function* () {
+	const git = yield* GitService;
+	const current = yield* git.currentBranch();
+	const name = isSome(current) ? userBranchOf(current.value) : void 0;
+	if (name === void 0) return void 0;
+	return isSome(yield* git.readRefOption(`refs/heads/${name}`)) ? name : void 0;
+});
+/** A starting landing moves onto `gtd/<b>` first. */
+const withBranchAndPush = (landing) => gen(function* () {
+	if (landing.kind !== "commit") return landing;
+	let out = landing;
+	if (landing.spec.vars !== void 0) {
+		const start = yield* startBranchFor("gtd land");
+		if (start.kind === "refusal") return {
+			kind: "refusal",
+			message: start.message
+		};
+		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) => gen(function* () {
+	let out = landing;
+	const back = landing.keepHistory === void 0 ? void 0 : yield* returnBranch;
+	if (back !== void 0) out = {
+		...out,
+		leaveBranch: back
+	};
+	if (landing.keepHistory === void 0 && landing.ship === void 0) return out;
+	const remote = (yield* (yield* ConfigService).load).historyRemote;
+	return remote === void 0 ? out : {
+		...out,
+		pushHistory: remote
+	};
+});
 /** Where landing the pending turn would leave the process, or `undefined` when it would land nothing. */
-const previewLanding = (rest) => decideLanding(rest, void 0, none(), none()).pipe(map((landing) => landing.kind === "commit" ? landing.to : void 0), catch_(() => succeed$1(void 0)));
+const previewLanding = (rest) => decideLanding(rest, void 0, none(), none(), rest.step.request.kind === "ship" ? SHIPPED_STAND_IN : void 0).pipe(map((landing) => landing.kind === "commit" ? landing.to : void 0), catch_(() => succeed$1(void 0)));
+const snapshotOf = (rest, landing) => ({
+	stepDef: rest.stepDef,
+	state: rest.state,
+	actor: rest.actor,
+	changes: rest.changes,
+	file: rest.hints.file,
+	landing
+});
+const refusedSnapshot = (rest, message) => snapshotOf(rest, {
+	kind: "refusal",
+	message
+});
+const SHIPPED_STAND_IN = "0".repeat(40);
+const SHIP_EXCLUDED = ".gtd/";
+const shippedPaths = (before, after) => {
+	const diff = diffTrees$1(before, after);
+	return [
+		...diff.added,
+		...diff.modified,
+		...diff.deleted
+	].filter((path) => !path.startsWith(SHIP_EXCLUDED));
+};
+const noTarget = (why) => ({
+	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) => gen(function* () {
+	const current = yield* git.currentBranch();
+	if (isNone(current)) return noTarget("HEAD is detached");
+	const branch = userBranchOf(current.value);
+	if (branch === void 0) return noTarget(`${current.value} is no gtd/ branch`);
+	if (userBranchOf(branch) !== void 0) return noTarget(`${current.value} records no user branch`);
+	const parent = yield* git.readRefOption(`refs/heads/${branch}`);
+	if (isNone(parent)) return noTarget(`${branch} does not exist`);
+	return {
+		kind: "ship",
+		branch,
+		parent: parent.value
+	};
+});
+/**
+* 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, workspace, parent, tree, changed) => gen(function* () {
+	const head = yield* git.resolveRef("HEAD");
+	const shipped = parseCommitMessage(yield* git.lastCommitMessage(parent)).tip;
+	if (shipped !== void 0 && (yield* git.isAncestor(shipped, head))) return [];
+	const fork = yield* git.mergeBase(parent, head);
+	const foreign = 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, tree) => 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, pin, step, changes) => gen(function* () {
+	if (pin !== void 0 || step.request.kind !== "ship" || changes.length > 0) return void 0;
+	const head = yield* (yield* GitService).resolveRef("HEAD");
+	const decision = yield* decideShip(setup.workspace, commitTree(setup.workspace, head));
+	return decision.kind === "blocked" ? decision.message : void 0;
+});
+const shipSnapshot = (rest, message, verdicts, branch, approver) => gen(function* () {
+	const tree = pendingTree(rest.setup.workspace, rest.setup.pendingWorktree(), void 0);
+	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 : void 0);
+	if (decided.kind !== "commit") return snapshotOf(rest, decided);
+	const 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. */
 const snapshotFromRest = (rest, verdicts) => 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() : 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 === void 0 && 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));
 });
 const humanCommitsOf = (trace, entryCommit) => trace.filter((entry) => entry.actor === "human" && entry.hash !== entryCommit).map((entry) => ({
 	hash: entry.hash,
@@ -27957,6 +28367,32 @@ const runStartListCommand = (json, out) => gen(function* () {
 	out.write([...workflows.map((name) => `workflow ${name}\n`), ...doors.map(([n, d]) => `door ${doorSynopsis(n, d)} → ${d.workflow}\n`)].join(""));
 });
 /**
+* Back on `<b>` when the process ran on `gtd/<b>` and `<b>` moved only by its
+* ships (whose `Gtd-Tip` the tip descends from): the rewind stops at the last
+* ship, so the uncommitted changes are what it left unshipped.
+*/
+const abandonTarget = (current, tip, startParent) => gen(function* () {
+	const git = yield* GitService;
+	const userBranch = isSome(current) ? userBranchOf(current.value) : void 0;
+	const userTip = userBranch === void 0 ? none() : yield* git.readRefOption(`refs/heads/${userBranch}`);
+	if (userBranch === void 0 || isNone(userTip)) return {
+		leaves: void 0,
+		rewindTo: startParent
+	};
+	if (userTip.value === startParent) return {
+		leaves: userBranch,
+		rewindTo: startParent
+	};
+	const shipped = parseCommitMessage(yield* git.lastCommitMessage(userTip.value)).tip;
+	return shipped !== void 0 && (yield* git.isAncestor(shipped, tip)) ? {
+		leaves: userBranch,
+		rewindTo: userTip.value
+	} : {
+		leaves: void 0,
+		rewindTo: startParent
+	};
+});
+/**
 * Ends the process underway without completing it. Nothing is discarded: a
 * `git reset --mixed` to the process's start commit leaves every turn
 * commit's content in the working tree.
@@ -27971,7 +28407,8 @@ const runStartListCommand = (json, out) => gen(function* () {
 */
 const runAbandonCommand = (json, out) => gen(function* () {
 	const git = yield* GitService;
-	const initial = (yield* (yield* ConfigService).load).workflow.initial;
+	const config = yield* (yield* ConfigService).load;
+	const initial = config.workflow.initial;
 	const run = yield* currentRun;
 	if (run.trace.length === 0) {
 		const required = emitScripts([{
@@ -27983,6 +28420,10 @@ const runAbandonCommand = (json, out) => gen(function* () {
 	const restState = run.trace[run.trace.length - 1].state;
 	if (run.startParentHash === EMPTY_TREE) return yield* fail$4(/* @__PURE__ */ new Error(`gtd abandon: the process underway (resting at "${restState}") starts at the repository's first commit — there is no earlier commit to rewind to`));
 	const tip = yield* git.resolveRef("HEAD");
+	const historyRef = processHistoryRef(run.startHash);
+	const current = yield* git.currentBranch();
+	const { leaves, rewindTo } = yield* abandonTarget(current, tip, run.startParentHash);
+	const remote = config.historyRemote;
 	const steps = [
 		{
 			kind: "gitWrite",
@@ -27990,21 +28431,60 @@ const runAbandonCommand = (json, out) => gen(function* () {
 		},
 		{
 			kind: "gitWrite",
-			command: mixedResetTo(run.startParentHash)
+			command: updateRef(historyRef, tip)
+		},
+		{
+			kind: "gitWrite",
+			command: mixedResetTo(rewindTo)
 		},
 		{
 			kind: "gitWrite",
 			command: unpinScript(PIN_PATH)
 		},
+		...leaves !== void 0 ? [
+			{
+				kind: "gitWrite",
+				command: switchTo(leaves)
+			},
+			{
+				kind: "gitWrite",
+				command: deleteBranch(getOrThrow$1(current))
+			},
+			{
+				kind: "gitWrite",
+				command: updateRef(RESUME_BRANCH_REF, tip)
+			}
+		] : [{
+			kind: "gitWrite",
+			command: deleteRef(RESUME_BRANCH_REF)
+		}],
 		{
 			kind: "outcome",
-			command: abandonedOutcome(restState, run.startParentHash, initial)
-		}
+			command: abandonedOutcome(restState, rewindTo, initial)
+		},
+		...remote !== void 0 ? [{
+			kind: "gitWrite",
+			command: pushRef(remote, historyRef)
+		}] : []
 	];
 	const required = emitScripts(steps).required;
 	yield* writeScript(json, out, combinedScript(required, ""));
 });
 /**
+* `gtd/<b>` when the abandon left it for `<b>` and HEAD is still on `<b>`. A
+* `gtd/<b>` made since is reset only when the retained tip contains it — the
+* `-C` switch would orphan anything else.
+*/
+const resumeBranch = (git, tip) => gen(function* () {
+	if (isNone(yield* git.readRefOption("refs/worktree/gtd/history-branch"))) return void 0;
+	const current = yield* git.currentBranch();
+	if (isNone(current) || current.value.startsWith("gtd/")) return void 0;
+	const branch = `${GTD_BRANCH_PREFIX}${current.value}`;
+	const existing = yield* git.readRefOption(`refs/heads/${branch}`);
+	if (isSome(existing) && !(yield* git.isAncestor(existing.value, tip))) return yield* fail$4(/* @__PURE__ */ new Error(`gtd restore: branch ${branch} holds commits the retained tip ${tip.slice(0, 7)} does not — merge or delete it first`));
+	return branch;
+});
+/**
 * `gtd restore`: hard-reset HEAD back to the tip `gtd abandon` retained.
 *
 * Guarded by `restorability` so it never discards work it didn't create:
@@ -28021,15 +28501,20 @@ const runRestoreCommand = (json, out) => gen(function* () {
 	const check = yield* restorability(git, headHash, tip);
 	if (!check.ok) return yield* fail$4(/* @__PURE__ */ new Error(`gtd restore: ${check.reason} — HEAD ${headHash.slice(0, 7)} is ahead of the retained tip ${tip.slice(0, 7)}.`));
 	const after = yield* restAt(tip);
+	const resumeOn = yield* resumeBranch(git, tip);
 	const steps = [
 		{
 			kind: "gitWrite",
-			command: hardResetTo(tip)
+			command: resumeOn === void 0 ? hardResetTo(tip) : switchBranchTo(resumeOn, tip)
 		},
 		{
 			kind: "gitWrite",
 			command: deleteRef(HISTORY_REF)
 		},
+		{
+			kind: "gitWrite",
+			command: deleteRef(RESUME_BRANCH_REF)
+		},
 		{
 			kind: "outcome",
 			command: restoredOutcome(tip, after.state)
@@ -28744,7 +29229,7 @@ gtd writes nothing itself. Plain output names the commit it would make; --json=s
 		},
 		group: "Start and stop",
 		summary: "Start a workflow or door; bare, list them",
-		details: `Start a new process: print the script that makes its first commit, which also commits whatever the working tree holds.
+		details: `Start a new process: print the script that makes its first commit, which also commits whatever the working tree holds. The process runs on the branch \`gtd/<b>\` (created, or reused when nothing on it would be lost), never on \`<b>\`; a branch already named \`gtd/…\` and a detached HEAD start in place.
 
 <name> is a door — a named shortcut whose positional args set the workflow's settings — or else a workflow the config exports, which takes no args. A door shadows a workflow of the same name. --var pins a setting either way.
 
@@ -28758,7 +29243,7 @@ With no <name>, list every workflow and door it can start. An unknown <name>, th
 		arity: "none",
 		group: "Start and stop",
 		summary: "Stop the process, keeping its changes",
-		details: `Stop the process underway without finishing it. The printed script moves HEAD back to the commit the process started from and keeps everything it produced as uncommitted changes; \`gtd restore\` undoes it. With no process underway the script does nothing.
+		details: `Stop the process underway without finishing it. The printed script moves HEAD back to the commit the process started from, or to its last ship, and keeps everything it produced as uncommitted changes, switches back to \`<b>\` and deletes \`gtd/<b>\`; it keeps the abandoned tip at \`refs/gtd/history/<entry>\` (pushed to \`historyRemote\` when set). \`gtd restore\` undoes it. With no process underway the script does nothing.
 
   s=$(gtd abandon --json=script) && sh -c "$s"`
 	},
@@ -28768,7 +29253,7 @@ With no <name>, list every workflow and door it can start. An unknown <name>, th
 		arity: "none",
 		group: "Start and stop",
 		summary: "Bring back the last abandoned process",
-		details: `Bring back the process the last \`gtd abandon\` stopped: the printed script resets HEAD to that process's last commit. Refuses on a dirty working tree, when nothing was abandoned, or when commits made since would be lost.`
+		details: `Bring back the process the last \`gtd abandon\` stopped: the printed script puts that process's last commit back, on a recreated \`gtd/<b>\` when the process ran on one. Refuses on a dirty working tree, when nothing was abandoned, or when commits made since would be lost.`
 	},
 	{
 		token: "repin",
@@ -28786,7 +29271,7 @@ With no <name>, list every workflow and door it can start. An unknown <name>, th
 		arity: "none",
 		group: "Inspect",
 		summary: "Print the prompt for the closing message",
-		details: `Print the prompt for an agent to write the closing message of the process HEAD closes or sits inside: its first commit, each commit a person made, the diff range to read, and its cost. Writes nothing — what to do with the answer (a squash message, a PR body) is the driver's call.
+		details: `Print the prompt for an agent to write the closing message of the process HEAD closes or sits inside (back on a user branch, the one its gtd/ branch closes): its first commit, each commit a person made, the diff range to read, and its cost. Writes nothing — what to do with the answer (a squash message, a PR body) is the driver's call.
 
 Refuses when the workflow declares no summary template, or when the process has no commits.`
 	},
@@ -28868,7 +29353,7 @@ Prints a sorted JSON array ([] when clean) and a summary on stderr; --verbose ad
 		arity: "none",
 		group: "Inspect",
 		summary: "Serve the web and phone client",
-		details: `Serve gtd's web and phone client for this worktree. By default it publishes through \`tailscale serve\`, reachable from anywhere on the tailnet, on the first of ports 8443, 10000 and 443 that works; when none does it serves HTTPS locally instead of refusing.`
+		details: `Serve gtd's web and phone client for this worktree. By default it publishes through \`tailscale serve\`, reachable from anywhere on the tailnet, on the first of ports 8443, 10000 and 443 that works; when none does it serves HTTPS locally instead of refusing. Done saves the steering file and keeps serving; the server exits when the worktree moves on to another step, or on a signal.`
 	},
 	{
 		token: "guide",
@@ -29589,6 +30074,71 @@ var InMemRepo = class InMemRepo {
 		this.worktree = new Map(tree);
 		this.index = new Map(tree);
 	}
+	/** `git switch -C <name> [<start>]`: pending changes ride along only when the tip's tree is unchanged. */
+	switchBranchTo(name, start) {
+		const hash = start === void 0 ? this.head : this.resolveRef(start);
+		if (hash === null) throw new Error(`invalid reference: ${start ?? "HEAD"}`);
+		this.moveToBranch(name, hash, true);
+	}
+	/** `git switch <name>`: a pending change rides along when its path is the same in both trees. */
+	switchTo(name) {
+		const hash = this.branches.get(name);
+		if (hash === void 0) throw new Error(`invalid reference: ${name}`);
+		if (hash === this.head) return this.moveToBranch(name, hash, false);
+		const from = this.headTree();
+		const to = this.getCommit(hash)?.files ?? /* @__PURE__ */ new Map();
+		const pending = [.../* @__PURE__ */ new Set([
+			...from.keys(),
+			...this.index.keys(),
+			...this.worktree.keys()
+		])].filter((path) => this.index.get(path) !== from.get(path) || this.worktree.get(path) !== from.get(path));
+		if (pending.some((path) => to.get(path) !== from.get(path))) throw new Error(`cannot switch to '${name}': local changes would be overwritten`);
+		const carry = (side) => {
+			const out = new Map(to);
+			for (const path of pending) {
+				const content = side.get(path);
+				if (content === void 0) out.delete(path);
+				else out.set(path, content);
+			}
+			return out;
+		};
+		this.worktree = carry(this.worktree);
+		this.index = carry(this.index);
+		this.head = hash;
+		this.currentBranch = name;
+	}
+	moveToBranch(name, hash, reset) {
+		if (hash !== this.head) {
+			if (this.statusPorcelain().trim() !== "") throw new Error(`cannot switch to '${name}': the working tree has uncommitted changes`);
+			const tree = this.getCommit(hash)?.files ?? /* @__PURE__ */ new Map();
+			this.head = hash;
+			this.worktree = new Map(tree);
+			this.index = new Map(tree);
+		}
+		if (reset || !this.branches.has(name)) this.branches.set(name, hash);
+		this.currentBranch = name;
+	}
+	deleteBranch(name) {
+		if (name === this.currentBranch) throw new Error(`cannot delete branch '${name}' checked out`);
+		if (!this.branches.delete(name)) throw new Error(`branch '${name}' not found`);
+	}
+	remotes = /* @__PURE__ */ new Map();
+	/** Test setup: a remote that accepts pushes. */
+	addRemote(name) {
+		this.remotes.set(name, /* @__PURE__ */ new Map());
+	}
+	/** What a remote holds after pushes: ref → hash. */
+	remoteRefs(name) {
+		return this.remotes.get(name) ?? /* @__PURE__ */ new Map();
+	}
+	/** `git push --force <remote> <ref>:<ref>`; returns git's complaint, or `undefined`. */
+	pushRef(remote, ref) {
+		const there = this.remotes.get(remote);
+		if (there === void 0) return `fatal: '${remote}' does not appear to be a git repository`;
+		const hash = this.resolveRef(ref);
+		if (hash === null) return `error: src refspec ${ref} does not match any`;
+		there.set(ref, hash);
+	}
 	/** Refs under `prefix`, newest tip first; the commit sequence number stands in for the committer date. */
 	listRefs(prefix) {
 		return [...this.refs.entries()].filter(([ref]) => ref.startsWith(prefix)).map(([ref, hash]) => ({
@@ -29821,6 +30371,27 @@ var InMemRepo = class InMemRepo {
 		this.index = new Map(tree);
 		this.resetHard();
 	}
+	/** Twin of `GitScript.shipCommit`: the staged tree, with `.gtd/` as `branch` has it, onto `branch`, then the landing commit naming it. */
+	shipCommit(branch, parent, shipMessage, historyRef, message) {
+		this.stageAll();
+		if (this.head === null) return "fatal: Needed a single revision";
+		if (this.signingFails) return "error: gpg failed to sign the data";
+		const kept = [...this.commits.get(parent)?.files ?? []];
+		const tree = new Map([...[...this.index].filter(([path]) => !path.startsWith(".gtd/")), ...kept.filter(([path]) => path.startsWith(".gtd/"))]);
+		const shipped = `${shipMessage}\n\nGtd-History: ${historyRef}\nGtd-Tip: ${this.head}\n`;
+		const hash = makeHash(shipped, parent, tree);
+		if (this.branches.get(branch) !== parent) return `fatal: update_ref failed for ref 'refs/heads/${branch}': cannot lock ref 'refs/heads/${branch}': is at ${this.branches.get(branch) ?? "nothing"} but expected ${parent}`;
+		this.commits.set(hash, {
+			hash,
+			message: shipped,
+			files: tree,
+			parent,
+			seq: this.nextSeq++,
+			signed: this.signingEnabled
+		});
+		this.branches.set(branch, hash);
+		return this.commitAsIs(`${message}\nGtd-Shipped: ${hash}`);
+	}
 	/** Discard every pending change, tracked or untracked: stage everything, then hard-reset (which drops the freshly-staged untracked paths too). */
 	discardPending() {
 		this.index = new Map(this.worktree);
@@ -30610,6 +31181,18 @@ const recognizeKeepTurn = (repo, block) => {
 		status: 1
 	};
 };
+const attempt = (apply) => {
+	try {
+		apply();
+		return { kind: "applied" };
+	} catch (e) {
+		return {
+			kind: "failed",
+			error: `fatal: ${e instanceof Error ? e.message : String(e)}`,
+			status: 128
+		};
+	}
+};
 const recognizeGitBuilders = (repo, block) => {
 	if (block === discardPending()) {
 		repo.discardPending();
@@ -30687,6 +31270,58 @@ const recognizeGitBuilders = (repo, block) => {
 		}
 		return;
 	}
+	if (block.startsWith("git switch -q -C ")) {
+		const [branch, start] = extractQuotedTokens(block);
+		if (branch !== void 0 && switchBranchTo(branch, start) === block) return attempt(() => repo.switchBranchTo(branch, start));
+		return;
+	}
+	if (block.startsWith("if ! git switch -q ")) {
+		const [branch, , note] = extractQuotedTokens(block);
+		if (branch !== void 0 && switchBack(branch) === block) try {
+			repo.switchTo(branch);
+			return { kind: "applied" };
+		} catch {
+			return {
+				kind: "noop",
+				output: `${note}\n`
+			};
+		}
+		return;
+	}
+	if (block.startsWith("git switch -q ")) {
+		const [branch] = extractQuotedTokens(block);
+		if (branch !== void 0 && switchTo(branch) === block) return attempt(() => repo.switchTo(branch));
+		return;
+	}
+	if (block.startsWith("git branch -q -D ")) {
+		const [branch] = extractQuotedTokens(block);
+		if (branch !== void 0 && deleteBranch(branch) === block) return attempt(() => repo.deleteBranch(branch));
+		return;
+	}
+	if (block.startsWith("if ! git push --force ")) {
+		const [remote, refspec] = extractQuotedTokens(block);
+		const ref = refspec?.split(":")[0];
+		if (remote !== void 0 && ref !== void 0 && pushRef(remote, ref) === block) {
+			const failure = repo.pushRef(remote, ref);
+			if (failure === void 0) return { kind: "applied" };
+			return {
+				kind: "failed",
+				error: `${failure}\n${extractQuotedTokens(block)[3]}`,
+				status: 1
+			};
+		}
+		return;
+	}
+	if (block.startsWith("gtd_ship_parent=")) {
+		const [parent, branch, history, shipMessage, message] = extractQuotedTokens(block);
+		if (parent === void 0 || branch === void 0 || history === void 0 || shipMessage === void 0 || message === void 0 || shipCommit(branch, parent, shipMessage, history, message) !== block) return;
+		const failure = repo.shipCommit(branch, parent, shipMessage, history, message);
+		return failure === void 0 ? { kind: "applied" } : {
+			kind: "failed",
+			error: failure,
+			status: 1
+		};
+	}
 	if (block.startsWith("git update-ref -d ")) {
 		const [ref] = extractQuotedTokens(block);
 		if (ref !== void 0 && deleteRef(ref) === block) {
@@ -30793,6 +31428,31 @@ const recognizeModeCommand = (repo, commands, block) => {
 	} : scripted;
 	return recognizeScriptedCommand(repo, /* @__PURE__ */ new Map([[command, bound]]), command);
 };
+const FAIL_REST_MIDDLE = "\n} 2>&1 )\" || gtd_run_status=$?\n";
+/** A `run(…, { onFail: "rest" })` body: the inner script's failure is recorded in the tree and the block itself succeeds. */
+const recognizeFailRest = (repo, commands, block) => {
+	if (!block.startsWith("rm -f -- '") || !block.includes("gtd_run_out=")) return void 0;
+	const [path] = extractQuotedTokens(block);
+	const headerEnd = block.indexOf("gtd_run_out=\"$( {\n");
+	const bodyEnd = block.indexOf(FAIL_REST_MIDDLE);
+	if (path === void 0 || headerEnd === -1 || bodyEnd === -1) return void 0;
+	const body = block.slice(headerEnd + 18, bodyEnd);
+	if (failRestScript(body, path) !== block) return void 0;
+	if (repo.readFile(path) !== void 0) repo.deleteFile(path);
+	const result = applyEmittedScript(repo, commands, body);
+	if (!result.ok && result.error?.startsWith(UNRECOGNIZED_PREFIX)) return {
+		kind: "failed",
+		error: `${result.output}${result.error}`
+	};
+	if (!result.ok) {
+		const lines = result.output.replace(/\n+$/, "").split("\n");
+		repo.writeFile(path, `exit ${result.status}\n${lines.slice(-50).join("\n")}\n`);
+	}
+	return {
+		kind: "noop",
+		output: result.output
+	};
+};
 const FAILURE_PROMPT_HEADER = "gtd_validate_status=0\ngtd_validate_out=\"$( {\n";
 const FAILURE_PROMPT_MIDDLE = "\n} 2>&1 )\" || gtd_validate_status=$?\nif [ \"$gtd_validate_status\" -ne 0 ]; then\n  printf '%s\\n\\n%s\\n' ";
 const FAILURE_PROMPT_FOOTER = " \"$gtd_validate_out\"\n  exit \"$gtd_validate_status\"\nfi";
@@ -31083,6 +31743,7 @@ const recognizersFor = (repo, commands, git) => [
 	(block) => git ? recognizeGitBuilders(repo, block) : void 0,
 	(block) => recognizeWriteLines(repo, block),
 	(block) => recognizePinScripts(repo, block),
+	(block) => recognizeFailRest(repo, commands, block),
 	(block) => recognizeFailurePromptWrapper(repo, commands, block),
 	(block) => recognizePresentationSubshell(repo, commands, block, git),
 	(block) => recognizeModeContradictionSkipNotice(block),