get-tbd 0.2.0 → 0.2.2

package/dist/cli.mjs

@@ -1,8 +1,8 @@
 import { C as IssueSchema, S as IssueKind, T as IssueTitle, c as DATA_SYNC_SCHEMA_VERSION, i as COMMON_DIR_LAYOUT_FIELD_ORDER, n as AtticEntrySchema, o as CommonDirLayoutSchema, t as ATTIC_ENTRY_FIELD_ORDER, w as IssueStatus, y as ISSUE_TITLE_MAX_LENGTH } from "./schemas-f0EcuAVu.mjs";
-import { a as insertAfterFrontmatter, c as noopLogger, i as serializeIssue, n as parseIssue, o as parseMarkdown, r as parseMarkdownWithFrontmatter, s as stripFrontmatter, t as VERSION$1 } from "./src-rIE4xSVs.mjs";
+import { a as insertAfterFrontmatter, c as noopLogger, i as serializeIssue, n as parseIssue, o as parseMarkdown, r as parseMarkdownWithFrontmatter, s as stripFrontmatter, t as VERSION$1 } from "./src-BpvcrLnq.mjs";
 import { a as parseYamlWithConflictDetection, d as PAGINATION_LINE_THRESHOLD, f as PARENT_CONTEXT_MAX_LINES, l as comparisonChain, n as detectDuplicateYamlKeys, o as sortKeys, s as stringifyYaml, u as ordering } from "./yaml-utils-BPy991by.mjs";
 import { A as WORKSPACES_DIR, C as SYNC_BRANCH, D as TBD_SHORTCUTS_STANDARD, E as TBD_GUIDELINES_DIR, F as resolveDataSyncDir, I as resolveSharedTbdPaths, M as getWorkspaceDir, N as isValidWorkspaceName, O as TBD_SHORTCUTS_SYSTEM, P as resolveAtticDir, S as LEGACY_WORKTREE_DIR, T as TBD_DOCS_DIR, _ as DATA_SYNC_DIR, a as isInitialized, b as DEFAULT_SHORTCUT_PATHS, c as readConfigWithMigration, d as writeConfig, g as CHARS_PER_TOKEN, h as isCompatibleFormat, i as initConfig, j as WORKTREE_DIR_NAME, k as TBD_TEMPLATES_DIR, l as readLocalState, m as formatUpgradeMessage, n as findTbdRoot, o as markWelcomeSeen, p as CURRENT_FORMAT, r as hasSeenWelcome, s as readConfig, t as IncompatibleFormatError, u as updateLocalState, v as DATA_SYNC_DIR_NAME, w as TBD_DIR, x as DEFAULT_TEMPLATE_PATHS, y as DEFAULT_GUIDELINES_PATHS } from "./config-BJz1m9eN.mjs";
-import { C as withLockfile, S as DATA_SYNC_LOCK_OPTIONS, _ as formatDisplayId, a as hasShortId, b as normalizeIssueId, c as parseIdMappingFromYaml, d as resolveToInternalId, f as saveIdMapping, g as formatDebugId, h as extractUlidFromInternalId, i as generateUniqueShortId, l as reconcileMappings, m as extractShortId, o as loadIdMapping, p as extractPrefix, s as mergeIdMappings, t as addIdMapping, u as resolveIdMappingConflicts, v as generateInternalId, x as validateIssueId, y as makeInternalId } from "./id-mapping-CtfTfGIh.mjs";
+import { C as withLockfile, S as DATA_SYNC_LOCK_OPTIONS, _ as formatDisplayId, a as hasShortId, b as normalizeIssueId, c as parseIdMappingFromYaml, d as resolveToInternalId, f as saveIdMapping, g as formatDebugId, h as extractUlidFromInternalId, i as generateUniqueShortId, l as reconcileMappings, m as extractShortId, o as loadIdMapping, p as extractPrefix, s as mergeIdMappings, t as addIdMapping, u as resolveIdMappingConflicts, v as generateInternalId, x as validateIssueId, y as makeInternalId } from "./id-mapping-687_UEsy.mjs";
 import { createRequire } from "node:module";
 import { ZodError } from "zod";
 import matter from "gray-matter";
@@ -620,6 +620,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:
@@ -917,6 +929,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/file/git.ts
 /**
@@ -931,6 +1061,55 @@ function nowFilenameTimestamp() {
 */
 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).
@@ -945,8 +1124,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.
@@ -1244,15 +1446,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.
@@ -1315,14 +1544,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) {
@@ -1542,6 +1779,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.
 *
@@ -1583,7 +1880,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 {
@@ -1604,6 +1907,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,
@@ -1660,22 +1964,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
 		};
 	}
 }
@@ -1714,6 +2026,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.
@@ -2061,124 +2455,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
 /**
@@ -5452,6 +5728,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}`);
@@ -5556,6 +5833,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;
@@ -5588,6 +5866,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);
@@ -6724,6 +7003,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 = "";
@@ -6775,7 +7083,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());
@@ -7010,7 +7318,7 @@ var DoctorHandler = class extends BaseCommand {
 			status: "ok"
 		};
 		if (fix && !this.checkDryRun("Resolve merge conflicts in ids.yml")) try {
-			const { resolveIdMappingConflicts, saveIdMapping } = await import("./id-mapping-CFoPVinz.mjs");
+			const { resolveIdMappingConflicts, saveIdMapping } = await import("./id-mapping-mtoSP9Qt.mjs");
 			const resolved = resolveIdMappingConflicts(content);
 			await saveIdMapping(this.dataSyncDir, resolved);
 			return {
@@ -7059,7 +7367,7 @@ var DoctorHandler = class extends BaseCommand {
 			status: "ok"
 		};
 		if (fix && !this.checkDryRun("Fix duplicate ID mapping keys")) try {
-			const { loadIdMapping, saveIdMapping } = await import("./id-mapping-CFoPVinz.mjs");
+			const { loadIdMapping, saveIdMapping } = await import("./id-mapping-mtoSP9Qt.mjs");
 			const mapping = await loadIdMapping(this.dataSyncDir);
 			await saveIdMapping(this.dataSyncDir, mapping);
 			return {
@@ -7198,7 +7506,7 @@ var DoctorHandler = class extends BaseCommand {
 			name: "ID mapping coverage",
 			status: "ok"
 		};
-		const { loadIdMapping, saveIdMapping, reconcileMappings } = await import("./id-mapping-CFoPVinz.mjs");
+		const { loadIdMapping, saveIdMapping, reconcileMappings } = await import("./id-mapping-mtoSP9Qt.mjs");
 		const mapping = await loadIdMapping(this.dataSyncDir);
 		const missingIds = [];
 		for (const issue of this.issues) {
@@ -7210,7 +7518,7 @@ var DoctorHandler = class extends BaseCommand {
 			status: "ok"
 		};
 		if (fix && !this.checkDryRun("Create missing ID mappings")) {
-			const { parseIdMappingFromYaml, mergeIdMappings } = await import("./id-mapping-CFoPVinz.mjs");
+			const { parseIdMappingFromYaml, mergeIdMappings } = await import("./id-mapping-mtoSP9Qt.mjs");
 			let historicalMapping;
 			try {
 				const syncBranch = (await import("./config-DlCUMyCG.mjs").then((m) => m.readConfig(this.cwd))).sync.branch;
@@ -7608,23 +7916,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",
@@ -9453,6 +9765,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 {
@@ -10395,9 +10708,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
@@ -10415,8 +10730,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);
 }
@@ -11461,10 +11787,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;
@@ -11508,7 +11840,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");
 				}
@@ -11526,7 +11858,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();