@pmelab/gtd 64.3.0 → 65.0.0

package/dist/gtd.bundle.mjs

@@ -1981,7 +1981,7 @@ var init_Order = __esmMin((() => {
 	isGreaterThan$1 = (O) => dual(2, (self, that) => O(self, that) === 1);
 	isLessThanOrEqualTo$1 = (O) => dual(2, (self, that) => O(self, that) !== 1);
 	isGreaterThanOrEqualTo$1 = (O) => dual(2, (self, that) => O(self, that) !== -1);
-})), none, some, isNone, isSome, match$3, getOrElse, orElse, fromNullishOr, getOrUndefined$1, map$6, flatMap$4;
+})), none, some, isNone, isSome, match$3, getOrElse, orElse, fromNullishOr, getOrUndefined$1, getOrThrowWith$1, getOrThrow$1, map$6, flatMap$4;
 var init_Option = __esmMin((() => {
 	init_Function();
 	init_option();
@@ -1994,6 +1994,11 @@ var init_Option = __esmMin((() => {
 	orElse = /*#__PURE__*/ dual(2, (self, that) => isNone(self) ? that() : self);
 	fromNullishOr = (a) => a == null ? none() : some(a);
 	getOrUndefined$1 = /*#__PURE__*/ getOrElse(constUndefined);
+	getOrThrowWith$1 = /*#__PURE__*/ dual(2, (self, onNone) => {
+		if (isSome(self)) return self.value;
+		throw onNone();
+	});
+	getOrThrow$1 = /*#__PURE__*/ getOrThrowWith$1(() => /* @__PURE__ */ new Error("getOrThrow called on a None"));
 	map$6 = /*#__PURE__*/ dual(2, (self, f) => isNone(self) ? none() : some(f(self.value)));
 	flatMap$4 = /*#__PURE__*/ dual(2, (self, f) => isNone(self) ? none() : f(self.value));
 }));
@@ -13724,6 +13729,8 @@ const loopLogPath = gen(function* () {
 init_dist$1();
 /** 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}`;
@@ -14632,6 +14639,17 @@ const run$3 = (name, body, options = {}) => ctx().step({
 	body,
 	options
 });
+/**
+* Squashes HEAD's tree, with `.gtd/` as the user's branch has it, into one commit on the user's branch
+* with `message`, and moves that branch there; HEAD stays on `gtd/<b>`.
+* Resolves to the new commit's hash, or `undefined` when nothing shipped.
+*/
+const ship = (name, message, options = {}) => ctx().step({
+	kind: "ship",
+	name,
+	message,
+	options
+});
 /** A judge gate: resolves to what the judge answered, for the flow to decide on. */
 const judge = (name, spec) => {
 	const { questions, evidence, ...options } = spec;
@@ -15123,7 +15141,8 @@ const CONFIG_KEYS = [
 	"modes",
 	"ui",
 	"skills",
-	"access"
+	"access",
+	"historyRemote"
 ];
 const MODE_KEYS = ["format", "validate"];
 const UI_KEYS = [
@@ -15194,6 +15213,10 @@ const configProblems = (value) => {
 		...unknownKeys(value, CONFIG_KEYS, []),
 		...value.modes === void 0 ? [] : recordOf(value.modes, ["modes"], "modes", modeProblems),
 		...value.ui === void 0 ? [] : uiProblems(value.ui, ["ui"]),
+		...value.historyRemote === void 0 || typeof value.historyRemote === "string" && value.historyRemote.trim() !== "" ? [] : [{
+			path: ["historyRemote"],
+			message: "must be a non-empty remote name"
+		}],
 		...value.skills === void 0 ? [] : recordOf(value.skills, ["skills"], "skill-name arrays", (v, path) => isStringArray$1(v) ? [] : [{
 			path,
 			message: "must be an array of skill names"
@@ -15262,6 +15285,7 @@ var flows_exports = /* @__PURE__ */ __exportAll({
 	sections: () => sections$1,
 	settings: () => settings,
 	settingsOf: () => settingsOf,
+	ship: () => ship,
 	showScript: () => showScript,
 	skillsFor: () => skillsFor,
 	start: () => start,
@@ -31138,6 +31162,8 @@ const renderFormat = (fmt, ...args) => {
 const ACCESS_REFUSAL = "gtd land: this turn wrote outside its write access — revert these paths, then run `gtd land` again:";
 /** Where a process keeps its pin: the engine and workflow it runs on, as `gtd bundle` prints them. */
 const PIN_PATH = ".gtd/process.gtdpin";
+/** Where a `run(…, { onFail: "rest" })` body's failure is recorded in the tree: the exit status and the output. */
+const RUN_FAILED_PATH = ".gtd/run-failed.txt";
 // src/wire/Demand.ts
 /**
 * The beat kind for a rest, in precedence order:
@@ -31161,7 +31187,7 @@ const beatKindOf = (input) => {
 * `stalled at "<state>"` stays a stable substring (see
 * `tests/integration/features/driver-doc.feature`).
 */
-const stallDiagnosis = (state, actor) => `stalled at "${state}": the last gtd(${actor}): ${state} turn landed an empty attempt, the tree is clean, and another dispatch would repeat it.\n\nTwo ways out:\n  - sharpen the step's prompt so the turn has something concrete to author\n  - pass allowEmpty: true to the step, so an empty turn completes it and the\n    flow decides what follows — finishing, or an escalation step after N\n    empty turns\n`;
+const stallDiagnosis = (state, actor, failure, blocked) => blocked !== void 0 ? `stalled at "${state}": landing this ship step is refused.\n\n${blocked}\n` : failure !== void 0 ? `stalled at "${state}": the script exited non-zero and its failure is recorded in the tree. Change the tree to run the script again; the step advances only on a zero exit.\n\n${failure}` : `stalled at "${state}": the last gtd(${actor}): ${state} turn landed an empty attempt, the tree is clean, and another dispatch would repeat it.\n\nTwo ways out:\n  - sharpen the step's prompt so the turn has something concrete to author\n  - pass allowEmpty: true to the step, so an empty turn completes it and the\n    flow decides what follows — finishing, or an escalation step after N\n    empty turns\n`;
 /**
 * Assemble one `Demand` — the ONLY place a rest's resolved content becomes
 * `Demand.content` (`stallDiagnosis` at `kind === "stalled"`, the rendered
@@ -31171,7 +31197,7 @@ const stallDiagnosis = (state, actor) => `stalled at "${state}": the last gtd(${
 */
 const demandOf = (input) => {
 	const { rendered, kind, session, validate } = input;
-	const content = kind === "stalled" ? stallDiagnosis(rendered.state, rendered.actor) : rendered.content;
+	const content = kind === "stalled" ? stallDiagnosis(rendered.state, rendered.actor, rendered.failure, rendered.blocked) : rendered.content;
 	const skills = rendered.skills !== void 0 && rendered.skills.length > 0 ? rendered.skills : void 0;
 	const access = rendered.access ?? {
 		read: null,
@@ -31770,6 +31796,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);
 	},
@@ -31794,6 +31826,8 @@ const parseCommitMessage = (message) => {
 		approved: void 0,
 		pin: void 0,
 		anchor: void 0,
+		shipped: void 0,
+		tip: void 0,
 		judge: [],
 		marks: [],
 		vars: {},
@@ -31835,7 +31869,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);
@@ -31969,9 +32003,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;
@@ -32082,15 +32119,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(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(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();
@@ -32204,7 +32241,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
@@ -32230,7 +32267,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;
@@ -32261,10 +32298,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(position.tree, commits[cursor].tree))) advance({
+				hash: commits[cursor].hash,
+				tree: commits[cursor].tree
+			});
 			cursor++;
 			skipPins();
 		}
@@ -32277,12 +32318,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`;
@@ -32464,6 +32515,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: []
@@ -32780,6 +32832,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))
@@ -33501,8 +33554,9 @@ const shellQuote$1 = (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$1(message);
+const commitAllowEmpty = (message, only) => commitWordAllowEmpty(shellQuote$1(message), only);
+/** `commitAllowEmpty` over a message that is already a shell word. */
+const commitWordAllowEmpty = (m, only) => {
 	const paths = only === void 0 ? "" : ` -- ${shellQuote$1(only)}`;
 	return [
 		`if ! out=$(git commit --allow-empty -m ${m}${paths} 2>&1); then`,
@@ -33518,6 +33572,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$1(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$1(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$1(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$1(path);
@@ -33581,6 +33657,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$1(branch)}${start === void 0 ? "" : ` ${shellQuote$1(start)}`}`;
+/** `git switch <branch>`: an existing branch, carrying pending changes over. */
+const switchTo = (branch) => `git switch -q ${shellQuote$1(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$1(branch)} 2>/dev/null; then`,
+	`  printf '%s\\n' ${shellQuote$1(`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$1(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$1(remote)} ${shellQuote$1(`${ref}:${ref}`)}`;
+	return [
+		`if ! ${retry}; then`,
+		`  printf '%s\\n' ${shellQuote$1(`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$1(parent)}`,
+	`gtd_ship_branch=${shellQuote$1(branch)}`,
+	`gtd_ship_history=${shellQuote$1(historyRef)}`,
+	`gtd_ship_message=${shellQuote$1(shipMessage)}`,
+	`gtd_land_message=${shellQuote$1(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$1(ref)} ${shellQuote$1(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$1(ref)}`;
@@ -33609,15 +33741,18 @@ const renderOutcome = (outcome) => {
 		case "note": return printfLine$1("%s\n", [shellQuote$1(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
@@ -34010,6 +34145,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,
@@ -34029,6 +34169,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 {
@@ -34076,6 +34220,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: {
@@ -34096,20 +34241,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
+			}))
 		]
 	};
 };
@@ -34129,6 +34291,43 @@ const accessRefusal = (changes, write) => {
 		`allowed: ${write.length === 0 ? "(nothing)" : write.join(", ")}`
 	].join("\n");
 };
+// src/step/startBranch.ts
+init_dist$1();
+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
 init_dist$1();
 const refusal = (message) => ({
@@ -34170,29 +34369,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
+				}
 			}
-		}]
+		]
 	};
 });
 /**
@@ -34438,14 +34650,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;
@@ -34579,7 +34809,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;
@@ -34603,6 +34840,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);
 	}
@@ -34756,6 +34994,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,
@@ -34774,7 +35013,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);
@@ -34903,6 +35143,8 @@ const renderRest = (rest) => succeed$2({
 	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 } : {}
@@ -34911,7 +35153,9 @@ const renderRest = (rest) => succeed$2({
 * 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. */
@@ -35076,7 +35320,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;
@@ -35089,30 +35333,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$2(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$2(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(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,
@@ -36248,6 +36645,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.
@@ -36262,7 +36685,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([{
@@ -36274,6 +36698,10 @@ const runAbandonCommand = (json, out) => gen(function* () {
 	const restState = run.trace[run.trace.length - 1].state;
 	if (run.startParentHash === EMPTY_TREE) return yield* fail$8(/* @__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",
@@ -36281,21 +36709,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$8(/* @__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:
@@ -36312,15 +36779,20 @@ const runRestoreCommand = (json, out) => gen(function* () {
 	const check = yield* restorability(git, headHash, tip);
 	if (!check.ok) return yield* fail$8(/* @__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)
@@ -37036,7 +37508,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.
 
@@ -37050,7 +37522,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"`
 	},
@@ -37060,7 +37532,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",
@@ -37078,7 +37550,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.`
 	},