get-tbd 0.1.30 → 0.2.1

package/dist/cli.mjs

@@ -1,8 +1,8 @@
-import { S as IssueTitle, b as IssueSchema, g as ISSUE_TITLE_MAX_LENGTH, n as AtticEntrySchema, t as ATTIC_ENTRY_FIELD_ORDER, x as IssueStatus, y as IssueKind } from "./schemas-C8mOQykE.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-BK_EF6mk.mjs";
+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-CtZIHxYM.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 getWorkspaceDir, C as TBD_GUIDELINES_DIR, D as WORKSPACES_DIR, E as TBD_TEMPLATES_DIR, M as resolveAtticDir, N as resolveDataSyncDir, O as WORKTREE_DIR, S as TBD_DOCS_DIR, T as TBD_SHORTCUTS_SYSTEM, _ as DEFAULT_GUIDELINES_PATHS, a as isInitialized, b as SYNC_BRANCH, c as readConfigWithMigration, d as writeConfig, g as DATA_SYNC_DIR_NAME, h as DATA_SYNC_DIR, i as initConfig, j as isValidWorkspaceName, k as WORKTREE_DIR_NAME, l as readLocalState, m as CHARS_PER_TOKEN, n as findTbdRoot, o as markWelcomeSeen, p as CURRENT_FORMAT, r as hasSeenWelcome, s as readConfig, u as updateLocalState, v as DEFAULT_SHORTCUT_PATHS, w as TBD_SHORTCUTS_STANDARD, x as TBD_DIR, y as DEFAULT_TEMPLATE_PATHS } from "./config-DVap9omo.mjs";
-import { _ 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-CqrrLgeX.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-687_UEsy.mjs";
 import { createRequire } from "node:module";
 import { ZodError } from "zod";
 import matter from "gray-matter";
@@ -12,7 +12,7 @@ import pc from "picocolors";
 import { marked } from "marked";
 import { markedTerminal } from "marked-terminal";
 import { execFile, execSync, spawn, spawnSync } from "node:child_process";
-import { access, chmod, cp, mkdir, readFile, readdir, rename, rm, stat, unlink } from "node:fs/promises";
+import { access, chmod, cp, mkdir, readFile, readdir, realpath, rename, rm, stat, unlink } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
 import { writeFile } from "atomically";
 import { homedir } from "node:os";
@@ -620,25 +620,15 @@ var SyncError = class extends CLIError {
 	}
 };
 /**
-* Worktree missing error - the data-sync-worktree directory doesn't exist.
-* This indicates the worktree was never created or was deleted.
-* See: tbd-design.md §2.3.6 Worktree Error Classes
+* 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 WorktreeMissingError = class extends CLIError {
-	constructor(message = "Worktree not found at .tbd/data-sync-worktree/. Run 'tbd doctor --fix' to repair.") {
-		super(message, 1);
-		this.name = "WorktreeMissingError";
-	}
-};
-/**
-* Worktree corrupted error - the worktree exists but is invalid.
-* This can occur when the .git file is missing or points to an invalid location.
-* See: tbd-design.md §2.3.6 Worktree Error Classes
-*/
-var WorktreeCorruptedError = class extends CLIError {
-	constructor(message = "Worktree at .tbd/data-sync-worktree/ is corrupted. Run 'tbd doctor --fix' to repair.") {
-		super(message, 1);
-		this.name = "WorktreeCorruptedError";
+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";
 	}
 };
 /**
@@ -706,10 +696,7 @@ var BaseCommand = class {
 		try {
 			return await action();
 		} catch (error) {
-			if (error instanceof CLIError) {
-				this.output.error(error.message);
-				throw error;
-			}
+			if (error instanceof CLIError) throw error;
 			const originalError = error instanceof Error ? error : void 0;
 			const detail = originalError?.message;
 			const fullMessage = detail && detail !== errorMessage ? `${errorMessage}: ${detail}` : errorMessage;
@@ -740,7 +727,7 @@ var BaseCommand = class {
 /**
 * Check if a path exists on the filesystem.
 */
-async function pathExists(path) {
+async function pathExists$1(path) {
 	try {
 		await access(path);
 		return true;
@@ -780,7 +767,7 @@ function hasGitignorePattern(content, pattern) {
 async function ensureGitignorePatterns(gitignorePath, patterns, header) {
 	let content = "";
 	let created = false;
-	if (await pathExists(gitignorePath)) content = await readFile(gitignorePath, "utf-8");
+	if (await pathExists$1(gitignorePath)) content = await readFile(gitignorePath, "utf-8");
 	else created = true;
 	const entries = [];
 	let currentPreamble = [];
@@ -942,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
 /**
@@ -956,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).
@@ -970,8 +1124,43 @@ 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.
+*
+* Internal tbd-sync commits are machine-generated data commits on the data branch,
+* not user commits. They must not depend on ambient `commit.gpgsign` config: in
+* signed-by-default environments without a usable signing key, an unguarded
+* `git commit` fails and leaves `tbd-sync` unborn, which the f04 fail-closed
+* health check then surfaces as "worktree corrupted" on every command.
+*/
+async function gitCommit(workdir, ...args) {
+	return git("-c", "commit.gpgsign=false", "-C", workdir, "commit", ...args);
 }
 /**
 * Minimum Git version required.
@@ -1088,23 +1277,6 @@ function getUpgradeInstructions(currentVersion) {
 	return `Git ${versionStr} detected. Git ${MIN_GIT_VERSION}+ required for tbd.\nUpgrade: ${upgradeUrl}`;
 }
 /**
-* Execute a git command with isolated index.
-* This protects the user's staging area during sync operations.
-*
-* See: tbd-design.md §3.3.2 Writing to Sync Branch
-*/
-async function withIsolatedIndex(fn) {
-	const isolatedIndex = join(await git("rev-parse", "--git-dir"), "tbd-index");
-	const originalIndex = process.env.GIT_INDEX_FILE;
-	try {
-		process.env.GIT_INDEX_FILE = isolatedIndex;
-		return await fn();
-	} finally {
-		if (originalIndex) process.env.GIT_INDEX_FILE = originalIndex;
-		else delete process.env.GIT_INDEX_FILE;
-	}
-}
-/**
 * Field-level merge strategies for Issue fields.
 * See: tbd-design.md §3.5 Merge Rules
 */
@@ -1274,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.
@@ -1330,36 +1529,63 @@ async function pushWithRetry(syncBranch, remote, onMergeNeeded, baseDir) {
 /**
 * Get the current branch name.
 */
-async function getCurrentBranch() {
-	return git("rev-parse", "--abbrev-ref", "HEAD");
+async function getCurrentBranch(baseDir) {
+	return git(...baseDir ? ["-C", baseDir] : [], "rev-parse", "--abbrev-ref", "HEAD");
 }
 /**
 * Check if a branch exists locally.
 */
-async function branchExists(branch) {
+async function branchExists(branch, baseDir) {
 	try {
-		await git("rev-parse", "--verify", `refs/heads/${branch}`);
+		await git(...baseDir ? ["-C", baseDir] : [], "rev-parse", "--verify", `refs/heads/${branch}`);
 		return true;
 	} catch {
 		return false;
 	}
 }
 /**
-* 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) {
+async function probeRemoteBranch(remote, branch, baseDir) {
+	const dirArgs = baseDir ? ["-C", baseDir] : [];
 	try {
-		await git("ls-remote", "--exit-code", remote, `refs/heads/${branch}`);
+		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) {
+	try {
+		await access(path);
 		return true;
 	} catch {
 		return false;
 	}
 }
+async function pathsReferToSameLocation(a, b) {
+	if (normalize(a) === normalize(b)) return true;
+	try {
+		return normalize(await realpath(a)) === normalize(await realpath(b));
+	} catch {
+		return false;
+	}
+}
+async function getSharedPaths(baseDir) {
+	return resolveSharedTbdPaths(baseDir);
+}
 /**
 * Check if the hidden worktree exists and is valid.
 */
 async function worktreeExists(baseDir) {
-	const worktreePath = join(baseDir, WORKTREE_DIR);
+	const { sharedWorktreePath: worktreePath } = await getSharedPaths(baseDir);
 	try {
 		await access(worktreePath);
 		await access(join(worktreePath, ".git"));
@@ -1373,15 +1599,15 @@ async function worktreeExists(baseDir) {
 * See: tbd-design.md §2.3 Worktree Lifecycle
 * See: plan-2026-01-28-sync-worktree-recovery-and-hardening.md §3
 */
-async function checkWorktreeHealth(baseDir) {
-	const worktreePath = join(baseDir, WORKTREE_DIR);
+async function checkWorktreeHealth(baseDir, syncBranch = SYNC_BRANCH) {
+	const { sharedWorktreePath: worktreePath } = await getSharedPaths(baseDir);
 	try {
 		const lines = (await git("-C", baseDir, "worktree", "list", "--porcelain")).split("\n");
 		let foundWorktree = false;
 		let isPrunable = false;
 		for (let i = 0; i < lines.length; i++) {
 			const line = lines[i];
-			if (line?.startsWith("worktree ") && line.includes(WORKTREE_DIR_NAME)) {
+			if (line?.startsWith("worktree ") && await pathsReferToSameLocation(line.slice(9), worktreePath)) {
 				foundWorktree = true;
 				for (let j = i + 1; j < lines.length && !lines[j]?.startsWith("worktree "); j++) if (lines[j]?.startsWith("prunable")) {
 					isPrunable = true;
@@ -1449,6 +1675,14 @@ async function checkWorktreeHealth(baseDir) {
 		} catch {
 			branch = null;
 		}
+		if (branch !== syncBranch) return {
+			exists: true,
+			valid: false,
+			status: "corrupted",
+			branch,
+			commit,
+			error: branch === null ? `Shared worktree is detached; expected branch ${syncBranch}` : `Shared worktree is on ${branch}; expected branch ${syncBranch}`
+		};
 		return {
 			exists: true,
 			valid: true,
@@ -1467,22 +1701,170 @@ async function checkWorktreeHealth(baseDir) {
 		};
 	}
 }
+function isLegacyDataSyncWorktreePath(path, sharedWorktreePath) {
+	const normalized = normalize(path);
+	if (normalized === normalize(sharedWorktreePath)) return false;
+	return basename(normalized) === WORKTREE_DIR_NAME && basename(dirname(normalized)) === TBD_DIR;
+}
+async function listLegacyWorktreePaths(baseDir, sharedWorktreePath) {
+	const paths = /* @__PURE__ */ new Set();
+	try {
+		const worktreeList = await git("-C", baseDir, "worktree", "list", "--porcelain");
+		for (const line of worktreeList.split("\n")) {
+			if (!line.startsWith("worktree ")) continue;
+			const worktreePath = line.slice(9);
+			if (isLegacyDataSyncWorktreePath(worktreePath, sharedWorktreePath)) paths.add(worktreePath);
+		}
+	} catch {}
+	const currentCheckoutLegacyPath = join(baseDir, LEGACY_WORKTREE_DIR);
+	if (currentCheckoutLegacyPath !== sharedWorktreePath && await pathExists(currentCheckoutLegacyPath)) paths.add(currentCheckoutLegacyPath);
+	return Array.from(paths);
+}
+async function preserveLegacyWorktreeHead(baseDir, legacyPath, syncBranch) {
+	if (!await pathExists(join(legacyPath, ".git"))) return;
+	if ((await git("-C", legacyPath, "status", "--porcelain").catch(() => "")).trim()) {
+		await git("-C", legacyPath, "add", "-A");
+		await gitCommit(legacyPath, "--no-verify", "-m", "tbd: preserve legacy sync data").catch((error) => {
+			if (!(error instanceof Error ? error.message : String(error)).includes("nothing to commit")) throw error;
+		});
+	}
+	const head = await git("-C", legacyPath, "rev-parse", "HEAD").catch(() => "");
+	if (!head) return;
+	const branchHead = await git("-C", baseDir, "rev-parse", syncBranch).catch(() => "");
+	if (!branchHead) {
+		await git("-C", baseDir, "branch", syncBranch, head);
+		return;
+	}
+	if (head === branchHead) return;
+	if (await git("-C", baseDir, "merge-base", "--is-ancestor", branchHead, head).then(() => true).catch(() => false)) {
+		await git("-C", baseDir, "update-ref", `refs/heads/${syncBranch}`, head);
+		return;
+	}
+	if (await git("-C", baseDir, "merge-base", "--is-ancestor", head, branchHead).then(() => true).catch(() => false)) return;
+	const backupBranch = `tbd-legacy-preserve-${nowFilenameTimestamp()}`;
+	await git("-C", baseDir, "branch", backupBranch, head);
+	throw new Error(`Legacy sync worktree at ${legacyPath} diverges from ${syncBranch}. Preserved its HEAD as ${backupBranch}; run 'tbd doctor --fix' after reviewing the backup branch.`);
+}
+/**
+* Preserve and remove f03 per-checkout sync worktrees before creating the shared worktree.
+*/
+async function migrateLegacyWorktreesToShared(baseDir, syncBranch = SYNC_BRANCH) {
+	const { sharedWorktreePath } = await getSharedPaths(baseDir);
+	const legacyPaths = await listLegacyWorktreePaths(baseDir, sharedWorktreePath);
+	let migrated = 0;
+	try {
+		for (const legacyPath of legacyPaths) {
+			await preserveLegacyWorktreeHead(baseDir, legacyPath, syncBranch);
+			try {
+				await git("-C", baseDir, "worktree", "remove", legacyPath, "--force");
+			} catch {
+				await rm(legacyPath, {
+					recursive: true,
+					force: true
+				});
+			}
+			migrated += 1;
+		}
+		if (legacyPaths.length > 0) await git("-C", baseDir, "worktree", "prune");
+		return {
+			success: true,
+			migrated
+		};
+	} catch (error) {
+		return {
+			success: false,
+			migrated,
+			error: error instanceof Error ? error.message : String(error)
+		};
+	}
+}
+/**
+* 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.
 *
+* MUST be called while holding `withSharedDataSyncLock` — it migrates legacy
+* per-checkout worktrees and creates the shared attached worktree on tbd-sync,
+* so concurrent callers can otherwise race branch ownership and migration.
+*
 * @param baseDir - The base directory of the repository
 * @param remote - The remote name (default: 'origin')
 * @param syncBranch - The sync branch name (default: 'tbd-sync')
 * @returns Path to the worktree or error message
 */
 async function initWorktree(baseDir, remote = "origin", syncBranch = SYNC_BRANCH) {
-	const worktreePath = join(baseDir, WORKTREE_DIR);
+	const paths = await getSharedPaths(baseDir);
+	const worktreePath = paths.sharedWorktreePath;
 	if (await worktreeExists(baseDir)) return {
 		success: true,
 		path: worktreePath,
 		created: false
 	};
+	await mkdir(paths.sharedTbdDir, { recursive: true });
+	const migrationResult = await migrateLegacyWorktreesToShared(baseDir, syncBranch);
+	if (!migrationResult.success) return {
+		success: false,
+		error: migrationResult.error
+	};
 	try {
 		await rm(worktreePath, {
 			recursive: true,
@@ -1490,7 +1872,7 @@ async function initWorktree(baseDir, remote = "origin", syncBranch = SYNC_BRANCH
 		});
 	} catch {}
 	try {
-		if (await branchExists(syncBranch)) {
+		if (await branchExists(syncBranch, baseDir)) {
 			await git("-C", baseDir, "worktree", "add", worktreePath, syncBranch);
 			return {
 				success: true,
@@ -1498,7 +1880,13 @@ async function initWorktree(baseDir, remote = "origin", syncBranch = SYNC_BRANCH
 				created: true
 			};
 		}
-		if (await remoteBranchExists(remote, syncBranch)) {
+		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 {
@@ -1513,12 +1901,13 @@ async function initWorktree(baseDir, remote = "origin", syncBranch = SYNC_BRANCH
 		await mkdir(join(dataSyncPath, "issues"), { recursive: true });
 		await mkdir(join(dataSyncPath, "mappings"), { recursive: true });
 		await mkdir(join(dataSyncPath, "attic", "conflicts"), { recursive: true });
-		await writeFile(join(dataSyncPath, "meta.yml"), "schema_version: 1\n");
+		await writeFile(join(dataSyncPath, "meta.yml"), `schema_version: ${DATA_SYNC_SCHEMA_VERSION}\n`);
 		await writeFile(join(dataSyncPath, "issues", ".gitkeep"), "");
 		await writeFile(join(dataSyncPath, "mappings", ".gitkeep"), "");
 		await writeFile(join(dataSyncPath, "mappings", ".gitattributes"), "ids.yml merge=union\n");
 		await git("-C", worktreePath, "add", ".");
-		await git("-C", worktreePath, "commit", "--no-verify", "-m", "Initialize tbd-sync branch");
+		await gitCommit(worktreePath, "--no-verify", "-m", "Initialize tbd-sync branch");
+		if (hasRemote) await pushFreshOrphan(baseDir, worktreePath, remote, syncBranch, dataSyncPath);
 		return {
 			success: true,
 			path: worktreePath,
@@ -1538,16 +1927,17 @@ async function initWorktree(baseDir, remote = "origin", syncBranch = SYNC_BRANCH
 * @param syncBranch - The sync branch name (default: 'tbd-sync')
 * @returns Health status indicating if branch exists and has commits
 */
-async function checkLocalBranchHealth(syncBranch = SYNC_BRANCH) {
+async function checkLocalBranchHealth(syncBranch = SYNC_BRANCH, baseDir) {
+	const dirArgs = baseDir ? ["-C", baseDir] : [];
 	try {
 		return {
 			exists: true,
 			orphaned: false,
-			head: (await git("rev-parse", `refs/heads/${syncBranch}`)).trim()
+			head: (await git(...dirArgs, "rev-parse", `refs/heads/${syncBranch}`)).trim()
 		};
 	} catch {
 		try {
-			await git("show-ref", "--verify", `refs/heads/${syncBranch}`);
+			await git(...dirArgs, "show-ref", "--verify", `refs/heads/${syncBranch}`);
 			return {
 				exists: true,
 				orphaned: true
@@ -1568,27 +1958,36 @@ async function checkLocalBranchHealth(syncBranch = SYNC_BRANCH) {
 * @param syncBranch - The sync branch name (default: 'tbd-sync')
 * @returns Health status indicating if remote branch exists and divergence state
 */
-async function checkRemoteBranchHealth(remote = "origin", syncBranch = SYNC_BRANCH) {
+async function checkRemoteBranchHealth(remote = "origin", syncBranch = SYNC_BRANCH, baseDir) {
+	const dirArgs = baseDir ? ["-C", baseDir] : [];
 	try {
-		await git("fetch", remote, syncBranch);
-		const remoteHead = (await git("rev-parse", `refs/remotes/${remote}/${syncBranch}`)).trim();
+		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("merge-base", syncBranch, `${remote}/${syncBranch}`);
-			const localHead = await git("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
 		};
 	}
 }
@@ -1602,7 +2001,8 @@ async function checkRemoteBranchHealth(remote = "origin", syncBranch = SYNC_BRAN
 * @returns Consistency status with HEAD comparisons and ahead/behind counts
 */
 async function checkSyncConsistency(baseDir, syncBranch = SYNC_BRANCH, remote = "origin") {
-	const worktreeHead = await git("-C", join(baseDir, WORKTREE_DIR), "rev-parse", "HEAD").catch(() => "");
+	const { sharedWorktreePath: worktreePath } = await getSharedPaths(baseDir);
+	const worktreeHead = await git("-C", worktreePath, "rev-parse", "HEAD").catch(() => "");
 	const localHead = await git("-C", baseDir, "rev-parse", syncBranch).catch(() => "");
 	const remoteHead = await git("-C", baseDir, "rev-parse", `${remote}/${syncBranch}`).catch(() => "");
 	let localAhead = 0;
@@ -1626,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.
@@ -1634,10 +2116,12 @@ async function checkSyncConsistency(baseDir, syncBranch = SYNC_BRANCH, remote =
 * @param syncBranch - The sync branch name (default: 'tbd-sync')
 * @returns Number of issue files on the remote branch, or null if branch doesn't exist
 */
-async function countRemoteIssues(remote = "origin", syncBranch = SYNC_BRANCH) {
+async function countRemoteIssues(remote = "origin", syncBranch = SYNC_BRANCH, baseDir) {
+	const dirArgs = baseDir ? ["-C", baseDir] : [];
 	try {
-		await git("fetch", remote, syncBranch);
-		const output = await git("ls-tree", "-r", "--name-only", `${remote}/${syncBranch}`);
+		await git(...dirArgs, "fetch", remote, syncBranch);
+		const remoteBranch = `${remote}/${syncBranch}`;
+		const output = await git(...dirArgs, "ls-tree", "-r", "--name-only", remoteBranch);
 		const issuesDir = `${TBD_DIR}/${DATA_SYNC_DIR_NAME}/issues/`;
 		return output.split("\n").filter(Boolean).filter((line) => line.startsWith(issuesDir) && line.endsWith(".md")).length;
 	} catch {
@@ -1652,6 +2136,10 @@ async function countRemoteIssues(remote = "origin", syncBranch = SYNC_BRANCH) {
 * - CORRUPTED: backup to .tbd/backups/, remove, then recreate
 * - MISSING: just create
 *
+* MUST be called while holding `withSharedDataSyncLock` — repair mutates
+* shared worktree and branch state and shares the same locking contract as
+* `initWorktree`.
+*
 * See: plan-2026-01-28-sync-worktree-recovery-and-hardening.md
 *
 * @param baseDir - The base directory of the repository
@@ -1660,13 +2148,12 @@ async function countRemoteIssues(remote = "origin", syncBranch = SYNC_BRANCH) {
 * @param syncBranch - The sync branch name (default: 'tbd-sync')
 */
 async function repairWorktree(baseDir, status, remote = "origin", syncBranch = SYNC_BRANCH) {
-	const worktreePath = join(baseDir, WORKTREE_DIR);
+	const { sharedWorktreePath: worktreePath, sharedBackupsDir } = await getSharedPaths(baseDir);
 	try {
 		if (status === "missing" || status === "prunable") await git("-C", baseDir, "worktree", "prune");
 		if (status === "corrupted") {
-			const backupsDir = join(baseDir, TBD_DIR, "backups");
-			await mkdir(backupsDir, { recursive: true });
-			const backupPath = join(backupsDir, `corrupted-worktree-backup-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, 19)}`);
+			await mkdir(sharedBackupsDir, { recursive: true });
+			const backupPath = join(sharedBackupsDir, `corrupted-worktree-backup-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, 19)}`);
 			try {
 				await cp(worktreePath, backupPath, { recursive: true });
 			} catch {}
@@ -1697,9 +2184,15 @@ async function repairWorktree(baseDir, status, remote = "origin", syncBranch = S
 * @returns true if worktree was detached and repaired, false if already attached
 */
 async function ensureWorktreeAttached(worktreePath) {
+	return ensureWorktreeAttachedToBranch(worktreePath, SYNC_BRANCH);
+}
+/**
+* Ensure worktree is attached to the requested sync branch, not detached HEAD.
+*/
+async function ensureWorktreeAttachedToBranch(worktreePath, syncBranch = SYNC_BRANCH) {
 	try {
-		if (!await git("-C", worktreePath, "branch", "--show-current").catch(() => "")) {
-			await git("-C", worktreePath, "checkout", SYNC_BRANCH);
+		if (await git("-C", worktreePath, "branch", "--show-current").catch(() => "") !== syncBranch) {
+			await git("-C", worktreePath, "checkout", syncBranch);
 			return true;
 		}
 		return false;
@@ -1725,28 +2218,23 @@ async function ensureWorktreeAttached(worktreePath) {
 */
 async function migrateDataToWorktree(baseDir, removeSource = false) {
 	const wrongPath = join(baseDir, TBD_DIR, DATA_SYNC_DIR_NAME);
-	const correctPath = join(baseDir, WORKTREE_DIR, TBD_DIR, DATA_SYNC_DIR_NAME);
-	const worktreePath = join(baseDir, WORKTREE_DIR);
+	const { sharedDataSyncDir: correctPath, sharedWorktreePath: worktreePath, sharedBackupsDir } = await getSharedPaths(baseDir);
 	try {
 		await ensureWorktreeAttached(worktreePath);
 		const wrongIssuesPath = join(wrongPath, "issues");
 		const wrongMappingsPath = join(wrongPath, "mappings");
 		let issueFiles = [];
 		let mappingFiles = [];
-		try {
-			const { readdir } = await import("node:fs/promises");
-			issueFiles = await readdir(wrongIssuesPath).catch(() => []);
-			mappingFiles = await readdir(wrongMappingsPath).catch(() => []);
-		} catch {}
+		issueFiles = await readdir(wrongIssuesPath).catch(() => []);
+		mappingFiles = await readdir(wrongMappingsPath).catch(() => []);
 		issueFiles = issueFiles.filter((f) => f !== ".gitkeep");
 		mappingFiles = mappingFiles.filter((f) => f !== ".gitkeep");
 		if (issueFiles.length === 0 && mappingFiles.length === 0) return {
 			success: true,
 			migratedCount: 0
 		};
-		const backupsDir = join(baseDir, TBD_DIR, "backups");
-		await mkdir(backupsDir, { recursive: true });
-		const backupPath = join(backupsDir, `data-sync-backup-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, 19)}`);
+		await mkdir(sharedBackupsDir, { recursive: true });
+		const backupPath = join(sharedBackupsDir, `data-sync-backup-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, 19)}`);
 		await cp(wrongPath, backupPath, { recursive: true });
 		const correctIssuesPath = join(correctPath, "issues");
 		const correctMappingsPath = join(correctPath, "mappings");
@@ -1754,8 +2242,6 @@ async function migrateDataToWorktree(baseDir, removeSource = false) {
 		await mkdir(correctMappingsPath, { recursive: true });
 		for (const file of issueFiles) await cp(join(wrongIssuesPath, file), join(correctIssuesPath, file));
 		for (const file of mappingFiles) if (file === "ids.yml") {
-			const { readFile } = await import("node:fs/promises");
-			const { loadIdMapping, mergeIdMappings, saveIdMapping, resolveIdMappingConflicts } = await import("./id-mapping-Ctfl_nc1.mjs");
 			const sourceMapping = resolveIdMappingConflicts(await readFile(join(wrongMappingsPath, file), "utf-8"));
 			let targetMapping;
 			try {
@@ -1767,7 +2253,7 @@ async function migrateDataToWorktree(baseDir, removeSource = false) {
 		} else await cp(join(wrongMappingsPath, file), join(correctMappingsPath, file));
 		const totalFiles = issueFiles.length + mappingFiles.length;
 		await git("-C", worktreePath, "add", "-A");
-		if (await git("-C", worktreePath, "diff", "--cached", "--quiet").then(() => false).catch(() => true)) await git("-C", worktreePath, "commit", "--no-verify", "-m", `tbd: migrate ${totalFiles} file(s) from incorrect location`);
+		if (await git("-C", worktreePath, "diff", "--cached", "--quiet").then(() => false).catch(() => true)) await gitCommit(worktreePath, "--no-verify", "-m", `tbd: migrate ${totalFiles} file(s) from incorrect location`);
 		if (removeSource) {
 			for (const file of issueFiles) await rm(join(wrongIssuesPath, file));
 			for (const file of mappingFiles) await rm(join(wrongMappingsPath, file));
@@ -1786,6 +2272,83 @@ async function migrateDataToWorktree(baseDir, removeSource = false) {
 	}
 }
 
+//#endregion
+//#region src/file/common-dir-layout.ts
+/**
+* Git common-dir layout metadata for shared issue sync machinery.
+*/
+/**
+* Error thrown when common-dir layout metadata cannot be used safely.
+*/
+var CommonDirLayoutError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "CommonDirLayoutError";
+	}
+};
+/**
+* Read $GIT_COMMON_DIR/tbd/layout.yml, returning null when it has not been created yet.
+*/
+async function readCommonDirLayout(layoutPath) {
+	try {
+		const content = await readFile(layoutPath, "utf-8");
+		return CommonDirLayoutSchema.parse(parse(content));
+	} catch (error) {
+		if (error.code === "ENOENT") return null;
+		throw new CommonDirLayoutError(`Invalid tbd common-dir layout metadata at ${layoutPath}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+/**
+* Validate that common-dir layout metadata matches the checkout config.
+*/
+function validateCommonDirLayout(layout, config) {
+	if (!isCompatibleFormat(layout.tbd_format)) throw new CommonDirLayoutError(formatUpgradeMessage("Common-dir layout", layout.tbd_format, CURRENT_FORMAT));
+	if (layout.tbd_format !== config.tbd_format) throw new CommonDirLayoutError(`Common-dir layout format '${layout.tbd_format}' does not match config format '${config.tbd_format}'. This indicates a partial migration or manual edit. Run 'tbd doctor --fix' to rewrite the layout from the current config. (Manual fallback: rm "$(git rev-parse --git-common-dir)/tbd/layout.yml".)`);
+	const layoutStorage = layout.sync_storage;
+	const configStorage = config.sync.storage;
+	if (layoutStorage !== configStorage) throw new CommonDirLayoutError(`Common-dir sync storage '${layoutStorage}' does not match config storage '${configStorage}'. This indicates a partial migration or manual edit. Run 'tbd doctor --fix' to rewrite the layout from the current config. (Manual fallback: rm "$(git rev-parse --git-common-dir)/tbd/layout.yml".)`);
+}
+/**
+* Write common-dir layout metadata using the synchronized tbd_format ID.
+*/
+async function writeCommonDirLayout(paths, config, existing) {
+	await mkdir(dirname(paths.sharedLayoutPath), { recursive: true });
+	const timestamp = now();
+	const layout = CommonDirLayoutSchema.parse({
+		tbd_format: config.tbd_format,
+		sync_storage: config.sync.storage,
+		data_sync_worktree: "data-sync-worktree",
+		lock_profile: "data-sync-v1",
+		created_at: existing?.created_at ?? timestamp,
+		updated_at: timestamp
+	});
+	const yaml = stringifyYaml(sortKeys(layout, COMMON_DIR_LAYOUT_FIELD_ORDER), {
+		lineWidth: 0,
+		sortMapEntries: false
+	});
+	await writeFile(paths.sharedLayoutPath, yaml);
+	return layout;
+}
+/**
+* Ensure layout metadata exists and matches the checkout config.
+*/
+async function ensureCommonDirLayout(paths, config) {
+	const existing = await readCommonDirLayout(paths.sharedLayoutPath);
+	if (existing) {
+		validateCommonDirLayout(existing, config);
+		return existing;
+	}
+	return writeCommonDirLayout(paths, config);
+}
+/**
+* Run a critical section while holding the repo-scoped data-sync lock.
+*/
+async function withSharedDataSyncLock(tbdRoot, fn) {
+	const paths = await resolveSharedTbdPaths(tbdRoot);
+	await mkdir(paths.sharedLocksDir, { recursive: true });
+	return withLockfile(paths.sharedLockPath, fn, DATA_SYNC_LOCK_OPTIONS);
+}
+
 //#endregion
 //#region src/cli/commands/init.ts
 /**
@@ -1816,7 +2379,7 @@ Example:
   tbd init --prefix=${prefix} --force`);
 		if (this.checkDryRun("Would initialize tbd repository", options)) return;
 		await this.execute(async () => {
-			await initConfig(cwd, VERSION, options.prefix);
+			const config = await initConfig(cwd, VERSION, options.prefix);
 			this.output.debug(`Created ${TBD_DIR}/config.yml with prefix '${options.prefix}'`);
 			await ensureGitignorePatterns(join(cwd, TBD_DIR, ".gitignore"), [
 				"# Installed documentation (regenerated on setup)",
@@ -1854,152 +2417,43 @@ Example:
 				if (!supported) throw new CLIError(`Git ${`${version.major}.${version.minor}.${version.patch}`} detected. Git ${MIN_GIT_VERSION}+ is required for tbd.\n\ntbd requires Git 2.42+ for orphan worktree support.\nPlease upgrade Git: https://git-scm.com/downloads`);
 				this.output.debug(`Git version ${version.major}.${version.minor}.${version.patch} OK`);
 			} catch (error) {
-				if (error instanceof CLIError) throw error;
-				this.output.debug(`Git version check skipped: ${error.message}`);
-			}
-			const worktreeResult = await initWorktree(cwd, remote, syncBranch);
-			if (worktreeResult.success) {
-				if (worktreeResult.created) this.output.debug(`Created hidden worktree at ${TBD_DIR}/${WORKTREE_DIR_NAME}/`);
-				else this.output.debug(`Worktree already exists at ${TBD_DIR}/${WORKTREE_DIR_NAME}/`);
-				const health = await checkWorktreeHealth(cwd);
-				if (!health.valid) this.output.warn(`Worktree created but failed verification (status: ${health.status}). Run 'tbd doctor' to diagnose.`);
-			} else this.output.debug(`Note: Worktree not created (${worktreeResult.error})`);
-		}, "Failed to initialize tbd");
-		this.output.data({
-			initialized: true,
-			version: VERSION,
-			prefix: options.prefix
-		}, () => {
-			this.output.success(`Initialized tbd repository (prefix: ${options.prefix})`);
-			if (!this.output.isQuiet()) {
-				console.log("");
-				console.log("Next steps:");
-				console.log("  git add .tbd/ && git commit -m \"Initialize tbd\"");
-				console.log("  tbd setup --auto   # Optional: configure agent integrations");
-			}
-		});
-	}
-};
-const initCommand = new Command("init").description("Initialize tbd in a git repository").option("--prefix <name>", "Project prefix for display IDs (2-8 alphabetic recommended)").option("--force", "Allow non-recommended prefix format").option("--sync-branch <name>", "Sync branch name (default: tbd-sync)").option("--remote <name>", "Remote name (default: origin)").action(async (options, command) => {
-	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 hidden worktree at .tbd/data-sync/issues/.
-*
-* 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);
+				if (error instanceof CLIError) throw error;
+				this.output.debug(`Git version check skipped: ${error.message}`);
 			}
-		}
+			const { worktreeResult, sharedPaths } = await withSharedDataSyncLock(cwd, async () => {
+				const result = await initWorktree(cwd, remote, syncBranch);
+				const paths = await resolveSharedTbdPaths(cwd);
+				if (result.success) await writeCommonDirLayout(paths, config);
+				return {
+					worktreeResult: result,
+					sharedPaths: paths
+				};
+			});
+			if (worktreeResult.success) {
+				if (worktreeResult.created) this.output.debug(`Created hidden worktree at ${sharedPaths.sharedWorktreePath}`);
+				else this.output.debug(`Worktree already exists at ${sharedPaths.sharedWorktreePath}`);
+				const health = await checkWorktreeHealth(cwd, syncBranch);
+				if (!health.valid) this.output.warn(`Worktree created but failed verification (status: ${health.status}). Run 'tbd doctor' to diagnose.`);
+			} else this.output.debug(`Note: Worktree not created (${worktreeResult.error})`);
+		}, "Failed to initialize tbd");
+		this.output.data({
+			initialized: true,
+			version: VERSION,
+			prefix: options.prefix
+		}, () => {
+			this.output.success(`Initialized tbd repository (prefix: ${options.prefix})`);
+			if (!this.output.isQuiet()) {
+				console.log("");
+				console.log("Next steps:");
+				console.log("  git add .tbd/ && git commit -m \"Initialize tbd\"");
+				console.log("  tbd setup --auto   # Optional: configure agent integrations");
+			}
+		});
 	}
-	return issues;
-}
-function reportInvalidIssueFile(invalidIssue, warnOnInvalid, onInvalidIssue) {
-	onInvalidIssue?.(invalidIssue);
-	if (warnOnInvalid) console.warn(`Skipping invalid issue file: ${invalidIssue.file}: ${invalidIssue.reason}`);
-}
+};
+const initCommand = new Command("init").description("Initialize tbd in a git repository").option("--prefix <name>", "Project prefix for display IDs (2-8 alphabetic recommended)").option("--force", "Allow non-recommended prefix format").option("--sync-branch <name>", "Sync branch name (default: tbd-sync)").option("--remote <name>", "Remote name (default: origin)").action(async (options, command) => {
+	await new InitHandler(command).run(options);
+});
 
 //#endregion
 //#region src/lib/priority.ts
@@ -2208,6 +2662,152 @@ function validateIssueTitle(title, options) {
 	return title;
 }
 
+//#endregion
+//#region src/cli/lib/data-context.ts
+async function probeDataSyncReadiness(tbdRoot) {
+	const { config, migrated, fromFormat } = await readConfigWithMigration(tbdRoot);
+	const sharedPaths = await resolveSharedTbdPaths(tbdRoot);
+	const layout = await readCommonDirLayout(sharedPaths.sharedLayoutPath);
+	if (layout) validateCommonDirLayout(layout, config);
+	const health = await checkWorktreeHealth(tbdRoot, config.sync.branch);
+	return {
+		config,
+		migrated,
+		fromFormat,
+		sharedPaths,
+		layout,
+		health,
+		ready: !migrated && layout !== null && health.valid
+	};
+}
+/**
+* Apply any pending first-use initialization, migration, or repair to the shared
+* data-sync layout. MUST be called while holding `withSharedDataSyncLock` so that
+* worktree repair, layout writes, and migrated-config writes are serialized.
+*/
+async function ensureSharedDataSyncLayout(tbdRoot, probe) {
+	let repairedWorktreeStatus;
+	if (!probe.health.valid) if (probe.health.status === "missing" || probe.health.status === "prunable") {
+		const repairResult = await repairWorktree(tbdRoot, probe.health.status, probe.config.sync.remote, probe.config.sync.branch);
+		if (!repairResult.success) throw new Error(`Failed to initialize shared data-sync worktree: ${repairResult.error}`);
+		repairedWorktreeStatus = probe.health.status;
+	} else throw new Error(`Shared data-sync worktree is ${probe.health.status}: ${probe.health.error ?? "unknown error"}. Run 'tbd doctor --fix' to repair.`);
+	await ensureCommonDirLayout(probe.sharedPaths, probe.config);
+	if (probe.migrated) {
+		await writeConfig(tbdRoot, probe.config);
+		notifyConfigMigrated(probe.fromFormat, CURRENT_FORMAT);
+	}
+	return repairedWorktreeStatus;
+}
+/**
+* Emit a one-time stderr notice when this checkout's `.tbd/config.yml` was migrated
+* (typically `fXX → fYY`). The config bump is the "publish" step of the format
+* migration and lands as a tracked diff on the current branch; users on a sibling
+* worktree (and even on main) deserve to know that without having to discover the
+* diff themselves later.
+*
+* See: docs/tbd-format-versioning.md (internal contributor guide) and
+* plan-2026-05-17-shared-common-dir-sync-worktree.md.
+*/
+function notifyConfigMigrated(fromFormat, toFormat) {
+	if (fromFormat === toFormat) return;
+	const arrow = fromFormat ? `${fromFormat} → ${toFormat}` : `→ ${toFormat}`;
+	process.stderr.write(`• tbd_format ${arrow}: .tbd/config.yml updated in this checkout. Commit on this branch or merge main to publish the format upgrade.\n`);
+}
+async function assembleDataContext(tbdRoot, probe, repairedWorktreeStatus) {
+	const dataSyncDir = await resolveDataSyncDir(tbdRoot, { allowFallback: false });
+	return {
+		dataSyncDir,
+		mapping: await loadIdMapping(dataSyncDir),
+		config: probe.config,
+		prefix: probe.config.display.id_prefix,
+		sharedPaths: probe.sharedPaths,
+		repairedWorktreeStatus
+	};
+}
+/**
+* Load all common data context needed by tbd commands.
+*
+* For writers this is called inside `withSharedDataSyncLock` by
+* `withDataSyncContext({ lock: true }, ...)`, so any ensure/migrate/repair work
+* is serialized.
+*/
+async function prepareDataSyncContext(tbdRoot) {
+	const probe = await probeDataSyncReadiness(tbdRoot);
+	return assembleDataContext(tbdRoot, probe, probe.ready ? void 0 : await ensureSharedDataSyncLayout(tbdRoot, probe));
+}
+/**
+* Prepare shared data-sync context, optionally holding the repo-scoped lock.
+*
+* - `{ lock: true }` (writers): always acquire the lock, then prepare under it.
+* - `{ lock: false }` (readers): probe first; only acquire the lock if first-use
+*   init/migrate/repair is actually required. Steady-state reads take no lock.
+*/
+async function withDataSyncContext(tbdRoot, options, fn) {
+	if (options.lock) return withSharedDataSyncLock(tbdRoot, async () => fn(await prepareDataSyncContext(tbdRoot)));
+	const probe = await probeDataSyncReadiness(tbdRoot);
+	if (probe.ready) return fn(await assembleDataContext(tbdRoot, probe));
+	return withSharedDataSyncLock(tbdRoot, async () => {
+		const reProbe = await probeDataSyncReadiness(tbdRoot);
+		return fn(await assembleDataContext(tbdRoot, reProbe, reProbe.ready ? void 0 : await ensureSharedDataSyncLayout(tbdRoot, reProbe)));
+	});
+}
+/**
+* Load the shared data-sync context for a read-only command.
+*
+* Read commands skip the shared lock when the layout and worktree are already
+* valid and the on-disk config needs no migration. When first-use
+* init/migrate/repair IS required, the underlying `withDataSyncContext` takes
+* the lock and runs the ensure path so concurrent readers cannot race
+* migration or worktree repair.
+*/
+async function loadDataContext(tbdRoot) {
+	return withDataSyncContext(tbdRoot, { lock: false }, async (context) => context);
+}
+/**
+* Load unified command context with CLI options, data, and helper methods.
+*
+* This is the recommended way to initialize command context. It:
+* 1. Checks that tbd is initialized (calls requireInit)
+* 2. Loads data context (dataSyncDir, mapping, config, prefix)
+* 3. Extracts CLI context from Commander
+* 4. Provides helper methods like displayId() and resolveId()
+*
+* Usage:
+* ```ts
+* class MyHandler extends BaseCommand {
+*   async run(id: string): Promise<void> {
+*     const ctx = await loadFullContext(this.command);
+*     const internalId = ctx.resolveId(id);
+*     const issue = await readIssue(ctx.dataSyncDir, internalId);
+*     console.log(ctx.displayId(issue.id));
+*   }
+* }
+* ```
+*
+* @param command - The Commander command instance
+* @throws Error if tbd is not initialized or resources fail to load
+*/
+async function loadFullContext(command) {
+	const tbdRoot = await requireInit();
+	const cli = getCommandContext(command);
+	const dataCtx = await loadDataContext(tbdRoot);
+	return {
+		...dataCtx,
+		cli,
+		displayId(internalId) {
+			return cli.debug ? formatDebugId(internalId, dataCtx.mapping, dataCtx.prefix) : formatDisplayId(internalId, dataCtx.mapping, dataCtx.prefix);
+		},
+		resolveId(inputId) {
+			try {
+				return resolveToInternalId(inputId, dataCtx.mapping);
+			} catch {
+				throw new NotFoundError("Issue", inputId);
+			}
+		}
+	};
+}
+
 //#endregion
 //#region src/cli/commands/create.ts
 /**
@@ -2252,52 +2852,52 @@ var CreateHandler = class extends BaseCommand {
 		let prefix;
 		let issue;
 		await this.execute(async () => {
-			const dataSyncDir = await resolveDataSyncDir(tbdRoot);
-			prefix = (await readConfig(tbdRoot)).display.id_prefix;
-			const mapping = await loadIdMapping(dataSyncDir);
-			shortId = generateUniqueShortId(mapping);
-			addIdMapping(mapping, ulid, shortId);
-			let parentId;
-			if (options.parent) try {
-				parentId = resolveToInternalId(options.parent, mapping);
-			} catch {
-				throw new ValidationError(`Invalid parent ID: ${options.parent}`);
-			}
-			if (!specPath && parentId) {
-				const parentIssue = await readIssue(dataSyncDir, parentId);
-				if (parentIssue.spec_path) specPath = parentIssue.spec_path;
-			}
-			issue = {
-				type: "is",
-				id,
-				version: 1,
-				title: validatedTitle,
-				kind,
-				status: "open",
-				priority,
-				labels: options.label ?? [],
-				dependencies: [],
-				created_at: timestamp,
-				updated_at: timestamp,
-				description: description ?? void 0,
-				assignee: options.assignee ?? void 0,
-				due_date: options.due ?? void 0,
-				deferred_until: options.defer ?? void 0,
-				parent_id: parentId,
-				spec_path: specPath
-			};
-			await writeIssue(dataSyncDir, issue);
-			await saveIdMapping(dataSyncDir, mapping);
-			if (parentId) try {
-				const parentIssue = await readIssue(dataSyncDir, parentId);
-				const hints = parentIssue.child_order_hints ?? [];
-				if (!hints.includes(id)) {
-					parentIssue.child_order_hints = [...hints, id];
-					parentIssue.version += 1;
-					parentIssue.updated_at = timestamp;
-					await writeIssue(dataSyncDir, parentIssue);
+			await withDataSyncContext(tbdRoot, { lock: true }, async ({ dataSyncDir, config, mapping }) => {
+				prefix = config.display.id_prefix;
+				shortId = generateUniqueShortId(mapping);
+				addIdMapping(mapping, ulid, shortId);
+				let parentId;
+				if (options.parent) try {
+					parentId = resolveToInternalId(options.parent, mapping);
+				} catch {
+					throw new ValidationError(`Invalid parent ID: ${options.parent}`);
 				}
-			} catch {}
+				if (!specPath && parentId) {
+					const parentIssue = await readIssue(dataSyncDir, parentId);
+					if (parentIssue.spec_path) specPath = parentIssue.spec_path;
+				}
+				issue = {
+					type: "is",
+					id,
+					version: 1,
+					title: validatedTitle,
+					kind,
+					status: "open",
+					priority,
+					labels: options.label ?? [],
+					dependencies: [],
+					created_at: timestamp,
+					updated_at: timestamp,
+					description: description ?? void 0,
+					assignee: options.assignee ?? void 0,
+					due_date: options.due ?? void 0,
+					deferred_until: options.defer ?? void 0,
+					parent_id: parentId,
+					spec_path: specPath
+				};
+				await writeIssue(dataSyncDir, issue);
+				await saveIdMapping(dataSyncDir, mapping);
+				if (parentId) try {
+					const parentIssue = await readIssue(dataSyncDir, parentId);
+					const hints = parentIssue.child_order_hints ?? [];
+					if (!hints.includes(id)) {
+						parentIssue.child_order_hints = [...hints, id];
+						parentIssue.version += 1;
+						parentIssue.updated_at = timestamp;
+						await writeIssue(dataSyncDir, parentIssue);
+					}
+				} catch {}
+			});
 		}, "Failed to create issue");
 		const displayId = `${prefix}-${shortId}`;
 		this.output.data({
@@ -2342,77 +2942,6 @@ function applyLimit(items, limitOption) {
 	return items.slice(0, limit);
 }
 
-//#endregion
-//#region src/cli/lib/data-context.ts
-/**
-* Load all common data context needed by tbd commands.
-*
-* This loads:
-* - dataSyncDir from resolveDataSyncDir()
-* - mapping from loadIdMapping()
-* - config from readConfig()
-* - prefix from config.display.id_prefix
-*
-* Call this once at the start of a command handler instead of
-* loading each piece separately.
-*
-* @param tbdRoot - The tbd repository root directory (from requireInit or findTbdRoot)
-* @throws Error if any of the resources fail to load
-*/
-async function loadDataContext(tbdRoot) {
-	const dataSyncDir = await resolveDataSyncDir(tbdRoot);
-	const [mapping, config] = await Promise.all([loadIdMapping(dataSyncDir), readConfig(tbdRoot)]);
-	return {
-		dataSyncDir,
-		mapping,
-		config,
-		prefix: config.display.id_prefix
-	};
-}
-/**
-* Load unified command context with CLI options, data, and helper methods.
-*
-* This is the recommended way to initialize command context. It:
-* 1. Checks that tbd is initialized (calls requireInit)
-* 2. Loads data context (dataSyncDir, mapping, config, prefix)
-* 3. Extracts CLI context from Commander
-* 4. Provides helper methods like displayId() and resolveId()
-*
-* Usage:
-* ```ts
-* class MyHandler extends BaseCommand {
-*   async run(id: string): Promise<void> {
-*     const ctx = await loadFullContext(this.command);
-*     const internalId = ctx.resolveId(id);
-*     const issue = await readIssue(ctx.dataSyncDir, internalId);
-*     console.log(ctx.displayId(issue.id));
-*   }
-* }
-* ```
-*
-* @param command - The Commander command instance
-* @throws Error if tbd is not initialized or resources fail to load
-*/
-async function loadFullContext(command) {
-	const tbdRoot = await requireInit();
-	const cli = getCommandContext(command);
-	const dataCtx = await loadDataContext(tbdRoot);
-	return {
-		...dataCtx,
-		cli,
-		displayId(internalId) {
-			return cli.debug ? formatDebugId(internalId, dataCtx.mapping, dataCtx.prefix) : formatDisplayId(internalId, dataCtx.mapping, dataCtx.prefix);
-		},
-		resolveId(inputId) {
-			try {
-				return resolveToInternalId(inputId, dataCtx.mapping);
-			} catch {
-				throw new NotFoundError("Issue", inputId);
-			}
-		}
-	};
-}
-
 //#endregion
 //#region src/lib/status.ts
 /**
@@ -3060,81 +3589,83 @@ const showCommand = new Command("show").description("Show issue details").argume
 var UpdateHandler = class extends BaseCommand {
 	async run(id, options) {
 		const tbdRoot = await requireInit();
-		const dataSyncDir = await resolveDataSyncDir(tbdRoot);
-		const mapping = await loadIdMapping(dataSyncDir);
-		let internalId;
-		try {
-			internalId = resolveToInternalId(id, mapping);
-		} catch {
-			throw new NotFoundError("Issue", id);
-		}
-		let issue;
-		try {
-			issue = await readIssue(dataSyncDir, internalId);
-		} catch {
-			throw new NotFoundError("Issue", id);
-		}
-		const updates = await this.parseUpdates(options, mapping, tbdRoot);
-		if (updates === null) return;
-		if (this.checkDryRun("Would update issue", {
-			id: internalId,
-			...updates
-		})) return;
-		const oldSpecPath = issue.spec_path;
-		if (updates.title !== void 0) issue.title = updates.title;
-		if (updates.status !== void 0) issue.status = updates.status;
-		if (updates.kind !== void 0) issue.kind = updates.kind;
-		if (updates.priority !== void 0) issue.priority = updates.priority;
-		if (updates.assignee !== void 0) issue.assignee = updates.assignee;
-		if (updates.description !== void 0) issue.description = updates.description;
-		if (updates.notes !== void 0) issue.notes = updates.notes;
-		if (updates.due_date !== void 0) issue.due_date = updates.due_date;
-		if (updates.deferred_until !== void 0) issue.deferred_until = updates.deferred_until;
-		if (updates.parent_id !== void 0) issue.parent_id = updates.parent_id;
-		if (updates.spec_path !== void 0) issue.spec_path = updates.spec_path;
-		if (updates.child_order_hints !== void 0) issue.child_order_hints = updates.child_order_hints;
-		if (updates.parent_id && options.spec === void 0 && !issue.spec_path) try {
-			const parentIssue = await readIssue(dataSyncDir, updates.parent_id);
-			if (parentIssue.spec_path) issue.spec_path = parentIssue.spec_path;
-		} catch {}
-		if (updates.labels !== void 0) issue.labels = updates.labels;
-		if (updates.addLabels && updates.addLabels.length > 0) {
-			const labelsSet = new Set(issue.labels);
-			for (const label of updates.addLabels) labelsSet.add(label);
-			issue.labels = [...labelsSet];
-		}
-		if (updates.removeLabels && updates.removeLabels.length > 0) {
-			const removeSet = new Set(updates.removeLabels);
-			issue.labels = issue.labels.filter((l) => !removeSet.has(l));
-		}
-		issue.version += 1;
-		issue.updated_at = now();
+		let displayId = id;
+		let didUpdate = false;
 		await this.execute(async () => {
-			await writeIssue(dataSyncDir, issue);
+			await withDataSyncContext(tbdRoot, { lock: true }, async ({ dataSyncDir, mapping, config }) => {
+				let internalId;
+				try {
+					internalId = resolveToInternalId(id, mapping);
+				} catch {
+					throw new NotFoundError("Issue", id);
+				}
+				let issue;
+				try {
+					issue = await readIssue(dataSyncDir, internalId);
+				} catch {
+					throw new NotFoundError("Issue", id);
+				}
+				const updates = await this.parseUpdates(options, mapping, tbdRoot);
+				if (updates === null) return;
+				if (this.checkDryRun("Would update issue", {
+					id: internalId,
+					...updates
+				})) return;
+				const oldSpecPath = issue.spec_path;
+				if (updates.title !== void 0) issue.title = updates.title;
+				if (updates.status !== void 0) issue.status = updates.status;
+				if (updates.kind !== void 0) issue.kind = updates.kind;
+				if (updates.priority !== void 0) issue.priority = updates.priority;
+				if (updates.assignee !== void 0) issue.assignee = updates.assignee;
+				if (updates.description !== void 0) issue.description = updates.description;
+				if (updates.notes !== void 0) issue.notes = updates.notes;
+				if (updates.due_date !== void 0) issue.due_date = updates.due_date;
+				if (updates.deferred_until !== void 0) issue.deferred_until = updates.deferred_until;
+				if (updates.parent_id !== void 0) issue.parent_id = updates.parent_id;
+				if (updates.spec_path !== void 0) issue.spec_path = updates.spec_path;
+				if (updates.child_order_hints !== void 0) issue.child_order_hints = updates.child_order_hints;
+				if (updates.parent_id && options.spec === void 0 && !issue.spec_path) try {
+					const parentIssue = await readIssue(dataSyncDir, updates.parent_id);
+					if (parentIssue.spec_path) issue.spec_path = parentIssue.spec_path;
+				} catch {}
+				if (updates.labels !== void 0) issue.labels = updates.labels;
+				if (updates.addLabels && updates.addLabels.length > 0) {
+					const labelsSet = new Set(issue.labels);
+					for (const label of updates.addLabels) labelsSet.add(label);
+					issue.labels = [...labelsSet];
+				}
+				if (updates.removeLabels && updates.removeLabels.length > 0) {
+					const removeSet = new Set(updates.removeLabels);
+					issue.labels = issue.labels.filter((l) => !removeSet.has(l));
+				}
+				issue.version += 1;
+				issue.updated_at = now();
+				await writeIssue(dataSyncDir, issue);
+				if (updates.parent_id) try {
+					const parentIssue = await readIssue(dataSyncDir, updates.parent_id);
+					const hints = parentIssue.child_order_hints ?? [];
+					if (!hints.includes(internalId)) {
+						parentIssue.child_order_hints = [...hints, internalId];
+						parentIssue.version += 1;
+						parentIssue.updated_at = now();
+						await writeIssue(dataSyncDir, parentIssue);
+					}
+				} catch {}
+				if (updates.spec_path !== void 0 && issue.spec_path && issue.spec_path !== oldSpecPath) {
+					const children = (await listIssues(dataSyncDir)).filter((i) => i.parent_id === issue.id);
+					const timestamp = now();
+					for (const child of children) if (!child.spec_path || child.spec_path === oldSpecPath) {
+						child.spec_path = issue.spec_path;
+						child.version += 1;
+						child.updated_at = timestamp;
+						await writeIssue(dataSyncDir, child);
+					}
+				}
+				displayId = this.ctx.debug ? formatDebugId(issue.id, mapping, config.display.id_prefix) : formatDisplayId(issue.id, mapping, config.display.id_prefix);
+				didUpdate = true;
+			});
 		}, "Failed to update issue");
-		if (updates.parent_id) try {
-			const parentIssue = await readIssue(dataSyncDir, updates.parent_id);
-			const hints = parentIssue.child_order_hints ?? [];
-			if (!hints.includes(internalId)) {
-				parentIssue.child_order_hints = [...hints, internalId];
-				parentIssue.version += 1;
-				parentIssue.updated_at = now();
-				await writeIssue(dataSyncDir, parentIssue);
-			}
-		} catch {}
-		if (updates.spec_path !== void 0 && issue.spec_path && issue.spec_path !== oldSpecPath) {
-			const children = (await listIssues(dataSyncDir)).filter((i) => i.parent_id === issue.id);
-			const timestamp = now();
-			for (const child of children) if (!child.spec_path || child.spec_path === oldSpecPath) {
-				child.spec_path = issue.spec_path;
-				child.version += 1;
-				child.updated_at = timestamp;
-				await writeIssue(dataSyncDir, child);
-			}
-		}
-		const showDebug = this.ctx.debug;
-		const prefix = (await readConfig(tbdRoot)).display.id_prefix;
-		const displayId = showDebug ? formatDebugId(issue.id, mapping, prefix) : formatDisplayId(issue.id, mapping, prefix);
+		if (!didUpdate) return;
 		this.output.data({
 			id: displayId,
 			updated: true
@@ -3262,48 +3793,47 @@ const updateCommand = new Command("update").description("Update an issue").argum
 var CloseHandler = class extends BaseCommand {
 	async run(id, options) {
 		const tbdRoot = await requireInit();
-		const dataSyncDir = await resolveDataSyncDir(tbdRoot);
-		const mapping = await loadIdMapping(dataSyncDir);
-		let internalId;
-		try {
-			internalId = resolveToInternalId(id, mapping);
-		} catch {
-			throw new NotFoundError("Issue", id);
-		}
-		let issue;
-		try {
-			issue = await readIssue(dataSyncDir, internalId);
-		} catch {
-			throw new NotFoundError("Issue", id);
-		}
-		const showDebug = this.ctx.debug;
-		const prefix = (await readConfig(tbdRoot)).display.id_prefix;
-		const displayId = showDebug ? formatDebugId(issue.id, mapping, prefix) : formatDisplayId(issue.id, mapping, prefix);
-		if (issue.status === "closed") {
-			this.output.data({
-				id: displayId,
-				closed: true,
-				alreadyClosed: true
-			}, () => {
-				this.output.success(`Closed ${displayId}`);
-			});
-			return;
-		}
-		if (this.checkDryRun("Would close issue", {
-			id: internalId,
-			reason: options.reason
-		})) return;
-		issue.status = "closed";
-		issue.closed_at = now();
-		issue.close_reason = options.reason ?? null;
-		issue.version += 1;
-		issue.updated_at = now();
+		let displayId = id;
+		let alreadyClosed = false;
+		let didClose = false;
 		await this.execute(async () => {
-			await writeIssue(dataSyncDir, issue);
+			await withDataSyncContext(tbdRoot, { lock: true }, async ({ dataSyncDir, mapping, config }) => {
+				let internalId;
+				try {
+					internalId = resolveToInternalId(id, mapping);
+				} catch {
+					throw new NotFoundError("Issue", id);
+				}
+				let issue;
+				try {
+					issue = await readIssue(dataSyncDir, internalId);
+				} catch {
+					throw new NotFoundError("Issue", id);
+				}
+				displayId = this.ctx.debug ? formatDebugId(issue.id, mapping, config.display.id_prefix) : formatDisplayId(issue.id, mapping, config.display.id_prefix);
+				if (issue.status === "closed") {
+					alreadyClosed = true;
+					didClose = true;
+					return;
+				}
+				if (this.checkDryRun("Would close issue", {
+					id: internalId,
+					reason: options.reason
+				})) return;
+				issue.status = "closed";
+				issue.closed_at = now();
+				issue.close_reason = options.reason ?? null;
+				issue.version += 1;
+				issue.updated_at = now();
+				await writeIssue(dataSyncDir, issue);
+				didClose = true;
+			});
 		}, "Failed to close issue");
+		if (!didClose) return;
 		this.output.data({
 			id: displayId,
-			closed: true
+			closed: true,
+			alreadyClosed
 		}, () => {
 			this.output.success(`Closed ${displayId}`);
 		});
@@ -3323,40 +3853,42 @@ const closeCommand = new Command("close").description("Close an issue").argument
 var ReopenHandler = class extends BaseCommand {
 	async run(id, options) {
 		const tbdRoot = await requireInit();
-		const dataSyncDir = await resolveDataSyncDir(tbdRoot);
-		const mapping = await loadIdMapping(dataSyncDir);
-		let internalId;
-		try {
-			internalId = resolveToInternalId(id, mapping);
-		} catch {
-			throw new NotFoundError("Issue", id);
-		}
-		let issue;
-		try {
-			issue = await readIssue(dataSyncDir, internalId);
-		} catch {
-			throw new NotFoundError("Issue", id);
-		}
-		if (issue.status !== "closed") throw new CLIError(`Issue ${id} is not closed (status: ${issue.status})`);
-		if (this.checkDryRun("Would reopen issue", {
-			id: internalId,
-			reason: options.reason
-		})) return;
-		issue.status = "open";
-		issue.closed_at = null;
-		issue.close_reason = null;
-		issue.version += 1;
-		issue.updated_at = now();
-		if (options.reason) {
-			const reopenNote = `Reopened: ${options.reason}`;
-			issue.notes = issue.notes ? `${issue.notes}\n\n${reopenNote}` : reopenNote;
-		}
+		let displayId = id;
+		let didReopen = false;
 		await this.execute(async () => {
-			await writeIssue(dataSyncDir, issue);
+			await withDataSyncContext(tbdRoot, { lock: true }, async ({ dataSyncDir, mapping, config }) => {
+				let internalId;
+				try {
+					internalId = resolveToInternalId(id, mapping);
+				} catch {
+					throw new NotFoundError("Issue", id);
+				}
+				let issue;
+				try {
+					issue = await readIssue(dataSyncDir, internalId);
+				} catch {
+					throw new NotFoundError("Issue", id);
+				}
+				if (issue.status !== "closed") throw new CLIError(`Issue ${id} is not closed (status: ${issue.status})`);
+				if (this.checkDryRun("Would reopen issue", {
+					id: internalId,
+					reason: options.reason
+				})) return;
+				issue.status = "open";
+				issue.closed_at = null;
+				issue.close_reason = null;
+				issue.version += 1;
+				issue.updated_at = now();
+				if (options.reason) {
+					const reopenNote = `Reopened: ${options.reason}`;
+					issue.notes = issue.notes ? `${issue.notes}\n\n${reopenNote}` : reopenNote;
+				}
+				await writeIssue(dataSyncDir, issue);
+				displayId = this.ctx.debug ? formatDebugId(issue.id, mapping, config.display.id_prefix) : formatDisplayId(issue.id, mapping, config.display.id_prefix);
+				didReopen = true;
+			});
 		}, "Failed to reopen issue");
-		const showDebug = this.ctx.debug;
-		const prefix = (await readConfig(tbdRoot)).display.id_prefix;
-		const displayId = showDebug ? formatDebugId(issue.id, mapping, prefix) : formatDisplayId(issue.id, mapping, prefix);
+		if (!didReopen) return;
 		this.output.data({
 			id: displayId,
 			reopened: true
@@ -3604,43 +4136,45 @@ const staleCommand = new Command("stale").description("List issues not updated r
 var LabelAddHandler = class extends BaseCommand {
 	async run(id, labels) {
 		const tbdRoot = await requireInit();
-		const dataSyncDir = await resolveDataSyncDir(tbdRoot);
-		const mapping = await loadIdMapping(dataSyncDir);
-		let internalId;
-		try {
-			internalId = resolveToInternalId(id, mapping);
-		} catch {
-			throw new NotFoundError("Issue", id);
-		}
-		let issue;
-		try {
-			issue = await readIssue(dataSyncDir, internalId);
-		} catch {
-			throw new NotFoundError("Issue", id);
-		}
-		if (this.checkDryRun("Would add labels", {
-			id: internalId,
-			labels
-		})) return;
-		const labelsSet = new Set(issue.labels);
-		let added = 0;
-		for (const label of labels) if (!labelsSet.has(label)) {
-			labelsSet.add(label);
-			added++;
-		}
-		if (added === 0) {
-			this.output.info("All labels already present");
-			return;
-		}
-		issue.labels = [...labelsSet];
-		issue.version += 1;
-		issue.updated_at = now();
+		let displayId = id;
+		let didAdd = false;
 		await this.execute(async () => {
-			await writeIssue(dataSyncDir, issue);
+			await withDataSyncContext(tbdRoot, { lock: true }, async ({ dataSyncDir, mapping, config }) => {
+				let internalId;
+				try {
+					internalId = resolveToInternalId(id, mapping);
+				} catch {
+					throw new NotFoundError("Issue", id);
+				}
+				let issue;
+				try {
+					issue = await readIssue(dataSyncDir, internalId);
+				} catch {
+					throw new NotFoundError("Issue", id);
+				}
+				if (this.checkDryRun("Would add labels", {
+					id: internalId,
+					labels
+				})) return;
+				const labelsSet = new Set(issue.labels);
+				let added = 0;
+				for (const label of labels) if (!labelsSet.has(label)) {
+					labelsSet.add(label);
+					added++;
+				}
+				if (added === 0) {
+					this.output.info("All labels already present");
+					return;
+				}
+				issue.labels = [...labelsSet];
+				issue.version += 1;
+				issue.updated_at = now();
+				await writeIssue(dataSyncDir, issue);
+				displayId = this.ctx.debug ? formatDebugId(issue.id, mapping, config.display.id_prefix) : formatDisplayId(issue.id, mapping, config.display.id_prefix);
+				didAdd = true;
+			});
 		}, "Failed to update issue");
-		const showDebug = this.ctx.debug;
-		const prefix = (await readConfig(tbdRoot)).display.id_prefix;
-		const displayId = showDebug ? formatDebugId(issue.id, mapping, prefix) : formatDisplayId(issue.id, mapping, prefix);
+		if (!didAdd) return;
 		this.output.data({
 			id: displayId,
 			addedLabels: labels
@@ -3652,39 +4186,41 @@ var LabelAddHandler = class extends BaseCommand {
 var LabelRemoveHandler = class extends BaseCommand {
 	async run(id, labels) {
 		const tbdRoot = await requireInit();
-		const dataSyncDir = await resolveDataSyncDir(tbdRoot);
-		const mapping = await loadIdMapping(dataSyncDir);
-		let internalId;
-		try {
-			internalId = resolveToInternalId(id, mapping);
-		} catch {
-			throw new NotFoundError("Issue", id);
-		}
-		let issue;
-		try {
-			issue = await readIssue(dataSyncDir, internalId);
-		} catch {
-			throw new NotFoundError("Issue", id);
-		}
-		if (this.checkDryRun("Would remove labels", {
-			id: internalId,
-			labels
-		})) return;
-		const removeSet = new Set(labels);
-		const originalCount = issue.labels.length;
-		issue.labels = issue.labels.filter((l) => !removeSet.has(l));
-		if (originalCount - issue.labels.length === 0) {
-			this.output.info("No matching labels found");
-			return;
-		}
-		issue.version += 1;
-		issue.updated_at = now();
+		let displayId = id;
+		let didRemove = false;
 		await this.execute(async () => {
-			await writeIssue(dataSyncDir, issue);
+			await withDataSyncContext(tbdRoot, { lock: true }, async ({ dataSyncDir, mapping, config }) => {
+				let internalId;
+				try {
+					internalId = resolveToInternalId(id, mapping);
+				} catch {
+					throw new NotFoundError("Issue", id);
+				}
+				let issue;
+				try {
+					issue = await readIssue(dataSyncDir, internalId);
+				} catch {
+					throw new NotFoundError("Issue", id);
+				}
+				if (this.checkDryRun("Would remove labels", {
+					id: internalId,
+					labels
+				})) return;
+				const removeSet = new Set(labels);
+				const originalCount = issue.labels.length;
+				issue.labels = issue.labels.filter((l) => !removeSet.has(l));
+				if (originalCount - issue.labels.length === 0) {
+					this.output.info("No matching labels found");
+					return;
+				}
+				issue.version += 1;
+				issue.updated_at = now();
+				await writeIssue(dataSyncDir, issue);
+				displayId = this.ctx.debug ? formatDebugId(issue.id, mapping, config.display.id_prefix) : formatDisplayId(issue.id, mapping, config.display.id_prefix);
+				didRemove = true;
+			});
 		}, "Failed to update issue");
-		const showDebug = this.ctx.debug;
-		const prefix = (await readConfig(tbdRoot)).display.id_prefix;
-		const displayId = showDebug ? formatDebugId(issue.id, mapping, prefix) : formatDisplayId(issue.id, mapping, prefix);
+		if (!didRemove) return;
 		this.output.data({
 			id: displayId,
 			removedLabels: labels
@@ -3695,7 +4231,7 @@ var LabelRemoveHandler = class extends BaseCommand {
 };
 var LabelListHandler = class extends BaseCommand {
 	async run() {
-		const dataSyncDir = await resolveDataSyncDir(await requireInit());
+		const { dataSyncDir } = await loadDataContext(await requireInit());
 		let issues;
 		try {
 			issues = await listIssues(dataSyncDir);
@@ -3743,53 +4279,56 @@ const labelCommand = new Command("label").description("Manage issue labels").add
 var DependsAddHandler = class extends BaseCommand {
 	async run(issueId, dependsOnId) {
 		const tbdRoot = await requireInit();
-		const dataSyncDir = await resolveDataSyncDir(tbdRoot);
-		const mapping = await loadIdMapping(dataSyncDir);
-		let internalIssueId;
-		let internalDependsOnId;
-		try {
-			internalIssueId = resolveToInternalId(issueId, mapping);
-		} catch {
-			throw new NotFoundError("Issue", issueId);
-		}
-		try {
-			internalDependsOnId = resolveToInternalId(dependsOnId, mapping);
-		} catch {
-			throw new NotFoundError("Issue", dependsOnId);
-		}
-		try {
-			await readIssue(dataSyncDir, internalIssueId);
-		} catch {
-			throw new NotFoundError("Issue", issueId);
-		}
-		let blockerIssue;
-		try {
-			blockerIssue = await readIssue(dataSyncDir, internalDependsOnId);
-		} catch {
-			throw new NotFoundError("Issue", dependsOnId);
-		}
-		if (internalIssueId === internalDependsOnId) throw new ValidationError("Issue cannot depend on itself");
-		if (this.checkDryRun("Would add dependency", {
-			issue: internalIssueId,
-			dependsOn: internalDependsOnId
-		})) return;
-		if (blockerIssue.dependencies.some((dep) => dep.type === "blocks" && dep.target === internalIssueId)) {
-			this.output.info("Dependency already exists");
-			return;
-		}
-		blockerIssue.dependencies.push({
-			type: "blocks",
-			target: internalIssueId
-		});
-		blockerIssue.version += 1;
-		blockerIssue.updated_at = now();
+		let displayIssueId = issueId;
+		let displayDependsOnId = dependsOnId;
+		let didAdd = false;
 		await this.execute(async () => {
-			await writeIssue(dataSyncDir, blockerIssue);
+			await withDataSyncContext(tbdRoot, { lock: true }, async ({ dataSyncDir, mapping, config }) => {
+				let internalIssueId;
+				let internalDependsOnId;
+				try {
+					internalIssueId = resolveToInternalId(issueId, mapping);
+				} catch {
+					throw new NotFoundError("Issue", issueId);
+				}
+				try {
+					internalDependsOnId = resolveToInternalId(dependsOnId, mapping);
+				} catch {
+					throw new NotFoundError("Issue", dependsOnId);
+				}
+				try {
+					await readIssue(dataSyncDir, internalIssueId);
+				} catch {
+					throw new NotFoundError("Issue", issueId);
+				}
+				let blockerIssue;
+				try {
+					blockerIssue = await readIssue(dataSyncDir, internalDependsOnId);
+				} catch {
+					throw new NotFoundError("Issue", dependsOnId);
+				}
+				if (internalIssueId === internalDependsOnId) throw new ValidationError("Issue cannot depend on itself");
+				if (this.checkDryRun("Would add dependency", {
+					issue: internalIssueId,
+					dependsOn: internalDependsOnId
+				})) return;
+				if (blockerIssue.dependencies.some((dep) => dep.type === "blocks" && dep.target === internalIssueId)) {
+					this.output.info("Dependency already exists");
+					return;
+				}
+				blockerIssue.dependencies.push({
+					type: "blocks",
+					target: internalIssueId
+				});
+				blockerIssue.version += 1;
+				blockerIssue.updated_at = now();
+				await writeIssue(dataSyncDir, blockerIssue);
+				displayIssueId = this.ctx.debug ? formatDebugId(internalIssueId, mapping, config.display.id_prefix) : formatDisplayId(internalIssueId, mapping, config.display.id_prefix);
+				displayDependsOnId = this.ctx.debug ? formatDebugId(internalDependsOnId, mapping, config.display.id_prefix) : formatDisplayId(internalDependsOnId, mapping, config.display.id_prefix);
+				didAdd = true;
+			});
 		}, "Failed to update issue");
-		const showDebug = this.ctx.debug;
-		const prefix = (await readConfig(tbdRoot)).display.id_prefix;
-		const displayIssueId = showDebug ? formatDebugId(internalIssueId, mapping, prefix) : formatDisplayId(internalIssueId, mapping, prefix);
-		const displayDependsOnId = showDebug ? formatDebugId(internalDependsOnId, mapping, prefix) : formatDisplayId(internalDependsOnId, mapping, prefix);
+		if (!didAdd) return;
 		this.output.data({
 			issue: displayIssueId,
 			dependsOn: displayDependsOnId
@@ -3801,45 +4340,48 @@ var DependsAddHandler = class extends BaseCommand {
 var DependsRemoveHandler = class extends BaseCommand {
 	async run(issueId, dependsOnId) {
 		const tbdRoot = await requireInit();
-		const dataSyncDir = await resolveDataSyncDir(tbdRoot);
-		const mapping = await loadIdMapping(dataSyncDir);
-		let internalIssueId;
-		let internalDependsOnId;
-		try {
-			internalIssueId = resolveToInternalId(issueId, mapping);
-		} catch {
-			throw new NotFoundError("Issue", issueId);
-		}
-		try {
-			internalDependsOnId = resolveToInternalId(dependsOnId, mapping);
-		} catch {
-			throw new NotFoundError("Issue", dependsOnId);
-		}
-		let blockerIssue;
-		try {
-			blockerIssue = await readIssue(dataSyncDir, internalDependsOnId);
-		} catch {
-			throw new NotFoundError("Issue", dependsOnId);
-		}
-		if (this.checkDryRun("Would remove dependency", {
-			issue: internalIssueId,
-			dependsOn: internalDependsOnId
-		})) return;
-		const initialLength = blockerIssue.dependencies.length;
-		blockerIssue.dependencies = blockerIssue.dependencies.filter((dep) => !(dep.type === "blocks" && dep.target === internalIssueId));
-		if (blockerIssue.dependencies.length === initialLength) {
-			this.output.info("Dependency not found");
-			return;
-		}
-		blockerIssue.version += 1;
-		blockerIssue.updated_at = now();
+		let displayIssueId = issueId;
+		let displayDependsOnId = dependsOnId;
+		let didRemove = false;
 		await this.execute(async () => {
-			await writeIssue(dataSyncDir, blockerIssue);
+			await withDataSyncContext(tbdRoot, { lock: true }, async ({ dataSyncDir, mapping, config }) => {
+				let internalIssueId;
+				let internalDependsOnId;
+				try {
+					internalIssueId = resolveToInternalId(issueId, mapping);
+				} catch {
+					throw new NotFoundError("Issue", issueId);
+				}
+				try {
+					internalDependsOnId = resolveToInternalId(dependsOnId, mapping);
+				} catch {
+					throw new NotFoundError("Issue", dependsOnId);
+				}
+				let blockerIssue;
+				try {
+					blockerIssue = await readIssue(dataSyncDir, internalDependsOnId);
+				} catch {
+					throw new NotFoundError("Issue", dependsOnId);
+				}
+				if (this.checkDryRun("Would remove dependency", {
+					issue: internalIssueId,
+					dependsOn: internalDependsOnId
+				})) return;
+				const initialLength = blockerIssue.dependencies.length;
+				blockerIssue.dependencies = blockerIssue.dependencies.filter((dep) => !(dep.type === "blocks" && dep.target === internalIssueId));
+				if (blockerIssue.dependencies.length === initialLength) {
+					this.output.info("Dependency not found");
+					return;
+				}
+				blockerIssue.version += 1;
+				blockerIssue.updated_at = now();
+				await writeIssue(dataSyncDir, blockerIssue);
+				displayIssueId = this.ctx.debug ? formatDebugId(internalIssueId, mapping, config.display.id_prefix) : formatDisplayId(internalIssueId, mapping, config.display.id_prefix);
+				displayDependsOnId = this.ctx.debug ? formatDebugId(internalDependsOnId, mapping, config.display.id_prefix) : formatDisplayId(internalDependsOnId, mapping, config.display.id_prefix);
+				didRemove = true;
+			});
 		}, "Failed to update issue");
-		const showDebug = this.ctx.debug;
-		const prefix = (await readConfig(tbdRoot)).display.id_prefix;
-		const displayIssueId = showDebug ? formatDebugId(internalIssueId, mapping, prefix) : formatDisplayId(internalIssueId, mapping, prefix);
-		const displayDependsOnId = showDebug ? formatDebugId(internalDependsOnId, mapping, prefix) : formatDisplayId(internalDependsOnId, mapping, prefix);
+		if (!didRemove) return;
 		this.output.data({
 			issue: displayIssueId,
 			removed: displayDependsOnId
@@ -3850,9 +4392,7 @@ var DependsRemoveHandler = class extends BaseCommand {
 };
 var DependsListHandler = class extends BaseCommand {
 	async run(id) {
-		const tbdRoot = await requireInit();
-		const dataSyncDir = await resolveDataSyncDir(tbdRoot);
-		const mapping = await loadIdMapping(dataSyncDir);
+		const { dataSyncDir, mapping, config } = await loadDataContext(await requireInit());
 		let internalId;
 		try {
 			internalId = resolveToInternalId(id, mapping);
@@ -3872,7 +4412,7 @@ var DependsListHandler = class extends BaseCommand {
 			allIssues = [];
 		}
 		const showDebug = this.ctx.debug;
-		const prefix = (await readConfig(tbdRoot)).display.id_prefix;
+		const prefix = config.display.id_prefix;
 		const deps = getDependencyDirections(issue, allIssues, (dependencyId) => showDebug ? formatDebugId(dependencyId, mapping, prefix) : formatDisplayId(dependencyId, mapping, prefix));
 		this.output.data(deps, () => {
 			const colors = this.output.getColors();
@@ -4896,6 +5436,8 @@ async function workspaceExists(tbdRoot, name) {
 var SyncHandler = class extends BaseCommand {
 	dataSyncDir = "";
 	tbdRoot = "";
+	worktreePath = "";
+	syncBranch = "";
 	async run(options) {
 		const tbdRoot = await requireInit();
 		this.tbdRoot = tbdRoot;
@@ -4908,42 +5450,28 @@ var SyncHandler = class extends BaseCommand {
 			await this.syncDocs(options.status);
 			if (!syncIssues) return;
 		}
-		let worktreeHealth = await checkWorktreeHealth(tbdRoot);
-		if (!worktreeHealth.valid) if (worktreeHealth.status === "missing") {
-			await this.doRepairWorktree(tbdRoot, "missing");
-			worktreeHealth = await checkWorktreeHealth(tbdRoot);
-			if (!worktreeHealth.valid) throw new WorktreeCorruptedError(`Failed to create worktree. Status: ${worktreeHealth.status}. Run 'tbd doctor' for diagnostics.`);
-		} else if (options.fix) {
-			await this.doRepairWorktree(tbdRoot, worktreeHealth.status);
-			worktreeHealth = await checkWorktreeHealth(tbdRoot);
-			if (!worktreeHealth.valid) throw new WorktreeCorruptedError(`Worktree repair failed. Status: ${worktreeHealth.status}. Run 'tbd doctor' for diagnostics.`);
-		} else {
-			if (worktreeHealth.status === "prunable") throw new WorktreeMissingError("Worktree directory was deleted but git still tracks it. Run 'tbd sync --fix' or 'tbd doctor --fix' to repair.");
-			if (worktreeHealth.status === "corrupted") throw new WorktreeCorruptedError(`Worktree is corrupted: ${worktreeHealth.error ?? "unknown error"}. Run 'tbd sync --fix' or 'tbd doctor --fix' to repair.`);
-		}
-		this.dataSyncDir = await resolveDataSyncDir(tbdRoot);
-		let config;
-		try {
-			config = await readConfig(tbdRoot);
-		} catch {
-			throw new NotInitializedError("Not a tbd repository. Run `tbd init` first.");
-		}
-		const syncBranch = config.sync.branch;
-		const remote = config.sync.remote;
-		if (options.status) {
-			await this.showIssueStatus(syncBranch, remote);
-			return;
-		}
-		if (this.checkDryRun("Would sync repository", {
-			syncBranch,
-			remote
-		})) return;
-		if (options.pull) await this.pullChanges(syncBranch, remote);
-		else if (options.push) await this.pushChanges(syncBranch, remote);
-		else await this.fullSync(syncBranch, remote, {
-			force: options.force,
-			autoSave: options.autoSave,
-			outbox: options.outbox
+		await withDataSyncContext(tbdRoot, { lock: true }, async ({ dataSyncDir, config, sharedPaths, repairedWorktreeStatus }) => {
+			this.dataSyncDir = dataSyncDir;
+			this.worktreePath = sharedPaths.sharedWorktreePath;
+			this.syncBranch = config.sync.branch;
+			const syncBranch = config.sync.branch;
+			const remote = config.sync.remote;
+			if (options.status) {
+				await this.showIssueStatus(syncBranch, remote);
+				return;
+			}
+			if (this.checkDryRun("Would sync repository", {
+				syncBranch,
+				remote
+			})) return;
+			if (repairedWorktreeStatus) this.output.success("Worktree repaired successfully");
+			if (options.pull) await this.pullChanges(syncBranch, remote);
+			else if (options.push) await this.pushChanges(syncBranch, remote);
+			else await this.fullSync(syncBranch, remote, {
+				force: options.force,
+				autoSave: options.autoSave,
+				outbox: options.outbox
+			});
 		});
 	}
 	/**
@@ -4993,24 +5521,6 @@ var SyncHandler = class extends BaseCommand {
 		if (result.pruned.length > 0) this.output.info(`Removed ${result.pruned.length} stale config entry/entries`);
 		for (const err of result.errors) this.output.warn(`Doc sync error: ${err.path}: ${err.error}`);
 	}
-	/**
-	* Attempt to repair an unhealthy worktree.
-	* See: plan-2026-01-28-sync-worktree-recovery-and-hardening.md
-	*/
-	async doRepairWorktree(tbdRoot, status) {
-		const spinner = this.output.spinner(`Repairing worktree (${status})...`);
-		try {
-			const result = await repairWorktree(tbdRoot, status);
-			spinner.stop();
-			if (!result.success) throw new WorktreeCorruptedError(`Failed to repair worktree: ${result.error}`);
-			if (result.backedUp) this.output.info(`Corrupted worktree backed up to: ${result.backedUp}`);
-			this.output.success("Worktree repaired successfully");
-		} catch (error) {
-			spinner.stop();
-			if (error instanceof WorktreeCorruptedError) throw error;
-			throw new WorktreeCorruptedError(`Failed to repair worktree: ${error.message}`);
-		}
-	}
 	async showIssueStatus(syncBranch, remote) {
 		const status = await this.getSyncStatus(syncBranch, remote);
 		this.output.data(status, () => {
@@ -5041,7 +5551,7 @@ var SyncHandler = class extends BaseCommand {
 		let ahead = 0;
 		let behind = 0;
 		try {
-			const status = await git("-C", join(this.tbdRoot, WORKTREE_DIR), "status", "--porcelain");
+			const status = await git("-C", this.worktreePath, "status", "--porcelain");
 			if (status) for (const line of status.split("\n")) {
 				if (!line) continue;
 				const statusCode = line.slice(0, 2).trim();
@@ -5100,11 +5610,8 @@ var SyncHandler = class extends BaseCommand {
 				this.output.success("Already up to date");
 				return;
 			}
-			await withIsolatedIndex(async () => {
-				await git("read-tree", `${remote}/${syncBranch}`);
-				const remoteCommit = await git("rev-parse", `${remote}/${syncBranch}`);
-				await git("update-ref", `refs/heads/${syncBranch}`, remoteCommit);
-			});
+			await ensureWorktreeAttachedToBranch(this.worktreePath, syncBranch);
+			await git("-C", this.worktreePath, "merge", "--ff-only", `${remote}/${syncBranch}`);
 			this.output.success(`Pulled ${behind} change(s) from ${remote}/${syncBranch}`);
 		} catch (error) {
 			spinner.stop();
@@ -5120,15 +5627,15 @@ var SyncHandler = class extends BaseCommand {
 	* @returns Tallies of new/updated/deleted files committed
 	*/
 	async commitWorktreeChanges() {
-		const worktreePath = join(this.tbdRoot, WORKTREE_DIR);
+		const worktreePath = this.worktreePath;
 		try {
-			await ensureWorktreeAttached(worktreePath);
+			await ensureWorktreeAttachedToBranch(worktreePath, this.syncBranch);
 			const status = await git("-C", worktreePath, "status", "--porcelain");
 			if (!status || status.trim() === "") return emptyTallies();
 			const tallies = parseGitStatus(status);
 			const fileCount = tallies.new + tallies.updated + tallies.deleted;
 			await git("-C", worktreePath, "add", "-A");
-			await git("-C", worktreePath, "commit", "-m", `tbd sync: ${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, 19)} (${fileCount} file${fileCount === 1 ? "" : "s"})`);
+			await gitCommit(worktreePath, "-m", `tbd sync: ${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, 19)} (${fileCount} file${fileCount === 1 ? "" : "s"})`);
 			return tallies;
 		} catch (error) {
 			if (error.message.includes("nothing to commit")) return emptyTallies();
@@ -5210,7 +5717,7 @@ var SyncHandler = class extends BaseCommand {
 		const spinner = this.output.spinner("Syncing with remote...");
 		const summary = emptySummary();
 		const conflicts = [];
-		const worktreePath = join(this.tbdRoot, WORKTREE_DIR);
+		const worktreePath = this.worktreePath;
 		try {
 			const committedTallies = await this.commitWorktreeChanges();
 			summary.sent.new += committedTallies.new;
@@ -5221,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}`);
@@ -5238,7 +5746,6 @@ var SyncHandler = class extends BaseCommand {
 				this.output.debug("Remote sync branch does not exist yet");
 			}
 			{
-				const { access, writeFile } = await import("node:fs/promises");
 				const attrPath = join(this.dataSyncDir, "mappings", ".gitattributes");
 				try {
 					await access(attrPath);
@@ -5246,7 +5753,7 @@ var SyncHandler = class extends BaseCommand {
 					await writeFile(attrPath, "ids.yml merge=union\n");
 					await git("-C", worktreePath, "add", attrPath);
 					try {
-						await git("-C", worktreePath, "commit", "--no-verify", "-m", "chore: add merge=union for ids.yml");
+						await gitCommit(worktreePath, "--no-verify", "-m", "chore: add merge=union for ids.yml");
 					} catch {}
 				}
 			}
@@ -5272,7 +5779,7 @@ var SyncHandler = class extends BaseCommand {
 						await saveIdMapping(this.dataSyncDir, postMergeMapping);
 						await git("-C", worktreePath, "add", "-A");
 						try {
-							await git("-C", worktreePath, "commit", "--no-verify", "-m", `tbd sync: reconcile ${totalReconciled} missing ID mapping(s)`);
+							await gitCommit(worktreePath, "--no-verify", "-m", `tbd sync: reconcile ${totalReconciled} missing ID mapping(s)`);
 						} catch {}
 						if (reconcileResult.recovered.length > 0) this.output.debug(`Recovered ${reconcileResult.recovered.length} ID mapping(s) from history`);
 						if (reconcileResult.created.length > 0) this.output.debug(`Created ${reconcileResult.created.length} new ID mapping(s) (no history available)`);
@@ -5294,7 +5801,6 @@ var SyncHandler = class extends BaseCommand {
 						const remoteIdsContent = await git("show", `${remote}/${syncBranch}:${DATA_SYNC_DIR}/mappings/ids.yml`);
 						if (remoteIdsContent) {
 							conflictRemoteMapping = parseIdMappingFromYaml(remoteIdsContent);
-							const { readFile } = await import("node:fs/promises");
 							const localMapping = resolveIdMappingConflicts(await readFile(join(this.dataSyncDir, "mappings", "ids.yml"), "utf-8"));
 							const mergedMapping = mergeIdMappings(localMapping, conflictRemoteMapping);
 							await saveIdMapping(this.dataSyncDir, mergedMapping);
@@ -5320,13 +5826,14 @@ var SyncHandler = class extends BaseCommand {
 						throw new SyncError(`Cannot commit: ${conflictedFiles.length} file(s) still have merge conflict markers:\n` + conflictedFiles.map((f) => `  - ${f}`).join("\n") + `\n\nThis is a bug in tbd sync. Please report it and manually resolve conflicts in:\n  ${worktreePath}`);
 					}
 					try {
-						await git("-C", worktreePath, "commit", "--no-verify", "-m", "tbd sync: resolved merge conflicts");
+						await gitCommit(worktreePath, "--no-verify", "-m", "tbd sync: resolved merge conflicts");
 					} catch {
 						this.output.debug("No merge commit needed (conflicts already resolved)");
 					}
 				}
 			}
 		} catch (error) {
+			if (error instanceof SyncError) throw error;
 			this.output.debug(`Fetch failed (may be first sync): ${error.message}`);
 		}
 		let aheadCommits = 0;
@@ -5359,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);
@@ -5813,16 +6321,23 @@ function renderBeadsWarning(colors) {
 * Used by: status
 *
 * @param path - Worktree path
-* @param healthy - Whether worktree is healthy
+* @param status - 'valid' (healthy), 'missing' (created on next sync), or 'prunable' /
+*   'corrupted' (truly unhealthy and needs repair)
 * @param colors - Color functions
 */
-function renderWorktreeStatus(path, healthy, colors) {
+function renderWorktreeStatus(path, status, colors) {
 	console.log("");
-	if (healthy) console.log(`${colors.dim("Worktree:")} ${path} (healthy)`);
-	else {
-		console.log(`${colors.warn("Worktree:")} ${path} (${colors.error("unhealthy")})`);
-		console.log("  Run: tbd doctor --fix");
+	if (status === "valid") {
+		console.log(`${colors.dim("Worktree:")} ${path} (healthy)`);
+		return;
+	}
+	if (status === "missing") {
+		console.log(`${colors.dim("Worktree:")} ${path} (not initialized)`);
+		console.log("  Run: tbd sync (or tbd doctor --fix) to initialize");
+		return;
 	}
+	console.log(`${colors.warn("Worktree:")} ${path} (${colors.error("unhealthy")})`);
+	console.log("  Run: tbd doctor --fix");
 }
 /**
 * Render footer with command suggestions.
@@ -6037,6 +6552,7 @@ var StatusHandler = class extends BaseCommand {
 			display_prefix: null,
 			worktree_path: null,
 			worktree_healthy: null,
+			worktree_status: null,
 			workspaces: [],
 			integrations: {
 				portable_skill: false,
@@ -6150,10 +6666,11 @@ var StatusHandler = class extends BaseCommand {
 			data.remote = config.sync.remote;
 			data.display_prefix = config.display.id_prefix;
 		} catch {}
-		const worktreePath = join(cwd, WORKTREE_DIR);
-		const worktreeHealth = await checkWorktreeHealth(cwd);
-		data.worktree_path = worktreePath;
+		const sharedPaths = await resolveSharedTbdPaths(cwd);
+		const worktreeHealth = await checkWorktreeHealth(cwd, data.sync_branch ?? void 0);
+		data.worktree_path = sharedPaths.sharedWorktreePath;
 		data.worktree_healthy = worktreeHealth.valid;
+		data.worktree_status = worktreeHealth.status;
 		try {
 			data.workspaces = await listWorkspaces(cwd);
 		} catch {}
@@ -6204,7 +6721,7 @@ var StatusHandler = class extends BaseCommand {
 			console.log("");
 			console.log(`Run ${colors.bold("tbd setup auto")} to configure detected agents`);
 		}
-		if (data.worktree_healthy !== null && data.worktree_path) renderWorktreeStatus(data.worktree_path, data.worktree_healthy, colors);
+		if (data.worktree_status !== null && data.worktree_path) renderWorktreeStatus(data.worktree_path, data.worktree_status, colors);
 		if (data.workspaces.length > 0) {
 			console.log("");
 			console.log(colors.bold("WORKSPACES"));
@@ -6302,7 +6819,8 @@ var StatsHandler = class extends BaseCommand {
 		const tbdRoot = await requireInit();
 		let issues;
 		try {
-			issues = await listIssues(await resolveDataSyncDir(tbdRoot));
+			const { dataSyncDir } = await loadDataContext(tbdRoot);
+			issues = await listIssues(dataSyncDir);
 		} catch {
 			throw new NotInitializedError("No issue store found. Run `tbd init` first.");
 		}
@@ -6485,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 = "";
@@ -6495,7 +7042,7 @@ var DoctorHandler = class extends BaseCommand {
 	async run(options) {
 		const tbdRoot = await requireInit();
 		this.cwd = tbdRoot;
-		this.dataSyncDir = await resolveDataSyncDir(tbdRoot);
+		this.dataSyncDir = (await resolveSharedTbdPaths(tbdRoot)).sharedDataSyncDir;
 		try {
 			this.config = await readConfig(this.cwd);
 		} catch {}
@@ -6519,10 +7066,11 @@ var DoctorHandler = class extends BaseCommand {
 		healthChecks.push(await this.checkTempFiles(options.fix));
 		healthChecks.push(this.checkIssueValidity(this.issues, this.invalidIssueFiles));
 		healthChecks.push(await this.checkWorktree(options.fix));
+		healthChecks.push(await this.checkCommonDirLayout(options.fix));
 		const dataLocationResult = await this.checkDataLocation(options.fix);
 		healthChecks.push(dataLocationResult);
 		if (dataLocationResult.status === "ok" && dataLocationResult.message?.includes("migrated")) {
-			this.dataSyncDir = await resolveDataSyncDir(this.cwd);
+			this.dataSyncDir = (await resolveSharedTbdPaths(this.cwd)).sharedDataSyncDir;
 			try {
 				this.invalidIssueFiles = [];
 				this.issues = await listIssues(this.dataSyncDir, {
@@ -6535,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());
@@ -6546,6 +7094,7 @@ var DoctorHandler = class extends BaseCommand {
 		integrationChecks.push(await this.checkCodexHooks());
 		const allChecks = [...healthChecks, ...integrationChecks];
 		const allOk = allChecks.every((c) => c.status === "ok");
+		const hasErrors = allChecks.some((c) => c.status === "error");
 		const hasFixable = allChecks.some((c) => c.fixable && c.status !== "ok");
 		this.output.data({
 			statusInfo,
@@ -6581,11 +7130,12 @@ var DoctorHandler = class extends BaseCommand {
 			else if (hasFixable && !options.fix) this.output.warn("Issues found. Run with --fix to repair.");
 			else this.output.warn("Issues found that may require manual intervention.");
 		});
+		if (hasErrors) process.exitCode = 1;
 	}
 	async gatherStatusInfo() {
 		let gitBranch = null;
 		try {
-			gitBranch = await getCurrentBranch();
+			gitBranch = await getCurrentBranch(this.cwd);
 		} catch {}
 		const worktreeHealth = await checkWorktreeHealth(this.cwd);
 		return {
@@ -6612,7 +7162,7 @@ var DoctorHandler = class extends BaseCommand {
 			if (issue.status === "open" && !blockedIds.has(issue.id)) readyCount++;
 		}
 		let remoteTotal = null;
-		if (this.issues.length === 0 && this.config) remoteTotal = await countRemoteIssues(this.config.sync.remote ?? "origin", this.config.sync.branch ?? "tbd-sync");
+		if (this.issues.length === 0 && this.config) remoteTotal = await countRemoteIssues(this.config.sync.remote ?? "origin", this.config.sync.branch ?? "tbd-sync", this.cwd);
 		return {
 			total: this.issues.length,
 			ready: readyCount,
@@ -6670,6 +7220,13 @@ var DoctorHandler = class extends BaseCommand {
 				path: configPath,
 				suggestion: "Run: tbd init"
 			};
+			if (error instanceof IncompatibleFormatError) return {
+				name: "Config file",
+				status: "error",
+				message: `requires newer tbd (found ${error.foundFormat}, supported ${error.supportedFormat})`,
+				path: configPath,
+				suggestion: "Upgrade: npm install -g get-tbd@latest"
+			};
 			return {
 				name: "Config file",
 				status: "error",
@@ -6761,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-Ctfl_nc1.mjs");
+			const { resolveIdMappingConflicts, saveIdMapping } = await import("./id-mapping-mtoSP9Qt.mjs");
 			const resolved = resolveIdMappingConflicts(content);
 			await saveIdMapping(this.dataSyncDir, resolved);
 			return {
@@ -6810,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-Ctfl_nc1.mjs");
+			const { loadIdMapping, saveIdMapping } = await import("./id-mapping-mtoSP9Qt.mjs");
 			const mapping = await loadIdMapping(this.dataSyncDir);
 			await saveIdMapping(this.dataSyncDir, mapping);
 			return {
@@ -6949,7 +7506,7 @@ var DoctorHandler = class extends BaseCommand {
 			name: "ID mapping coverage",
 			status: "ok"
 		};
-		const { loadIdMapping, saveIdMapping, reconcileMappings } = await import("./id-mapping-Ctfl_nc1.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) {
@@ -6961,10 +7518,10 @@ var DoctorHandler = class extends BaseCommand {
 			status: "ok"
 		};
 		if (fix && !this.checkDryRun("Create missing ID mappings")) {
-			const { parseIdMappingFromYaml, mergeIdMappings } = await import("./id-mapping-Ctfl_nc1.mjs");
+			const { parseIdMappingFromYaml, mergeIdMappings } = await import("./id-mapping-mtoSP9Qt.mjs");
 			let historicalMapping;
 			try {
-				const syncBranch = (await import("./config-BPHcePSm.mjs").then((m) => m.readConfig(this.cwd))).sync.branch;
+				const syncBranch = (await import("./config-DlCUMyCG.mjs").then((m) => m.readConfig(this.cwd))).sync.branch;
 				const logArgs = ["log", "--format=%H"];
 				if (maxHistory > 0) logArgs.push(`-${maxHistory}`);
 				logArgs.push(syncBranch, "--", `${DATA_SYNC_DIR}/mappings/ids.yml`);
@@ -7095,24 +7652,51 @@ var DoctorHandler = class extends BaseCommand {
 	* See: plan-2026-01-28-sync-worktree-recovery-and-hardening.md §4
 	*/
 	async checkWorktree(fix) {
-		const worktreePath = WORKTREE_DIR;
-		const worktreeHealth = await checkWorktreeHealth(this.cwd);
+		const worktreePath = (await resolveSharedTbdPaths(this.cwd)).sharedWorktreePath;
+		const syncBranch = this.config?.sync.branch ?? "tbd-sync";
+		const remote = this.config?.sync.remote ?? "origin";
+		const worktreeHealth = await checkWorktreeHealth(this.cwd, syncBranch);
 		switch (worktreeHealth.status) {
 			case "valid": return {
 				name: "Worktree",
 				status: "ok",
 				path: worktreePath
 			};
-			case "missing": return {
-				name: "Worktree",
-				status: "ok",
-				message: "not created yet",
-				path: worktreePath
-			};
+			case "missing":
+				if (fix && !this.checkDryRun("Initialize shared data-sync worktree")) {
+					try {
+						await withSharedDataSyncLock(this.cwd, async () => {
+							await prepareDataSyncContext(this.cwd);
+						});
+					} catch (error) {
+						return {
+							name: "Worktree",
+							status: "error",
+							message: `initialization failed: ${error instanceof Error ? error.message : String(error)}`,
+							path: worktreePath
+						};
+					}
+					try {
+						this.config = await readConfig(this.cwd);
+					} catch {}
+					return {
+						name: "Worktree",
+						status: "ok",
+						message: "initialized",
+						path: worktreePath
+					};
+				}
+				return {
+					name: "Worktree",
+					status: "ok",
+					message: "not created yet",
+					path: worktreePath
+				};
 			case "prunable":
 			case "corrupted":
 				if (fix && !this.checkDryRun("Repair worktree")) {
-					const result = await repairWorktree(this.cwd, worktreeHealth.status);
+					const repairStatus = worktreeHealth.status;
+					const result = await withSharedDataSyncLock(this.cwd, async () => repairWorktree(this.cwd, repairStatus, remote, syncBranch));
 					if (result.success) return {
 						name: "Worktree",
 						status: "ok",
@@ -7155,10 +7739,80 @@ var DoctorHandler = class extends BaseCommand {
 		}
 	}
 	/**
+	* Check $GIT_COMMON_DIR/tbd/layout.yml against the checkout config.
+	*
+	* Reports missing (initialized on next mutating command), mismatched (rewrite
+	* from config under --fix), or future-format (requires newer tbd, no fix).
+	*
+	* See: plan-2026-05-17-shared-common-dir-sync-worktree.md §Format And Layout
+	* Versioning.
+	*/
+	async checkCommonDirLayout(fix) {
+		if (!this.config) return {
+			name: "Common-dir layout",
+			status: "ok",
+			message: "skipped (no config)"
+		};
+		const sharedPaths = await resolveSharedTbdPaths(this.cwd);
+		const layoutPath = sharedPaths.sharedLayoutPath;
+		let layout;
+		try {
+			layout = await readCommonDirLayout(layoutPath);
+		} catch (error) {
+			return {
+				name: "Common-dir layout",
+				status: "error",
+				message: error instanceof Error ? error.message : String(error),
+				path: layoutPath
+			};
+		}
+		if (!layout) return {
+			name: "Common-dir layout",
+			status: "ok",
+			message: "not initialized yet (created on first sync)",
+			path: layoutPath
+		};
+		if (!isCompatibleFormat(layout.tbd_format)) return {
+			name: "Common-dir layout",
+			status: "error",
+			message: `requires newer tbd (found ${layout.tbd_format})`,
+			path: layoutPath,
+			suggestion: "Upgrade: npm install -g get-tbd@latest"
+		};
+		try {
+			validateCommonDirLayout(layout, this.config);
+			return {
+				name: "Common-dir layout",
+				status: "ok",
+				path: layoutPath
+			};
+		} catch (error) {
+			if (!(error instanceof CommonDirLayoutError)) throw error;
+			if (fix && !this.checkDryRun("Repair common-dir layout")) {
+				const configRef = this.config;
+				await withSharedDataSyncLock(this.cwd, async () => writeCommonDirLayout(sharedPaths, configRef, layout));
+				return {
+					name: "Common-dir layout",
+					status: "ok",
+					message: "rewritten from config",
+					path: layoutPath
+				};
+			}
+			return {
+				name: "Common-dir layout",
+				status: "error",
+				message: "mismatched with config",
+				path: layoutPath,
+				fixable: true,
+				suggestion: "Run: tbd doctor --fix"
+			};
+		}
+	}
+	/**
 	* Check for issues in wrong location.
 	* See: plan-2026-01-28-sync-worktree-recovery-and-hardening.md §5
 	*
-	* Issues should be in .tbd/data-sync-worktree/.tbd/data-sync/issues/
+	* Issues should be in $GIT_COMMON_DIR/tbd/data-sync-worktree/.tbd/data-sync/issues/
 	* If they're in .tbd/data-sync/issues/ on main branch, the worktree was missing
 	* and data was written to the fallback path - this is a bug requiring migration.
 	*/
@@ -7176,7 +7830,7 @@ var DoctorHandler = class extends BaseCommand {
 		if (fix && !this.checkDryRun("Migrate data to worktree")) {
 			let worktreeHealth = await checkWorktreeHealth(this.cwd);
 			if (worktreeHealth.status === "missing") {
-				const initResult = await initWorktree(this.cwd);
+				const initResult = await withSharedDataSyncLock(this.cwd, async () => initWorktree(this.cwd));
 				if (!initResult.success) return {
 					name: "Data location",
 					status: "error",
@@ -7219,7 +7873,7 @@ var DoctorHandler = class extends BaseCommand {
 			path: wrongIssuesPath,
 			details: [
 				`Found ${wrongPathIssues.length} issues in .tbd/data-sync/ (wrong)`,
-				"Issues should be in .tbd/data-sync-worktree/.tbd/data-sync/",
+				"Issues should be in $GIT_COMMON_DIR/tbd/data-sync-worktree/.tbd/data-sync/",
 				"This indicates the worktree was missing when issues were created"
 			],
 			fixable: true,
@@ -7232,14 +7886,14 @@ var DoctorHandler = class extends BaseCommand {
 	*/
 	async checkLocalSyncBranch() {
 		const syncBranch = this.config?.sync.branch ?? "tbd-sync";
-		const localHealth = await checkLocalBranchHealth(syncBranch);
+		const localHealth = await checkLocalBranchHealth(syncBranch, this.cwd);
 		if (localHealth.exists && !localHealth.orphaned) return {
 			name: "Local sync branch",
 			status: "ok",
 			message: syncBranch
 		};
 		if (!localHealth.exists) {
-			if ((await checkRemoteBranchHealth(this.config?.sync.remote ?? "origin", syncBranch)).exists) return {
+			if ((await checkRemoteBranchHealth(this.config?.sync.remote ?? "origin", syncBranch, this.cwd)).exists) return {
 				name: "Local sync branch",
 				status: "warn",
 				message: `${syncBranch} not found (remote exists)`,
@@ -7262,24 +7916,28 @@ 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);
-		if (remoteHealth.exists) {
-			if (remoteHealth.diverged) return {
+		const remoteHealth = await checkRemoteBranchHealth(remote, syncBranch, this.cwd);
+		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"
 			};
 		}
-		if ((await checkLocalBranchHealth(syncBranch)).exists) return {
+		const diag = classifyRemoteSyncHealth(remoteHealth, remote, syncBranch);
+		if (diag) return diag;
+		if ((await checkLocalBranchHealth(syncBranch, this.cwd)).exists) return {
 			name: "Remote sync branch",
 			status: "warn",
 			message: `${remote}/${syncBranch} not found`,
@@ -7308,7 +7966,7 @@ var DoctorHandler = class extends BaseCommand {
 			status: "ok"
 		};
 		const syncBranch = this.config?.sync.branch ?? "tbd-sync";
-		if (!(await checkRemoteBranchHealth(this.config?.sync.remote ?? "origin", syncBranch)).exists) return {
+		if (!(await checkRemoteBranchHealth(this.config?.sync.remote ?? "origin", syncBranch, this.cwd)).exists) return {
 			name: "Sync status",
 			status: "warn",
 			message: `${localIssueCount} local issues, remote branch not found`,
@@ -7454,6 +8112,7 @@ var ConfigShowHandler = class extends BaseCommand {
 			console.log(`${colors.dim("sync:")}`);
 			console.log(`  ${colors.dim("branch:")} ${config.sync.branch}`);
 			console.log(`  ${colors.dim("remote:")} ${config.sync.remote}`);
+			console.log(`  ${colors.dim("storage:")} ${config.sync.storage}`);
 			console.log(`${colors.dim("display:")}`);
 			console.log(`  ${colors.dim("id_prefix:")} ${config.display.id_prefix}`);
 			console.log(`${colors.dim("settings:")}`);
@@ -7589,9 +8248,9 @@ async function listAtticEntries(tbdRoot, filterById) {
 var AtticListHandler = class extends BaseCommand {
 	async run(id) {
 		const tbdRoot = await requireInit();
+		const { mapping, config } = await loadDataContext(tbdRoot);
 		const entries = await listAtticEntries(tbdRoot, id ? normalizeIssueId(id) : void 0);
-		const mapping = await loadIdMapping(await resolveDataSyncDir(tbdRoot));
-		const prefix = (await readConfig(tbdRoot)).display.id_prefix;
+		const prefix = config.display.id_prefix;
 		const showDebug = this.ctx.debug;
 		const output = entries.map((e) => ({
 			id: showDebug ? formatDebugId(e.entity_id, mapping, prefix) : formatDisplayId(e.entity_id, mapping, prefix),
@@ -7616,10 +8275,10 @@ var AtticListHandler = class extends BaseCommand {
 var AtticShowHandler = class extends BaseCommand {
 	async run(id, timestamp) {
 		const tbdRoot = await requireInit();
+		const { mapping, config } = await loadDataContext(tbdRoot);
 		const entry = (await listAtticEntries(tbdRoot, normalizeIssueId(id))).find((e) => e.timestamp === timestamp || e.timestamp.replace(/:/g, "-") === timestamp);
 		if (!entry) throw new NotFoundError("Attic entry", `${id} at ${timestamp}`);
-		const mapping = await loadIdMapping(await resolveDataSyncDir(tbdRoot));
-		const prefix = (await readConfig(tbdRoot)).display.id_prefix;
+		const prefix = config.display.id_prefix;
 		const displayId = this.ctx.debug ? formatDebugId(entry.entity_id, mapping, prefix) : formatDisplayId(entry.entity_id, mapping, prefix);
 		this.output.data(entry, () => {
 			const colors = this.output.getColors();
@@ -7645,6 +8304,7 @@ var AtticShowHandler = class extends BaseCommand {
 var AtticRestoreHandler = class extends BaseCommand {
 	async run(id, timestamp) {
 		const tbdRoot = await requireInit();
+		await loadDataContext(tbdRoot);
 		const normalizedId = normalizeIssueId(id);
 		const entry = (await listAtticEntries(tbdRoot, normalizedId)).find((e) => e.timestamp === timestamp || e.timestamp.replace(/:/g, "-") === timestamp);
 		if (!entry) throw new NotFoundError("Attic entry", `${id} at ${timestamp}`);
@@ -7652,24 +8312,24 @@ var AtticRestoreHandler = class extends BaseCommand {
 			id: normalizedId,
 			field: entry.field
 		})) return;
-		const dataSyncDir = await resolveDataSyncDir(tbdRoot);
-		let issue;
-		try {
-			issue = await readIssue(dataSyncDir, normalizedId);
-		} catch {
-			throw new NotFoundError("Issue", id);
-		}
-		const field = entry.field;
-		if (field === "description" || field === "notes" || field === "title") issue[field] = entry.lost_value;
-		else throw new ValidationError(`Cannot restore field: ${entry.field}`);
-		issue.version += 1;
-		issue.updated_at = now();
+		let displayId = id;
 		await this.execute(async () => {
-			await writeIssue(dataSyncDir, issue);
+			await withDataSyncContext(tbdRoot, { lock: true }, async ({ dataSyncDir, mapping, config }) => {
+				let issue;
+				try {
+					issue = await readIssue(dataSyncDir, normalizedId);
+				} catch {
+					throw new NotFoundError("Issue", id);
+				}
+				const field = entry.field;
+				if (field === "description" || field === "notes" || field === "title") issue[field] = entry.lost_value;
+				else throw new ValidationError(`Cannot restore field: ${entry.field}`);
+				issue.version += 1;
+				issue.updated_at = now();
+				await writeIssue(dataSyncDir, issue);
+				displayId = this.ctx.debug ? formatDebugId(normalizedId, mapping, config.display.id_prefix) : formatDisplayId(normalizedId, mapping, config.display.id_prefix);
+			});
 		}, "Failed to restore from attic");
-		const mapping = await loadIdMapping(dataSyncDir);
-		const prefix = (await readConfig(tbdRoot)).display.id_prefix;
-		const displayId = this.ctx.debug ? formatDebugId(normalizedId, mapping, prefix) : formatDisplayId(normalizedId, mapping, prefix);
 		this.output.success(`Restored ${entry.field} for ${displayId} from attic entry ${timestamp}`);
 	}
 };
@@ -7789,14 +8449,18 @@ var ImportHandler = class extends BaseCommand {
 		if (!file && !options.validate) throw new ValidationError("Provide a JSONL file path to import.\n\nFor Beads migration, use: tbd setup --from-beads\nFor workspace import, use: tbd import --workspace=<name> or --outbox");
 		if (options.validate) {
 			this.tbdRoot = await requireInit();
-			this.dataSyncDir = await resolveDataSyncDir(this.tbdRoot);
-			await this.validateImport(options);
+			await withDataSyncContext(this.tbdRoot, { lock: true }, async ({ dataSyncDir }) => {
+				this.dataSyncDir = dataSyncDir;
+				await this.validateImport(options);
+			});
 			return;
 		}
 		if (file) {
 			this.tbdRoot = await requireInit();
-			this.dataSyncDir = await resolveDataSyncDir(this.tbdRoot);
-			await this.importFromFile(file, options);
+			await withDataSyncContext(this.tbdRoot, { lock: true }, async ({ dataSyncDir }) => {
+				this.dataSyncDir = dataSyncDir;
+				await this.importFromFile(file, options);
+			});
 		}
 	}
 	/**
@@ -7804,7 +8468,6 @@ var ImportHandler = class extends BaseCommand {
 	*/
 	async importFromWorkspaceCmd(options) {
 		this.tbdRoot = await requireInit();
-		this.dataSyncDir = await resolveDataSyncDir(this.tbdRoot);
 		const wsOptions = {
 			workspace: options.workspace,
 			dir: options.dir,
@@ -7815,7 +8478,10 @@ var ImportHandler = class extends BaseCommand {
 		const spinner = this.output.spinner("Importing from workspace...");
 		wsOptions.logger = this.output.logger(spinner);
 		const result = await this.execute(async () => {
-			return await importFromWorkspace(this.tbdRoot, this.dataSyncDir, wsOptions);
+			return await withDataSyncContext(this.tbdRoot, { lock: true }, async ({ dataSyncDir }) => {
+				this.dataSyncDir = dataSyncDir;
+				return await importFromWorkspace(this.tbdRoot, this.dataSyncDir, wsOptions);
+			});
 		}, "Failed to import from workspace");
 		spinner.stop();
 		if (!result) return;
@@ -8461,7 +9127,12 @@ var UninstallHandler = class extends BaseCommand {
 		const syncBranch = config?.sync.branch ?? SYNC_BRANCH;
 		const remote = config?.sync.remote ?? "origin";
 		const tbdDir = join(tbdRoot, ".tbd");
-		const worktreePath = join(tbdDir, "data-sync-worktree");
+		const sharedPaths = await resolveSharedTbdPaths(tbdRoot).catch((error) => {
+			this.output.debug(`resolveSharedTbdPaths failed: ${error instanceof Error ? error.message : String(error)}`);
+			return null;
+		});
+		const worktreePath = sharedPaths?.sharedWorktreePath ?? join(tbdDir, "data-sync-worktree");
+		const legacyWorktreePath = join(tbdDir, "data-sync-worktree");
 		const displayPath = (p) => relative(process.cwd(), p) || p;
 		const items = [];
 		let worktreeExists = false;
@@ -8471,6 +9142,13 @@ var UninstallHandler = class extends BaseCommand {
 			const worktreeStats = await this.getDirectoryStats(worktreePath);
 			items.push(`  - Worktree: ${displayPath(worktreePath)} (${worktreeStats.files} files)`);
 		} catch {}
+		let legacyWorktreeExists = false;
+		if (legacyWorktreePath !== worktreePath) try {
+			await access(legacyWorktreePath);
+			legacyWorktreeExists = true;
+			const legacyStats = await this.getDirectoryStats(legacyWorktreePath);
+			items.push(`  - Legacy worktree: ${displayPath(legacyWorktreePath)} (${legacyStats.files} files)`);
+		} catch {}
 		let localBranchExists = false;
 		try {
 			execSync(`git rev-parse --verify ${syncBranch}`, {
@@ -8534,6 +9212,23 @@ var UninstallHandler = class extends BaseCommand {
 				console.log(`  ${colors.warn("⚠")} Could not remove worktree directory`);
 			}
 		}
+		if (legacyWorktreeExists) try {
+			execSync(`git worktree remove --force "${legacyWorktreePath}"`, {
+				encoding: "utf-8",
+				stdio: [
+					"ignore",
+					"pipe",
+					"ignore"
+				]
+			});
+			console.log(`  ${colors.success("✓")} Removed legacy git worktree`);
+		} catch {
+			await rm(legacyWorktreePath, {
+				recursive: true,
+				force: true
+			});
+			console.log(`  ${colors.success("✓")} Removed legacy worktree directory`);
+		}
 		if (localBranchExists && !options.keepBranch) try {
 			execSync(`git branch -D ${syncBranch}`, {
 				encoding: "utf-8",
@@ -8579,6 +9274,15 @@ var UninstallHandler = class extends BaseCommand {
 		} catch (error) {
 			throw new CLIError(`Failed to remove .tbd directory: ${error instanceof Error ? error.message : String(error)}`);
 		}
+		if (sharedPaths) try {
+			await rm(sharedPaths.sharedTbdDir, {
+				recursive: true,
+				force: true
+			});
+			console.log(`  ${colors.success("✓")} Removed shared common-dir metadata`);
+		} catch {
+			console.log(`  ${colors.warn("⚠")} Could not remove shared common-dir metadata`);
+		}
 		console.log("");
 		this.output.success("tbd has been uninstalled from this repository.");
 		if (options.keepBranch && localBranchExists) {
@@ -9061,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 {
@@ -9149,7 +9854,8 @@ var PrimeHandler = class extends BaseCommand {
 	*/
 	async getIssueStats(tbdRoot) {
 		try {
-			const issues = await listIssues(await resolveDataSyncDir(tbdRoot));
+			const { dataSyncDir } = await loadDataContext(tbdRoot);
+			const issues = await listIssues(dataSyncDir);
 			let open = 0;
 			let inProgress = 0;
 			const blockedIds = /* @__PURE__ */ new Set();
@@ -10002,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
@@ -10022,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);
 }
@@ -10825,25 +11544,26 @@ var SetupDefaultHandler = class extends BaseCommand {
 		if (!gitRoot) throw new CLIError("Could not determine git repository root.");
 		const projectDir = gitRoot;
 		const hasTbd = await isInitialized(projectDir);
-		const hasBeads = await pathExists(join(projectDir, ".beads"));
+		const hasBeads = await pathExists$1(join(projectDir, ".beads"));
 		if (options.fromBeads && !hasBeads) throw new CLIError("The --from-beads flag requires a .beads/ directory to migrate from.\nFor fresh setup, use: tbd setup --auto --prefix=<name>");
 		console.log("Checking repository...");
 		console.log(`  ${colors.success("✓")} Git repository detected`);
 		if (hasTbd) {
 			const { config, migrated, changes } = await readConfigWithMigration(projectDir);
 			console.log(`  ${colors.success("✓")} tbd initialized (prefix: ${config.display.id_prefix})`);
-			let needsConfigWrite = migrated;
+			let ghCliChanged = false;
 			if (options.ghCli === false && config.settings.use_gh_cli !== false) {
 				config.settings.use_gh_cli = false;
-				needsConfigWrite = true;
+				ghCliChanged = true;
 			}
-			if (needsConfigWrite) {
+			if (migrated) {
+				await withDataSyncContext(projectDir, { lock: true }, async () => void 0);
+				console.log(`  ${colors.success("✓")} Config migrated to latest format`);
+				for (const change of changes) console.log(`      ${colors.dim(change)}`);
+			}
+			if (ghCliChanged) {
 				await writeConfig(projectDir, config);
-				if (migrated) {
-					console.log(`  ${colors.success("✓")} Config migrated to latest format`);
-					for (const change of changes) console.log(`      ${colors.dim(change)}`);
-				}
-				if (options.ghCli === false) console.log(`  ${colors.success("✓")} Disabled gh CLI auto-setup`);
+				console.log(`  ${colors.success("✓")} Disabled gh CLI auto-setup`);
 			}
 			console.log("");
 			await this.handleAlreadyInitialized(projectDir, isAutoMode);
@@ -10991,7 +11711,7 @@ Example:
 	}
 	async initializeTbd(cwd, prefix) {
 		const colors = this.output.getColors();
-		await initConfig(cwd, VERSION, prefix);
+		const config = await initConfig(cwd, VERSION, prefix);
 		console.log(`  ${colors.success("✓")} Created .tbd/config.yml`);
 		const tbdGitignoreResult = await ensureGitignorePatterns(join(cwd, TBD_DIR, ".gitignore"), [
 			"# Synced documentation cache (regenerated by tbd sync --docs)",
@@ -11022,7 +11742,10 @@ Example:
 		if (gitattributesResult.created) console.log(`  ${colors.success("✓")} Created .tbd/.gitattributes (merge protection)`);
 		else if (gitattributesResult.added.length > 0) console.log(`  ${colors.success("✓")} Updated .tbd/.gitattributes (merge protection)`);
 		try {
-			await initWorktree(cwd);
+			await withSharedDataSyncLock(cwd, async () => {
+				await initWorktree(cwd);
+				await writeCommonDirLayout(await resolveSharedTbdPaths(cwd), config);
+			});
 			const health = await checkWorktreeHealth(cwd);
 			if (health.valid) console.log(`  ${colors.success("✓")} Initialized sync branch`);
 			else {
@@ -11220,18 +11943,18 @@ var SetupAutoHandler = class extends BaseCommand {
 		};
 		if (mode === "off") return result;
 		if (mode === "auto") {
-			const hasClaudeDir = await pathExists(GLOBAL_CLAUDE_DIR);
+			const hasClaudeDir = await pathExists$1(GLOBAL_CLAUDE_DIR);
 			const hasClaudeEnv = Object.keys(process.env).some((k) => k.startsWith("CLAUDE_"));
 			if (!hasClaudeDir && !hasClaudeEnv) return result;
 		}
 		result.detected = true;
 		const claudePaths = getClaudePaths(cwd);
 		try {
-			if (await pathExists(claudePaths.settings)) {
+			if (await pathExists$1(claudePaths.settings)) {
 				const content = await readFile(claudePaths.settings, "utf-8");
 				const hooks = JSON.parse(content).hooks;
 				if (hooks) {
-					if (hooks.SessionStart?.some((h) => h.hooks?.some((hook) => (hook.command?.includes("tbd prime") ?? false) || (hook.command?.includes("tbd-session.sh") ?? false))) && await pathExists(claudePaths.skill)) result.alreadyInstalled = true;
+					if (hooks.SessionStart?.some((h) => h.hooks?.some((hook) => (hook.command?.includes("tbd prime") ?? false) || (hook.command?.includes("tbd-session.sh") ?? false))) && await pathExists$1(claudePaths.skill)) result.alreadyInstalled = true;
 				}
 			}
 			const handler = new SetupClaudeHandler(this.cmd);
@@ -11252,7 +11975,7 @@ var SetupAutoHandler = class extends BaseCommand {
 		};
 		if (mode === "off") return result;
 		const agentsPath = getAgentsMdPath(cwd);
-		const hasAgentsMd = await pathExists(agentsPath);
+		const hasAgentsMd = await pathExists$1(agentsPath);
 		if (mode === "auto") {
 			const hasCodexEnv = Object.keys(process.env).some((k) => k.startsWith("CODEX_"));
 			if (!hasAgentsMd && !hasCodexEnv) return result;
@@ -11322,7 +12045,6 @@ const setupCommand = new Command("setup").description("Configure tbd integration
 var SaveHandler = class extends BaseCommand {
 	async run(options) {
 		const tbdRoot = await requireInit();
-		const dataSyncDir = await resolveDataSyncDir(tbdRoot);
 		if (!options.workspace && !options.dir && !options.outbox) throw new ValidationError("One of --workspace, --dir, or --outbox is required");
 		const saveOptions = {
 			workspace: options.workspace,
@@ -11334,7 +12056,9 @@ var SaveHandler = class extends BaseCommand {
 		const spinner = this.output.spinner("Saving issues...");
 		saveOptions.logger = this.output.logger(spinner);
 		const result = await this.execute(async () => {
-			return await saveToWorkspace(tbdRoot, dataSyncDir, saveOptions);
+			return await withDataSyncContext(tbdRoot, { lock: true }, async ({ dataSyncDir }) => {
+				return await saveToWorkspace(tbdRoot, dataSyncDir, saveOptions);
+			});
 		}, "Failed to save issues");
 		spinner.stop();
 		if (!result) return;