get-tbd 0.2.0 → 0.2.2

package/dist/tbd

@@ -11,7 +11,7 @@ import tty from "node:tty";
 import { access, chmod, cp, mkdir, readFile, readdir, realpath, rename, rm, rmdir, stat, unlink } from "node:fs/promises";
 import { Readable } from "node:stream";
 import { promisify } from "node:util";
-import crypto, { randomBytes } from "node:crypto";
+import crypto, { randomBytes, randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import prettyBytes from "pretty-bytes";
 import prettyMs from "pretty-ms";
@@ -14104,7 +14104,7 @@ function serializeIssue(issue) {
 * Package version, derived from git at build time.
 * Format: X.Y.Z for releases, X.Y.Z-dev.N.hash for dev builds.
 */
-const VERSION$1 = "0.2.0";
+const VERSION$1 = "0.2.2";
 
 //#endregion
 //#region src/cli/lib/version.ts
@@ -98354,6 +98354,18 @@ var SyncError = class extends CLIError {
 	}
 };
 /**
+* Unrelated-history error - the local and remote tbd-sync share no common
+* ancestor, so a push can never fast-forward and a plain git merge refuses.
+* `tbd sync` cannot resolve this; the rescue lives in `tbd doctor --fix`.
+* See: plan-2026-05-29-tbd-sync-unrelated-history-hardening.md
+*/
+var UnrelatedHistoriesError = class extends SyncError {
+	constructor(remote = "origin", syncBranch = "tbd-sync") {
+		super(`${remote}/${syncBranch} has an unrelated history (no common ancestor) — push cannot fast-forward and a merge would refuse.\nRun \`tbd doctor --fix\` to reconcile the unrelated histories (non-destructive; a backup branch is created first).`);
+		this.name = "UnrelatedHistoriesError";
+	}
+};
+/**
 * Classify a sync error to determine appropriate recovery action.
 *
 * Used by `tbd sync` to decide whether to:
@@ -98651,6 +98663,124 @@ function nowFilenameTimestamp() {
 	return (/* @__PURE__ */ new Date()).toISOString().replace(/:/g, "-").replace(/\.\d+Z$/, "Z");
 }
 
+//#endregion
+//#region src/utils/zod-error-utils.ts
+/**
+* Helpers for rendering Zod errors without relying on object inspection.
+*/
+/**
+* Format a ZodError as concise path-qualified messages for CLI output.
+*/
+function formatZodError(error) {
+	const messages = error.issues.map((issue) => {
+		return `${issue.path.length > 0 ? issue.path.join(".") : "<root>"}: ${issue.message}`;
+	});
+	return messages.length > 0 ? messages.join("; ") : error.message;
+}
+/**
+* Format unknown thrown values as safe strings for warnings and diagnostics.
+*/
+function formatUnknownError(error) {
+	if (error instanceof ZodError) return formatZodError(error);
+	if (error instanceof Error) return error.message;
+	return String(error);
+}
+
+//#endregion
+//#region src/file/storage.ts
+/**
+* Storage layer for issue files.
+*
+* Provides atomic file operations and issue CRUD operations.
+* All operations work on the data-sync directory selected by the caller. In production
+* that is the shared hidden worktree under $GIT_COMMON_DIR/tbd/data-sync-worktree/.
+*
+* See: tbd-design.md §3.2 Storage Layer
+*/
+/**
+* Maximum issue files read concurrently to avoid exhausting file descriptors in large repos.
+*/
+const ISSUE_READ_BATCH_SIZE = 200;
+/**
+* Get the path to an issue file.
+*/
+function getIssuePath(baseDir, id) {
+	return join(baseDir, "issues", `${id}.md`);
+}
+/**
+* Read an issue from the worktree.
+* @throws If the issue file doesn't exist or is invalid.
+*/
+async function readIssue(baseDir, id) {
+	return parseIssue(await readFile(getIssuePath(baseDir, id), "utf-8"));
+}
+/**
+* Write an issue to the worktree.
+* Uses atomic write to prevent corruption.
+*/
+async function writeIssue(baseDir, issue) {
+	const validIssue = IssueSchema.parse(issue);
+	await writeFile(getIssuePath(baseDir, validIssue.id), serializeIssue(validIssue));
+}
+/**
+* List all issues in the worktree.
+* Returns empty array if issues directory doesn't exist.
+*
+* Uses parallel file reading for better performance with many issues.
+*/
+async function listIssues(baseDir, options = {}) {
+	const warnOnInvalid = options.warnOnInvalid ?? true;
+	const issuesDir = join(baseDir, "issues");
+	let files;
+	try {
+		files = await readdir(issuesDir);
+	} catch {
+		return [];
+	}
+	const mdFiles = files.filter((f) => f.endsWith(".md"));
+	const issues = [];
+	for (let i = 0; i < mdFiles.length; i += ISSUE_READ_BATCH_SIZE) {
+		const batch = mdFiles.slice(i, i + ISSUE_READ_BATCH_SIZE);
+		const fileContents = await Promise.all(batch.map(async (file) => {
+			const filePath = join(issuesDir, file);
+			try {
+				return {
+					file,
+					content: await readFile(filePath, "utf-8")
+				};
+			} catch (error) {
+				return {
+					file,
+					error: formatUnknownError(error)
+				};
+			}
+		}));
+		for (const result of fileContents) {
+			if ("error" in result) {
+				reportInvalidIssueFile({
+					file: result.file,
+					reason: `failed to read file: ${result.error}`
+				}, warnOnInvalid, options.onInvalidIssue);
+				continue;
+			}
+			try {
+				const issue = parseIssue(result.content);
+				issues.push(issue);
+			} catch (error) {
+				reportInvalidIssueFile({
+					file: result.file,
+					reason: formatUnknownError(error)
+				}, warnOnInvalid, options.onInvalidIssue);
+			}
+		}
+	}
+	return issues;
+}
+function reportInvalidIssueFile(invalidIssue, warnOnInvalid, onInvalidIssue) {
+	onInvalidIssue?.(invalidIssue);
+	if (warnOnInvalid) console.warn(`Skipping invalid issue file: ${invalidIssue.file}: ${invalidIssue.reason}`);
+}
+
 //#endregion
 //#region src/utils/lockfile.ts
 /**
@@ -98682,10 +98812,15 @@ function nowFilenameTimestamp() {
 *
 * 1. **Acquire**: `mkdir(lockDir)` — fails with EEXIST if held by another process
 * 2. **Hold**: Execute the critical section
-* 3. **Release**: `rmdir(lockDir)` — in a finally block
+* 3. **Release**: `rmdir(lockDir)` — in a finally block, with a bounded retry to
+*    absorb transient Windows failures (EBUSY/EPERM from AV scanners or lingering
+*    handles) that would otherwise orphan the lock directory.
 * 4. **Stale detection**: If lock mtime exceeds a threshold, assume the holder
-*    crashed and break the lock. This is a heuristic — safe when the critical
-*    section is short-lived (sub-second for file I/O).
+*    crashed and break the lock. Breaking is done **atomically** by renaming the
+*    stale directory aside (only one waiter can win the rename), so two waiters can
+*    never both break the same lock and end up running concurrently. This is a
+*    heuristic — safe when the critical section is short-lived (sub-second for
+*    file I/O).
 *
 * ## Failure on timeout
 *
@@ -98733,6 +98868,53 @@ var LockAcquisitionError = class extends Error {
 		this.name = "LockAcquisitionError";
 	}
 };
+/** Filesystem error codes that are transient on Windows and worth retrying. */
+const TRANSIENT_RMDIR_CODES = new Set([
+	"EBUSY",
+	"EPERM",
+	"EACCES",
+	"ENOTEMPTY"
+]);
+/**
+* Remove a lock directory, tolerating transient Windows failures.
+*
+* `rmdir` can intermittently fail with EBUSY/EPERM on Windows (antivirus scanners
+* or lingering directory handles). A few short retries make release reliable; if it
+* still fails, we give up and let stale detection reclaim the directory rather than
+* throwing from a best-effort cleanup path.
+*/
+async function removeLockDir(lockPath, attempts = 5) {
+	for (let attempt = 0; attempt < attempts; attempt++) try {
+		await rmdir(lockPath);
+		return;
+	} catch (error) {
+		const code = error.code;
+		if (code === "ENOENT") return;
+		if (attempt < attempts - 1 && code && TRANSIENT_RMDIR_CODES.has(code)) {
+			await new Promise((resolve) => setTimeout(resolve, 20 * (attempt + 1)));
+			continue;
+		}
+		return;
+	}
+}
+/**
+* Atomically break a stale lock.
+*
+* Renames the stale directory to a unique sidecar path and removes it. `rename` is
+* atomic, so when several waiters race to break the same stale lock only one wins the
+* rename; the losers see ENOENT and simply retry. This prevents the classic
+* non-atomic break race (rmdir + mkdir) where two waiters both break the lock and both
+* acquire it, defeating mutual exclusion.
+*/
+async function breakStaleLock(lockPath) {
+	const sidecar = `${lockPath}.stale-${randomUUID()}`;
+	try {
+		await rename(lockPath, sidecar);
+	} catch {
+		return;
+	}
+	await removeLockDir(sidecar);
+}
 /**
 * Execute `fn` while holding a lockfile.
 *
@@ -98771,26 +98953,24 @@ async function withLockfile(lockPath, fn, options) {
 		break;
 	} catch (error) {
 		if (error.code !== "EEXIST") throw error;
+		let lockStat;
 		try {
-			const lockStat = await stat(lockPath);
-			if (Date.now() - lockStat.mtimeMs > staleMs) {
-				try {
-					await rmdir(lockPath);
-				} catch {}
-				continue;
-			}
+			lockStat = await stat(lockPath);
 		} catch {
 			continue;
 		}
+		if (!lockStat.isDirectory()) throw new Error(`Lock path exists but is not a directory: ${lockPath}. Refusing to break it; remove the conflicting file and retry.`);
+		if (Date.now() - lockStat.mtimeMs > staleMs) {
+			await breakStaleLock(lockPath);
+			continue;
+		}
 		await new Promise((resolve) => setTimeout(resolve, pollMs));
 	}
 	if (!acquired) throw new LockAcquisitionError(lockPath, timeoutMs);
 	try {
 		return await fn();
 	} finally {
-		try {
-			await rmdir(lockPath);
-		} catch {}
+		await removeLockDir(lockPath);
 	}
 }
 
@@ -99521,6 +99701,55 @@ function resolveIdMappingConflicts(content) {
 */
 const execFileAsync$1 = promisify(execFile);
 /**
+* Error thrown by {@link git} when a git command exits non-zero.
+*
+* Carries the process `exitCode` so callers can branch on git's exit status
+* (e.g. `ls-remote --exit-code` => 2 means "ref absent", `merge-base` => 1
+* means "no common ancestor") instead of string-matching stderr. The original
+* message/stderr is preserved so existing message-based classifiers
+* (classifySyncError) keep working.
+*/
+var GitError = class GitError extends Error {
+	/** Process exit code, or null for a spawn failure (e.g. git not found). */
+	exitCode;
+	stderr;
+	stdout;
+	args;
+	constructor(message, opts) {
+		super(message);
+		this.name = "GitError";
+		this.exitCode = opts.exitCode;
+		this.stderr = opts.stderr;
+		this.stdout = opts.stdout;
+		this.args = opts.args;
+	}
+	/**
+	* Wrap a raw execFile rejection into a GitError.
+	*
+	* Node's execFile rejection carries `code` (numeric exit code for a normal
+	* exit, or a string like 'ENOENT' for a spawn failure), plus `stderr`/`stdout`.
+	*/
+	static from(err, args) {
+		const raw = err;
+		const exitCode = typeof raw.code === "number" ? raw.code : null;
+		const stderr = typeof raw.stderr === "string" ? raw.stderr : "";
+		const stdout = typeof raw.stdout === "string" ? raw.stdout : "";
+		return new GitError(raw.message ?? `git ${args.join(" ")} failed`, {
+			exitCode,
+			stderr,
+			stdout,
+			args
+		});
+	}
+};
+/**
+* Read the git exit code from a thrown value, or null if it is not a GitError
+* (or carries no numeric code, e.g. a spawn failure).
+*/
+function exitCodeOf(err) {
+	return err instanceof GitError ? err.exitCode : null;
+}
+/**
 * Maximum buffer size for git command output.
 *
 * Node.js child_process.execFile() defaults to 1MB (1024 * 1024 bytes).
@@ -99535,8 +99764,31 @@ const GIT_MAX_BUFFER = 50 * 1024 * 1024;
 * Uses execFile for security - prevents shell injection attacks.
 */
 async function git(...args) {
-	const { stdout } = await execFileAsync$1("git", args, { maxBuffer: GIT_MAX_BUFFER });
-	return stdout.trim();
+	try {
+		const { stdout } = await execFileAsync$1("git", args, { maxBuffer: GIT_MAX_BUFFER });
+		return stdout.trim();
+	} catch (err) {
+		throw GitError.from(err, args);
+	}
+}
+/**
+* Like {@link git} but with `GIT_TERMINAL_PROMPT=0` so a network operation
+* (e.g. a best-effort push) fails fast instead of blocking on a credential
+* prompt in a non-interactive environment.
+*/
+async function gitNoPrompt(...args) {
+	try {
+		const { stdout } = await execFileAsync$1("git", args, {
+			maxBuffer: GIT_MAX_BUFFER,
+			env: {
+				...process.env,
+				GIT_TERMINAL_PROMPT: "0"
+			}
+		});
+		return stdout.trim();
+	} catch (err) {
+		throw GitError.from(err, args);
+	}
 }
 /**
 * Run `git commit` in a worktree with gpg signing disabled at the command level.
@@ -99834,15 +100086,42 @@ function mergeIssues(base, local, remote) {
 	};
 }
 /**
+* Categorize issues from two unrelated tbd-sync roots by id (which embeds the
+* globally unique ULID). Pure and git-free so the rescue is robust to the
+* missing merge base. Substantive equality ignores version/updated_at so
+* trivial bumps don't masquerade as conflicts.
+*/
+function categorizeIssuesByUlid(local, remote) {
+	const localById = new Map(local.map((i) => [i.id, i]));
+	const remoteById = new Map(remote.map((i) => [i.id, i]));
+	const buckets = {
+		localOnly: [],
+		remoteOnly: [],
+		bothIdentical: [],
+		bothDifferent: []
+	};
+	for (const [id, localIssue] of localById) {
+		const remoteIssue = remoteById.get(id);
+		if (!remoteIssue) buckets.localOnly.push(localIssue);
+		else if (issuesSubstantivelyEqual(localIssue, remoteIssue)) buckets.bothIdentical.push(remoteIssue);
+		else buckets.bothDifferent.push({
+			local: localIssue,
+			remote: remoteIssue
+		});
+	}
+	for (const [id, remoteIssue] of remoteById) if (!localById.has(id)) buckets.remoteOnly.push(remoteIssue);
+	return buckets;
+}
+/**
 * Maximum retry attempts for push operations.
 */
 const MAX_PUSH_RETRIES = 3;
 /**
-* Check if error is a non-fast-forward rejection.
+* Check if error is a non-fast-forward rejection (also the init race signal).
 */
 function isNonFastForward(error) {
-	const msg = error instanceof Error ? error.message : String(error);
-	return msg.includes("non-fast-forward") || msg.includes("fetch first") || msg.includes("rejected");
+	const msg = error instanceof GitError ? `${error.stderr}\n${error.message}` : error instanceof Error ? error.message : String(error);
+	return /non-fast-forward|fetch first|rejected|updates were rejected/i.test(msg);
 }
 /**
 * Push with retry and merge on conflict.
@@ -99905,14 +100184,22 @@ async function branchExists(branch, baseDir) {
 	}
 }
 /**
-* Check if a remote branch exists.
+* Probe whether a remote branch exists, distinguishing a clean "absent" from a
+* "check failed".
+*
+* `git ls-remote --exit-code` exits 2 when the connection succeeded but no ref
+* matched; any other failure (auth/network/transient, or git not found) is a
+* check failure. Orphan-creating callers MUST branch on all three states and
+* never treat `check-failed` as `absent` — doing so risks creating a divergent
+* local branch when the remote is merely unreachable.
 */
-async function remoteBranchExists(remote, branch, baseDir) {
+async function probeRemoteBranch(remote, branch, baseDir) {
+	const dirArgs = baseDir ? ["-C", baseDir] : [];
 	try {
-		await git(...baseDir ? ["-C", baseDir] : [], "ls-remote", "--exit-code", remote, `refs/heads/${branch}`);
-		return true;
-	} catch {
-		return false;
+		await git(...dirArgs, "ls-remote", "--exit-code", remote, `refs/heads/${branch}`);
+		return "present";
+	} catch (err) {
+		return exitCodeOf(err) === 2 ? "absent" : "check-failed";
 	}
 }
 async function pathExists(path) {
@@ -100132,6 +100419,66 @@ async function migrateLegacyWorktreesToShared(baseDir, syncBranch = SYNC_BRANCH)
 	}
 }
 /**
+* Whether the given remote is configured (has a URL) in the repo at baseDir.
+* A local-only repo (no remote) is safe to orphan and never pushes.
+*/
+async function remoteIsConfigured(remote, baseDir) {
+	try {
+		await git("-C", baseDir, "config", "--get", `remote.${remote}.url`);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Whether the data-sync worktree carries any user issue files (is-<ulid>.md),
+* as opposed to only the initial orphan scaffold (.gitkeep / .gitattributes).
+*/
+async function worktreeHasUserIssues(dataSyncPath) {
+	try {
+		return (await readdir(join(dataSyncPath, "issues"))).some((name) => /^is-.*\.md$/.test(name));
+	} catch {
+		return false;
+	}
+}
+/**
+* Push a freshly-created orphan tbd-sync immediately so "first init wins"
+* (closes the #137 race window). Classifies the outcome:
+*
+*  - success            => pushed: true ("first init wins").
+*  - transient/permanent network/auth failure => best-effort, ignored
+*    (branch stays local-only until the first reachable sync).
+*  - non-fast-forward rejection => a detected init race (environment B pushed
+*    its own orphan first). Fetch, then:
+*      - scaffold-only local  => adopt the remote (reset local to remote).
+*      - local has user issues => fail loudly toward `tbd doctor --fix` so the
+*        local work is never silently discarded.
+*
+* MUST be called after the orphan's initial commit, while the worktree is on
+* syncBranch.
+*/
+async function pushFreshOrphan(baseDir, worktreePath, remote, syncBranch, dataSyncPath) {
+	try {
+		await gitNoPrompt("-C", worktreePath, "push", remote, `HEAD:refs/heads/${syncBranch}`);
+		return {
+			pushed: true,
+			adopted: false
+		};
+	} catch (err) {
+		if (!isNonFastForward(err)) return {
+			pushed: false,
+			adopted: false
+		};
+		await gitNoPrompt("-C", baseDir, "fetch", remote, syncBranch);
+		if (await worktreeHasUserIssues(dataSyncPath)) throw new Error(`Detected unrelated ${remote}/${syncBranch} histories during init, and the local branch already contains issues. Refusing to discard local work. Run \`tbd doctor --fix\` to reconcile the histories.`);
+		await git("-C", worktreePath, "reset", "--hard", `${remote}/${syncBranch}`);
+		return {
+			pushed: false,
+			adopted: true
+		};
+	}
+}
+/**
 * Initialize the hidden worktree for the tbd-sync branch.
 * Follows the decision tree from tbd-design.md §2.3.
 *
@@ -100173,7 +100520,13 @@ async function initWorktree(baseDir, remote = "origin", syncBranch = SYNC_BRANCH
 				created: true
 			};
 		}
-		if (await remoteBranchExists(remote, syncBranch, baseDir)) {
+		const hasRemote = await remoteIsConfigured(remote, baseDir);
+		const probe = hasRemote ? await probeRemoteBranch(remote, syncBranch, baseDir) : "absent";
+		if (probe === "check-failed") return {
+			success: false,
+			error: `Could not verify whether ${remote}/${syncBranch} exists (remote check failed); refusing to create a divergent local branch. Check connectivity/auth and retry.`
+		};
+		if (probe === "present") {
 			await git("-C", baseDir, "fetch", remote, syncBranch);
 			await git("-C", baseDir, "worktree", "add", "-b", syncBranch, worktreePath, `${remote}/${syncBranch}`);
 			return {
@@ -100194,6 +100547,7 @@ async function initWorktree(baseDir, remote = "origin", syncBranch = SYNC_BRANCH
 		await writeFile(join(dataSyncPath, "mappings", ".gitattributes"), "ids.yml merge=union\n");
 		await git("-C", worktreePath, "add", ".");
 		await gitCommit(worktreePath, "--no-verify", "-m", "Initialize tbd-sync branch");
+		if (hasRemote) await pushFreshOrphan(baseDir, worktreePath, remote, syncBranch, dataSyncPath);
 		return {
 			success: true,
 			path: worktreePath,
@@ -100250,22 +100604,30 @@ async function checkRemoteBranchHealth(remote = "origin", syncBranch = SYNC_BRAN
 		await git(...dirArgs, "fetch", remote, syncBranch);
 		const remoteHead = (await git(...dirArgs, "rev-parse", `refs/remotes/${remote}/${syncBranch}`)).trim();
 		let diverged = false;
-		try {
-			const mergeBase = await git(...dirArgs, "merge-base", syncBranch, `${remote}/${syncBranch}`);
-			const localHead = await git(...dirArgs, "rev-parse", syncBranch);
-			diverged = mergeBase.trim() !== localHead.trim() && mergeBase.trim() !== remoteHead;
-		} catch {
-			diverged = false;
+		let unrelated = false;
+		if (await branchExists(syncBranch, baseDir)) {
+			const localHead = (await git(...dirArgs, "rev-parse", syncBranch)).trim();
+			try {
+				const mergeBase = (await git(...dirArgs, "merge-base", syncBranch, `${remote}/${syncBranch}`)).trim();
+				diverged = mergeBase !== localHead && mergeBase !== remoteHead;
+			} catch (err) {
+				if (exitCodeOf(err) === 1) {
+					unrelated = true;
+					diverged = true;
+				}
+			}
 		}
 		return {
 			exists: true,
 			diverged,
+			unrelated,
 			head: remoteHead
 		};
 	} catch {
 		return {
 			exists: false,
-			diverged: false
+			diverged: false,
+			unrelated: false
 		};
 	}
 }
@@ -100304,6 +100666,88 @@ async function checkSyncConsistency(baseDir, syncBranch = SYNC_BRANCH, remote =
 		localBehind
 	};
 }
+/** Read all issues from a git ref's data-sync tree (no checkout needed). */
+async function readBranchIssues(baseDir, ref) {
+	let listing;
+	try {
+		listing = await git("-C", baseDir, "ls-tree", "-r", "--name-only", ref, "--", `${DATA_SYNC_DIR}/issues/`);
+	} catch {
+		return [];
+	}
+	const issues = [];
+	for (const path of listing.split("\n").filter((p) => /\/is-.*\.md$/.test(p))) try {
+		const content = await git("-C", baseDir, "show", `${ref}:${path}`);
+		issues.push(parseIssue(content));
+	} catch {}
+	return issues;
+}
+/** Read the ID mapping from a git ref's ids.yml (empty if absent). */
+async function readBranchMapping(baseDir, ref) {
+	try {
+		return parseIdMappingFromYaml(await git("-C", baseDir, "show", `${ref}:${DATA_SYNC_DIR}/mappings/ids.yml`));
+	} catch {
+		return {
+			shortToUlid: /* @__PURE__ */ new Map(),
+			ulidToShort: /* @__PURE__ */ new Map()
+		};
+	}
+}
+/** Preserve a losing issue version explicitly under attic/conflicts/. */
+async function preserveLosingVersion(dataSyncPath, loser) {
+	const conflictsDir = join(dataSyncPath, "attic", "conflicts");
+	await mkdir(conflictsDir, { recursive: true });
+	await writeFile(join(conflictsDir, `${loser.id}__${nowFilenameTimestamp()}.md`), serializeIssue(loser));
+}
+/**
+* Non-destructively rescue an unrelated tbd-sync history (#139).
+*
+* Reconciles at the issue-file layer (ULIDs guarantee no collisions), never via
+* a git history merge. Adopts the remote as the canonical base and replays
+* local work onto it. The only destructive step (the reset) happens AFTER a
+* backup branch is created, so the pre-rescue HEAD is always recoverable and
+* the rescue is restartable.
+*
+* MUST be called while holding `withSharedDataSyncLock`. Aborts if the
+* data-sync worktree is dirty or has a merge in progress.
+*/
+async function rescueUnrelatedHistory(baseDir, remote = "origin", syncBranch = SYNC_BRANCH) {
+	const { sharedWorktreePath: worktreePath, sharedDataSyncDir: dataSyncPath } = await getSharedPaths(baseDir);
+	if ((await git("-C", worktreePath, "status", "--porcelain")).trim()) throw new Error("Refusing to rescue: the tbd-sync worktree has uncommitted changes. Commit or stash them, then retry.");
+	if (await git("-C", worktreePath, "rev-parse", "-q", "--verify", "MERGE_HEAD").then(() => true).catch(() => false)) throw new Error("Refusing to rescue: a merge is in progress in the tbd-sync worktree. Resolve or abort it, then retry.");
+	await gitNoPrompt("-C", baseDir, "fetch", remote, syncBranch);
+	const localIssues = await listIssues(dataSyncPath);
+	const localMapping = await loadIdMapping(dataSyncPath);
+	const remoteIssues = await readBranchIssues(baseDir, `${remote}/${syncBranch}`);
+	const remoteMapping = await readBranchMapping(baseDir, `${remote}/${syncBranch}`);
+	const localHead = (await git("-C", baseDir, "rev-parse", syncBranch)).trim();
+	const backupBranch = `tbd-backup-${nowFilenameTimestamp()}`;
+	await git("-C", baseDir, "branch", backupBranch, localHead);
+	const buckets = categorizeIssuesByUlid(localIssues, remoteIssues);
+	await git("-C", worktreePath, "reset", "--hard", `${remote}/${syncBranch}`);
+	let conflicts = 0;
+	for (const issue of buckets.localOnly) await writeIssue(dataSyncPath, issue);
+	for (const { local, remote: remoteIssue } of buckets.bothDifferent) {
+		const { merged } = mergeIssues(null, local, remoteIssue);
+		await writeIssue(dataSyncPath, merged);
+		for (const side of [local, remoteIssue]) if (!issuesSubstantivelyEqual(side, merged)) {
+			await preserveLosingVersion(dataSyncPath, side);
+			conflicts++;
+		}
+	}
+	const mergedMapping = mergeIdMappings(remoteMapping, localMapping);
+	const allIssues = await listIssues(dataSyncPath);
+	reconcileMappings(allIssues.map((i) => i.id), mergedMapping, remoteMapping);
+	await saveIdMapping(dataSyncPath, mergedMapping);
+	await git("-C", worktreePath, "add", "-A");
+	if ((await git("-C", worktreePath, "status", "--porcelain")).trim()) await gitCommit(worktreePath, "--no-verify", "-m", `tbd rescue: adopt remote base + reconcile ${buckets.localOnly.length + buckets.bothDifferent.length} issue(s) (${buckets.localOnly.length} local-only, ${buckets.bothDifferent.length} merged)`);
+	return {
+		backupBranch,
+		localOnly: buckets.localOnly.length,
+		merged: buckets.bothDifferent.length,
+		conflicts,
+		totalIssues: allIssues.length
+	};
+}
 /**
 * Count issues on a remote sync branch without creating a worktree.
 * Used by doctor to show accurate statistics on fresh clones.
@@ -100651,124 +101095,6 @@ const initCommand = new Command("init").description("Initialize tbd in a git rep
 	await new InitHandler(command).run(options);
 });
 
-//#endregion
-//#region src/utils/zod-error-utils.ts
-/**
-* Helpers for rendering Zod errors without relying on object inspection.
-*/
-/**
-* Format a ZodError as concise path-qualified messages for CLI output.
-*/
-function formatZodError(error) {
-	const messages = error.issues.map((issue) => {
-		return `${issue.path.length > 0 ? issue.path.join(".") : "<root>"}: ${issue.message}`;
-	});
-	return messages.length > 0 ? messages.join("; ") : error.message;
-}
-/**
-* Format unknown thrown values as safe strings for warnings and diagnostics.
-*/
-function formatUnknownError(error) {
-	if (error instanceof ZodError) return formatZodError(error);
-	if (error instanceof Error) return error.message;
-	return String(error);
-}
-
-//#endregion
-//#region src/file/storage.ts
-/**
-* Storage layer for issue files.
-*
-* Provides atomic file operations and issue CRUD operations.
-* All operations work on the data-sync directory selected by the caller. In production
-* that is the shared hidden worktree under $GIT_COMMON_DIR/tbd/data-sync-worktree/.
-*
-* See: tbd-design.md §3.2 Storage Layer
-*/
-/**
-* Maximum issue files read concurrently to avoid exhausting file descriptors in large repos.
-*/
-const ISSUE_READ_BATCH_SIZE = 200;
-/**
-* Get the path to an issue file.
-*/
-function getIssuePath(baseDir, id) {
-	return join(baseDir, "issues", `${id}.md`);
-}
-/**
-* Read an issue from the worktree.
-* @throws If the issue file doesn't exist or is invalid.
-*/
-async function readIssue(baseDir, id) {
-	return parseIssue(await readFile(getIssuePath(baseDir, id), "utf-8"));
-}
-/**
-* Write an issue to the worktree.
-* Uses atomic write to prevent corruption.
-*/
-async function writeIssue(baseDir, issue) {
-	const validIssue = IssueSchema.parse(issue);
-	await writeFile(getIssuePath(baseDir, validIssue.id), serializeIssue(validIssue));
-}
-/**
-* List all issues in the worktree.
-* Returns empty array if issues directory doesn't exist.
-*
-* Uses parallel file reading for better performance with many issues.
-*/
-async function listIssues(baseDir, options = {}) {
-	const warnOnInvalid = options.warnOnInvalid ?? true;
-	const issuesDir = join(baseDir, "issues");
-	let files;
-	try {
-		files = await readdir(issuesDir);
-	} catch {
-		return [];
-	}
-	const mdFiles = files.filter((f) => f.endsWith(".md"));
-	const issues = [];
-	for (let i = 0; i < mdFiles.length; i += ISSUE_READ_BATCH_SIZE) {
-		const batch = mdFiles.slice(i, i + ISSUE_READ_BATCH_SIZE);
-		const fileContents = await Promise.all(batch.map(async (file) => {
-			const filePath = join(issuesDir, file);
-			try {
-				return {
-					file,
-					content: await readFile(filePath, "utf-8")
-				};
-			} catch (error) {
-				return {
-					file,
-					error: formatUnknownError(error)
-				};
-			}
-		}));
-		for (const result of fileContents) {
-			if ("error" in result) {
-				reportInvalidIssueFile({
-					file: result.file,
-					reason: `failed to read file: ${result.error}`
-				}, warnOnInvalid, options.onInvalidIssue);
-				continue;
-			}
-			try {
-				const issue = parseIssue(result.content);
-				issues.push(issue);
-			} catch (error) {
-				reportInvalidIssueFile({
-					file: result.file,
-					reason: formatUnknownError(error)
-				}, warnOnInvalid, options.onInvalidIssue);
-			}
-		}
-	}
-	return issues;
-}
-function reportInvalidIssueFile(invalidIssue, warnOnInvalid, onInvalidIssue) {
-	onInvalidIssue?.(invalidIssue);
-	if (warnOnInvalid) console.warn(`Skipping invalid issue file: ${invalidIssue.file}: ${invalidIssue.reason}`);
-}
-
 //#endregion
 //#region src/lib/priority.ts
 /**
@@ -104042,6 +104368,7 @@ var SyncHandler = class extends BaseCommand {
 				this.output.debug(`Committed ${count} file(s) to sync branch`);
 			}
 			await git("fetch", remote, syncBranch);
+			if ((await checkRemoteBranchHealth(remote, syncBranch)).unrelated) throw new UnrelatedHistoriesError(remote, syncBranch);
 			let behindCommits = 0;
 			try {
 				const behindOutput = await git("rev-list", "--count", `${syncBranch}..${remote}/${syncBranch}`);
@@ -104146,6 +104473,7 @@ var SyncHandler = class extends BaseCommand {
 				}
 			}
 		} catch (error) {
+			if (error instanceof SyncError) throw error;
 			this.output.debug(`Fetch failed (may be first sync): ${error.message}`);
 		}
 		let aheadCommits = 0;
@@ -104178,6 +104506,7 @@ var SyncHandler = class extends BaseCommand {
 		summary.conflicts = conflicts.length;
 		spinner.stop();
 		if (pushFailed) {
+			if ((await checkRemoteBranchHealth(remote, syncBranch)).unrelated) throw new UnrelatedHistoriesError(remote, syncBranch);
 			let displayError = pushError;
 			const httpMatch = /HTTP (\d+)/.exec(pushError);
 			const curlMatch = /curl \d+ (.+?)(?:\n|$)/.exec(pushError);
@@ -105314,6 +105643,35 @@ function renderDiagnostics(results, colors) {
 *
 * See: tbd-design.md §4.9 Doctor
 */
+/**
+* Map remote sync-branch health to a "Remote sync branch" diagnostic.
+*
+* Returns null when the remote branch does not exist (the caller then falls
+* through to local-branch / new-repo handling). Unrelated histories are a hard
+* ✗ finding routed to `tbd doctor --fix` (the rescue), NOT `tbd sync` — push
+* can never fast-forward and a plain merge refuses, so `tbd sync` cannot help.
+*/
+function classifyRemoteSyncHealth(health, remote, syncBranch) {
+	if (!health.exists) return null;
+	if (health.unrelated) return {
+		name: "Remote sync branch",
+		status: "error",
+		fixable: true,
+		message: `${remote}/${syncBranch} histories are unrelated (no common ancestor) — push cannot succeed`,
+		suggestion: "Run: tbd doctor --fix to reconcile the unrelated histories"
+	};
+	if (health.diverged) return {
+		name: "Remote sync branch",
+		status: "warn",
+		message: `${remote}/${syncBranch} has diverged`,
+		suggestion: "Run: tbd sync to reconcile changes"
+	};
+	return {
+		name: "Remote sync branch",
+		status: "ok",
+		message: `${remote}/${syncBranch}`
+	};
+}
 const CONFIG_DIR = TBD_DIR;
 var DoctorHandler = class extends BaseCommand {
 	dataSyncDir = "";
@@ -105365,7 +105723,7 @@ var DoctorHandler = class extends BaseCommand {
 		const maxHistory = Number.isNaN(parsedMaxHistory) || parsedMaxHistory < 0 ? 50 : parsedMaxHistory;
 		healthChecks.push(await this.checkMissingMappings(options.fix, maxHistory));
 		healthChecks.push(await this.checkLocalSyncBranch());
-		healthChecks.push(await this.checkRemoteSyncBranch());
+		healthChecks.push(await this.checkRemoteSyncBranch(options.fix));
 		healthChecks.push(await this.checkLocalVsRemoteData());
 		healthChecks.push(await this.checkCloneScenarios());
 		healthChecks.push(await this.checkSyncConsistency());
@@ -106198,23 +106556,27 @@ var DoctorHandler = class extends BaseCommand {
 	* Check remote sync branch health.
 	* See: plan-2026-01-28-sync-worktree-recovery-and-hardening.md §4b
 	*/
-	async checkRemoteSyncBranch() {
+	async checkRemoteSyncBranch(fix) {
 		const syncBranch = this.config?.sync.branch ?? "tbd-sync";
 		const remote = this.config?.sync.remote ?? "origin";
 		const remoteHealth = await checkRemoteBranchHealth(remote, syncBranch, this.cwd);
-		if (remoteHealth.exists) {
-			if (remoteHealth.diverged) return {
+		if (remoteHealth.unrelated && fix && !this.checkDryRun("Rescue unrelated tbd-sync histories")) try {
+			const result = await withSharedDataSyncLock(this.cwd, async () => rescueUnrelatedHistory(this.cwd, remote, syncBranch));
+			return {
 				name: "Remote sync branch",
-				status: "warn",
-				message: `${remote}/${syncBranch} has diverged`,
-				suggestion: "Run: tbd sync to reconcile changes"
+				status: "ok",
+				message: `rescued: adopted ${remote}/${syncBranch} base, reconciled ${result.localOnly} local-only + ${result.merged} merged (backup: ${result.backupBranch})`
 			};
+		} catch (error) {
 			return {
 				name: "Remote sync branch",
-				status: "ok",
-				message: `${remote}/${syncBranch}`
+				status: "error",
+				message: `rescue failed: ${error instanceof Error ? error.message : String(error)}`,
+				suggestion: "Resolve manually; the pre-rescue state is on the tbd-backup-* branch"
 			};
 		}
+		const diag = classifyRemoteSyncHealth(remoteHealth, remote, syncBranch);
+		if (diag) return diag;
 		if ((await checkLocalBranchHealth(syncBranch, this.cwd)).exists) return {
 			name: "Remote sync branch",
 			status: "warn",
@@ -108116,6 +108478,7 @@ var PrimeHandler = class extends BaseCommand {
 		console.log(`${colors.success("✓")} Initialized in this repo`);
 		if (await this.checkHooksInstalled(tbdRoot)) console.log(`${colors.success("✓")} Hooks installed`);
 		else console.log(`${colors.dim("✗")} Hooks not installed (run: tbd setup --auto)`);
+		console.log(colors.dim("  Run `tbd setup --auto` to refresh skills and settings (e.g. after upgrading tbd)."));
 		console.log("");
 		console.log(colors.bold("=== PROJECT STATUS ==="));
 		try {
@@ -109058,9 +109421,11 @@ async function getShortcutDirectory(quiet = false) {
 }
 /**
 * DO NOT EDIT marker inserted after the frontmatter of every generated SKILL.md.
+* Carries the shared `format=fNN` integration code so the forward-compatibility
+* guard can detect a skill written by a newer tbd (see {@link writeSkillFile}).
 * Formatted to match flowmark output.
 */
-const SKILL_DO_NOT_EDIT_MARKER = "<!-- DO NOT EDIT: Generated by tbd setup.\nRun 'tbd setup' to update.\n-->";
+const SKILL_DO_NOT_EDIT_MARKER = `<!-- DO NOT EDIT: Generated by tbd setup (format=${AGENT_INTEGRATION_FORMAT}).\nRun 'tbd setup' to update.\n-->`;
 /**
 * Build the full generated SKILL.md payload: the bundled skill content with the
 * shortcut/guideline directory appended and a DO NOT EDIT marker after the
@@ -109078,8 +109443,19 @@ async function buildSkillPayload(quiet = false) {
 }
 /**
 * Write a generated SKILL.md payload to a target path, creating parent dirs.
+*
+* Forward-compatibility guard: if an existing skill carries a newer
+* `format=fNN` stamp than this tbd understands, refuse to overwrite it and tell
+* the user to upgrade. Guarding each generated surface at its own write point
+* means an older tbd cannot partial-downgrade a newer committed skill,
+* regardless of the order in which surfaces are written.
 */
 async function writeSkillFile(targetPath, payload) {
+	let existing = null;
+	try {
+		existing = await readFile(targetPath, "utf-8");
+	} catch {}
+	if (existing !== null) assertNotNewerFormat(existing, targetPath);
 	await mkdir(dirname(targetPath), { recursive: true });
 	await writeFile(targetPath, payload);
 }
@@ -110124,10 +110500,16 @@ var SetupAutoHandler = class extends BaseCommand {
 			const entries = await readdir(scriptsDir, { withFileTypes: true });
 			for (const entry of entries) if (entry.isFile()) {
 				const filename = entry.name;
-				if (LEGACY_TBD_SCRIPTS.includes(filename)) try {
-					await rm(join(scriptsDir, filename));
-					scriptsRemoved.push(filename);
-				} catch {}
+				if (LEGACY_TBD_SCRIPTS.includes(filename)) {
+					if (this.ctx.dryRun) {
+						scriptsRemoved.push(filename);
+						continue;
+					}
+					try {
+						await rm(join(scriptsDir, filename));
+						scriptsRemoved.push(filename);
+					} catch {}
+				}
 			}
 		} catch {}
 		return scriptsRemoved;
@@ -110171,7 +110553,7 @@ var SetupAutoHandler = class extends BaseCommand {
 						modified = true;
 					}
 				}
-				if (modified) {
+				if (modified && !this.ctx.dryRun) {
 					if (Object.keys(hooks).length === 0) delete settings.hooks;
 					await writeFile(projectSettingsPath, JSON.stringify(settings, null, 2) + "\n");
 				}
@@ -110189,7 +110571,8 @@ var SetupAutoHandler = class extends BaseCommand {
 			const parts = [];
 			if (scriptsRemoved.length > 0) parts.push(`${scriptsRemoved.length} script(s)`);
 			if (hooksRemoved > 0) parts.push(`${hooksRemoved} hook(s)`);
-			console.log(colors.dim(`Cleaned up legacy ${parts.join(" and ")}`));
+			if (this.ctx.dryRun) this.output.dryRun(`Would clean up legacy ${parts.join(" and ")}`);
+			else console.log(colors.dim(`Cleaned up legacy ${parts.join(" and ")}`));
 		}
 		await this.syncDocs(cwd);
 		const targeting = this.resolveTargeting();