get-tbd 0.1.29 → 0.2.0

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-CJyVkC3V.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-rIE4xSVs.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 isValidWorkspaceName, C as TBD_SHORTCUTS_STANDARD, D as WORKTREE_DIR, E as WORKSPACES_DIR, M as resolveDataSyncDir, O as WORKTREE_DIR_NAME, S as TBD_GUIDELINES_DIR, T as TBD_TEMPLATES_DIR, _ as DEFAULT_SHORTCUT_PATHS, a as isInitialized, b as TBD_DIR, c as readConfigWithMigration, d as writeConfig, g as DEFAULT_GUIDELINES_PATHS, h as DATA_SYNC_DIR_NAME, i as initConfig, j as resolveAtticDir, k as getWorkspaceDir, l as readLocalState, m as DATA_SYNC_DIR, n as findTbdRoot, o as markWelcomeSeen, p as CHARS_PER_TOKEN, r as hasSeenWelcome, s as readConfig, u as updateLocalState, v as DEFAULT_TEMPLATE_PATHS, w as TBD_SHORTCUTS_SYSTEM, x as TBD_DOCS_DIR, y as SYNC_BRANCH } from "./config-B38rbI9u.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-CtfTfGIh.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,28 +620,6 @@ 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
-*/
-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";
-	}
-};
-/**
 * Classify a sync error to determine appropriate recovery action.
 *
 * Used by `tbd sync` to decide whether to:
@@ -706,10 +684,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 +715,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 +755,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 = [];
@@ -974,6 +949,18 @@ async function git(...args) {
 	return stdout.trim();
 }
 /**
+* 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.
 * Git 2.42 (August 2023) introduced `git worktree add --orphan` which tbd requires.
 */
@@ -1088,23 +1075,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
 */
@@ -1330,15 +1300,15 @@ 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;
@@ -1347,19 +1317,38 @@ async function branchExists(branch) {
 /**
 * Check if a remote branch exists.
 */
-async function remoteBranchExists(remote, branch) {
+async function remoteBranchExists(remote, branch, baseDir) {
 	try {
-		await git("ls-remote", "--exit-code", remote, `refs/heads/${branch}`);
+		await git(...baseDir ? ["-C", baseDir] : [], "ls-remote", "--exit-code", remote, `refs/heads/${branch}`);
 		return true;
 	} catch {
 		return false;
 	}
 }
+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 +1362,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 +1438,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 +1464,110 @@ 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)
+		};
+	}
+}
 /**
 * 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 +1575,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 +1583,7 @@ async function initWorktree(baseDir, remote = "origin", syncBranch = SYNC_BRANCH
 				created: true
 			};
 		}
-		if (await remoteBranchExists(remote, syncBranch)) {
+		if (await remoteBranchExists(remote, syncBranch, baseDir)) {
 			await git("-C", baseDir, "fetch", remote, syncBranch);
 			await git("-C", baseDir, "worktree", "add", "-b", syncBranch, worktreePath, `${remote}/${syncBranch}`);
 			return {
@@ -1513,12 +1598,12 @@ 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");
 		return {
 			success: true,
 			path: worktreePath,
@@ -1538,16 +1623,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,14 +1654,15 @@ 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);
+			const mergeBase = await git(...dirArgs, "merge-base", syncBranch, `${remote}/${syncBranch}`);
+			const localHead = await git(...dirArgs, "rev-parse", syncBranch);
 			diverged = mergeBase.trim() !== localHead.trim() && mergeBase.trim() !== remoteHead;
 		} catch {
 			diverged = false;
@@ -1602,7 +1689,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;
@@ -1634,10 +1722,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 +1742,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 +1754,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 +1790,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 +1824,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 +1848,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 +1859,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 +1878,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 +1985,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)",
@@ -1857,11 +2026,19 @@ Example:
 				if (error instanceof CLIError) throw error;
 				this.output.debug(`Git version check skipped: ${error.message}`);
 			}
-			const worktreeResult = await initWorktree(cwd, remote, syncBranch);
+			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 ${TBD_DIR}/${WORKTREE_DIR_NAME}/`);
-				else this.output.debug(`Worktree already exists at ${TBD_DIR}/${WORKTREE_DIR_NAME}/`);
-				const health = await checkWorktreeHealth(cwd);
+				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");
@@ -1913,7 +2090,8 @@ function formatUnknownError(error) {
 * 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/.
+* 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
 */
@@ -2208,6 +2386,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 +2576,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 +2666,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 +3313,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 +3517,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 +3577,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 +3860,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 +3910,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 +3955,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 +4003,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 +4064,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 +4116,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 +4136,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 +5160,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 +5174,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
+			});
 		});
 	}
 	/**
@@ -4988,28 +5240,10 @@ var SyncHandler = class extends BaseCommand {
 		const parts = [];
 		if (result.added.length > 0) parts.push(`+${result.added.length}`);
 		if (result.updated.length > 0) parts.push(`~${result.updated.length}`);
-		if (result.removed.length > 0) parts.push(`-${result.removed.length}`);
-		if (parts.length > 0) this.output.success(`Synced docs: ${parts.join(" ")} doc(s)`);
-		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}`);
-		}
+		if (result.removed.length > 0) parts.push(`-${result.removed.length}`);
+		if (parts.length > 0) this.output.success(`Synced docs: ${parts.join(" ")} doc(s)`);
+		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}`);
 	}
 	async showIssueStatus(syncBranch, remote) {
 		const status = await this.getSyncStatus(syncBranch, remote);
@@ -5041,7 +5275,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 +5334,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 +5351,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 +5441,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;
@@ -5238,7 +5469,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 +5476,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 +5502,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 +5524,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,7 +5549,7 @@ 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)");
 					}
@@ -5813,16 +6042,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.
@@ -5845,9 +6081,10 @@ function renderFooter(suggestions, colors) {
 /**
 * Centralized path constants and utilities for coding agent integrations.
 *
-* IMPORTANT: All tbd integration files (hooks, settings, skills) are installed
-* to PROJECT-LOCAL directories (.claude/, AGENTS.md) ONLY. We do NOT install to
-* global/user directories (~/.claude/).
+* IMPORTANT: All tbd integration files (skills, hooks, settings, scripts) are
+* installed to PROJECT-LOCAL directories (.agents/, .claude/, .codex/,
+* scripts/agent/, AGENTS.md) ONLY. We do NOT install to global/user directories
+* (~/.claude/, ~/.codex/, ~/.agents/).
 *
 * This file defines all path constants in one place to:
 * 1. Ensure consistency across the codebase
@@ -5855,6 +6092,19 @@ function renderFooter(suggestions, colors) {
 * 3. Simplify future changes to path conventions
 */
 /**
+* Format version stamped into generated agent integration artifacts (e.g. the
+* AGENTS.md managed block's begin marker: `... format=f03 surface=...`).
+*
+* UNIFIED with the `.tbd/` directory format (`tbd_format`): there is one format
+* code for all tbd-managed surfaces, sourced from `tbd-format.ts` (the single
+* source of truth). Bump `CURRENT_FORMAT` there when any managed surface — config
+* schema OR a generated agent surface — changes shape. A marked AGENTS.md block
+* with no `format=` field predates this and is treated as `f01`; a running tbd
+* that finds a HIGHER format than it knows refuses to overwrite it and tells the
+* user to upgrade tbd.
+*/
+const AGENT_INTEGRATION_FORMAT = CURRENT_FORMAT;
+/**
 * Relative path to Claude Code settings file from project root.
 * This is where hooks are configured.
 */
@@ -5888,11 +6138,33 @@ const TBD_CLOSING_REMINDER_REL = ".claude/hooks/tbd-closing-reminder.sh";
 */
 const GH_CLI_SCRIPT_REL = ".claude/scripts/ensure-gh-cli.sh";
 /**
+* Canonical portable project Agent Skill, scanned by Codex, Gemini CLI, Cursor,
+* GitHub Copilot, Amp, OpenCode, pi, and other Agent Skills clients.
+*/
+const AGENTS_SKILL_REL = ".agents/skills/tbd/SKILL.md";
+/**
+* Repository distribution copy of the skill, for skills.sh-style installers
+* (`npx skills add`) and direct GitHub browsing.
+*/
+const SKILLS_DIST_REL = "skills/tbd/SKILL.md";
+/**
 * Relative path to AGENTS.md file from project root.
 * Used by Codex, Factory.ai, Cursor (v1.6+), and other compatible tools.
 */
 const AGENTS_MD_REL = "AGENTS.md";
 /**
+* Codex project-local config/hook directory.
+*/
+const CODEX_DIR_REL = ".codex";
+/**
+* Codex project-local hooks file (Claude-compatible event schema).
+*/
+const CODEX_HOOKS_REL = ".codex/hooks.json";
+/**
+* Codex project-local config; may also carry an inline `[hooks]` table.
+*/
+const CODEX_CONFIG_REL = ".codex/config.toml";
+/**
 * Global Claude Code directory in user's home.
 * Used ONLY for detecting if Claude Code is installed (for agent detection).
 * All installations are project-local.
@@ -5926,6 +6198,31 @@ function getAgentsMdPath(projectRoot) {
 	return join(projectRoot, AGENTS_MD_REL);
 }
 /**
+* Get the three SKILL.md targets: the portable Agent Skills install, the Claude
+* Code mirror, and the committed distribution copy.
+*
+* @param projectRoot - The project root directory (containing .tbd/)
+*/
+function getAgentSkillPaths(projectRoot) {
+	return {
+		portable: join(projectRoot, AGENTS_SKILL_REL),
+		claudeMirror: join(projectRoot, CLAUDE_SKILL_REL),
+		distribution: join(projectRoot, SKILLS_DIST_REL)
+	};
+}
+/**
+* Get project-local Codex config/hook paths.
+*
+* @param projectRoot - The project root directory
+*/
+function getCodexPaths(projectRoot) {
+	return {
+		dir: join(projectRoot, CODEX_DIR_REL),
+		hooks: join(projectRoot, CODEX_HOOKS_REL),
+		config: join(projectRoot, CODEX_CONFIG_REL)
+	};
+}
+/**
 * Display path for Claude Code settings in status/doctor output.
 */
 const CLAUDE_SETTINGS_DISPLAY = "./.claude/settings.json";
@@ -5933,6 +6230,14 @@ const CLAUDE_SETTINGS_DISPLAY = "./.claude/settings.json";
 * Display path for AGENTS.md in status/doctor output.
 */
 const AGENTS_MD_DISPLAY = "./AGENTS.md";
+/**
+* Display path for the portable Agent Skill in status/doctor output.
+*/
+const AGENTS_SKILL_DISPLAY = "./.agents/skills/tbd/SKILL.md";
+/**
+* Display path for the Codex hooks file in status/doctor output.
+*/
+const CODEX_HOOKS_DISPLAY = "./.codex/hooks.json";
 
 //#endregion
 //#region src/cli/commands/status.ts
@@ -5968,12 +6273,17 @@ var StatusHandler = class extends BaseCommand {
 			display_prefix: null,
 			worktree_path: null,
 			worktree_healthy: null,
+			worktree_status: null,
 			workspaces: [],
 			integrations: {
+				portable_skill: false,
+				portable_skill_path: AGENTS_SKILL_DISPLAY,
 				claude_code: false,
 				claude_code_path: CLAUDE_SETTINGS_DISPLAY,
 				codex: false,
-				codex_path: AGENTS_MD_DISPLAY
+				codex_path: AGENTS_MD_DISPLAY,
+				codex_hooks: false,
+				codex_hooks_path: CODEX_HOOKS_DISPLAY
 			}
 		};
 		const gitInfo = await this.checkGitRepo();
@@ -6041,11 +6351,23 @@ var StatusHandler = class extends BaseCommand {
 		const claudePaths = getClaudePaths(projectRoot);
 		const agentsPath = getAgentsMdPath(projectRoot);
 		const result = {
+			portable_skill: false,
+			portable_skill_path: AGENTS_SKILL_DISPLAY,
 			claude_code: false,
 			claude_code_path: CLAUDE_SETTINGS_DISPLAY,
 			codex: false,
-			codex_path: AGENTS_MD_DISPLAY
+			codex_path: AGENTS_MD_DISPLAY,
+			codex_hooks: false,
+			codex_hooks_path: CODEX_HOOKS_DISPLAY
 		};
+		try {
+			await access(getAgentSkillPaths(projectRoot).portable);
+			result.portable_skill = true;
+		} catch {}
+		try {
+			await access(getCodexPaths(projectRoot).hooks);
+			result.codex_hooks = true;
+		} catch {}
 		try {
 			await access(claudePaths.settings);
 			const content = await readFile(claudePaths.settings, "utf-8");
@@ -6065,10 +6387,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 {}
@@ -6094,19 +6417,32 @@ var StatusHandler = class extends BaseCommand {
 			remote: data.remote,
 			displayPrefix: data.display_prefix
 		}, colors);
-		if (renderIntegrationsSection([{
-			name: "Claude Code hooks",
-			installed: data.integrations.claude_code,
-			path: data.integrations.claude_code_path
-		}, {
-			name: "Codex AGENTS.md",
-			installed: data.integrations.codex,
-			path: data.integrations.codex_path
-		}], colors)) {
+		if (renderIntegrationsSection([
+			{
+				name: "Portable Agent Skill",
+				installed: data.integrations.portable_skill,
+				path: data.integrations.portable_skill_path
+			},
+			{
+				name: "Claude Code hooks",
+				installed: data.integrations.claude_code,
+				path: data.integrations.claude_code_path
+			},
+			{
+				name: "Codex AGENTS.md",
+				installed: data.integrations.codex,
+				path: data.integrations.codex_path
+			},
+			{
+				name: "Codex hooks",
+				installed: data.integrations.codex_hooks,
+				path: data.integrations.codex_hooks_path
+			}
+		], colors)) {
 			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"));
@@ -6204,7 +6540,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.");
 		}
@@ -6397,7 +6734,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 {}
@@ -6421,10 +6758,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, {
@@ -6442,10 +6780,13 @@ var DoctorHandler = class extends BaseCommand {
 		healthChecks.push(await this.checkCloneScenarios());
 		healthChecks.push(await this.checkSyncConsistency());
 		const integrationChecks = [];
+		integrationChecks.push(await this.checkPortableSkill());
 		integrationChecks.push(await this.checkClaudeSkill());
 		integrationChecks.push(await this.checkCodexAgents());
+		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,
@@ -6481,11 +6822,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 {
@@ -6512,7 +6854,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,
@@ -6570,6 +6912,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",
@@ -6661,7 +7010,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-CFoPVinz.mjs");
 			const resolved = resolveIdMappingConflicts(content);
 			await saveIdMapping(this.dataSyncDir, resolved);
 			return {
@@ -6710,7 +7059,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-CFoPVinz.mjs");
 			const mapping = await loadIdMapping(this.dataSyncDir);
 			await saveIdMapping(this.dataSyncDir, mapping);
 			return {
@@ -6849,7 +7198,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-CFoPVinz.mjs");
 		const mapping = await loadIdMapping(this.dataSyncDir);
 		const missingIds = [];
 		for (const issue of this.issues) {
@@ -6861,10 +7210,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-CFoPVinz.mjs");
 			let historicalMapping;
 			try {
-				const syncBranch = (await import("./config-C0ITTrtc.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`);
@@ -6907,6 +7256,25 @@ var DoctorHandler = class extends BaseCommand {
 			suggestion: "Run: tbd doctor --fix to create missing mappings"
 		};
 	}
+	async checkPortableSkill() {
+		const { portable } = getAgentSkillPaths(this.cwd);
+		try {
+			await access(portable);
+			return {
+				name: "Portable Agent Skill",
+				status: "ok",
+				path: AGENTS_SKILL_REL
+			};
+		} catch {
+			return {
+				name: "Portable Agent Skill",
+				status: "warn",
+				message: "not installed",
+				path: AGENTS_SKILL_REL,
+				suggestion: "Run: tbd setup --auto"
+			};
+		}
+	}
 	async checkClaudeSkill() {
 		const claudePaths = getClaudePaths(this.cwd);
 		try {
@@ -6926,6 +7294,25 @@ var DoctorHandler = class extends BaseCommand {
 			};
 		}
 	}
+	async checkCodexHooks() {
+		const codexPaths = getCodexPaths(this.cwd);
+		try {
+			await access(codexPaths.hooks);
+			return {
+				name: "Codex hooks",
+				status: "ok",
+				path: CODEX_HOOKS_REL
+			};
+		} catch {
+			return {
+				name: "Codex hooks",
+				status: "warn",
+				message: "not installed",
+				path: CODEX_HOOKS_REL,
+				suggestion: "Run: tbd setup --auto"
+			};
+		}
+	}
 	async checkCodexAgents() {
 		const agentsPath = getAgentsMdPath(this.cwd);
 		try {
@@ -6957,24 +7344,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",
@@ -7017,10 +7431,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.
 	*/
@@ -7038,7 +7522,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",
@@ -7081,7 +7565,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,
@@ -7094,14 +7578,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)`,
@@ -7127,7 +7611,7 @@ var DoctorHandler = class extends BaseCommand {
 	async checkRemoteSyncBranch() {
 		const syncBranch = this.config?.sync.branch ?? "tbd-sync";
 		const remote = this.config?.sync.remote ?? "origin";
-		const remoteHealth = await checkRemoteBranchHealth(remote, syncBranch);
+		const remoteHealth = await checkRemoteBranchHealth(remote, syncBranch, this.cwd);
 		if (remoteHealth.exists) {
 			if (remoteHealth.diverged) return {
 				name: "Remote sync branch",
@@ -7141,7 +7625,7 @@ var DoctorHandler = class extends BaseCommand {
 				message: `${remote}/${syncBranch}`
 			};
 		}
-		if ((await checkLocalBranchHealth(syncBranch)).exists) return {
+		if ((await checkLocalBranchHealth(syncBranch, this.cwd)).exists) return {
 			name: "Remote sync branch",
 			status: "warn",
 			message: `${remote}/${syncBranch} not found`,
@@ -7170,7 +7654,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`,
@@ -7316,6 +7800,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:")}`);
@@ -7451,9 +7936,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),
@@ -7478,10 +7963,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();
@@ -7507,6 +7992,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}`);
@@ -7514,24 +8000,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}`);
 	}
 };
@@ -7651,14 +8137,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);
+			});
 		}
 	}
 	/**
@@ -7666,7 +8156,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,
@@ -7677,7 +8166,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;
@@ -8323,7 +8815,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;
@@ -8333,6 +8830,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}`, {
@@ -8396,6 +8900,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",
@@ -8441,6 +8962,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) {
@@ -9011,7 +9541,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();
@@ -9863,16 +10394,89 @@ async function getShortcutDirectory(quiet = false) {
 	return generateShortcutDirectory(shortcuts, guidelines);
 }
 /**
-* Get the tbd section content for AGENTS.md (Codex integration).
-* Loads from SKILL.md, strips frontmatter, and wraps in TBD INTEGRATION markers.
+* DO NOT EDIT marker inserted after the frontmatter of every generated SKILL.md.
+* Formatted to match flowmark output.
+*/
+const SKILL_DO_NOT_EDIT_MARKER = "<!-- DO NOT EDIT: Generated by tbd setup.\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
+* frontmatter. This is the single source for every skill surface (the portable
+* .agents/skills install and the .claude/skills mirror) so they stay identical.
 *
-* @param quiet - If true, suppress auto-sync output (default: false)
+* @param quiet - If true, suppress auto-sync output.
 */
-async function getCodexTbdSection(quiet = false) {
-	let content = stripFrontmatter(await loadSkillContent());
+async function buildSkillPayload(quiet = false) {
+	let skillContent = await loadSkillContent();
 	const directory = await getShortcutDirectory(quiet);
-	if (directory) content = content.trimEnd() + "\n\n" + directory + "\n";
-	return `<!-- BEGIN TBD INTEGRATION -->\n${content}<!-- END TBD INTEGRATION -->\n`;
+	if (directory) skillContent = skillContent.trimEnd() + "\n\n" + directory;
+	skillContent = insertAfterFrontmatter(skillContent, SKILL_DO_NOT_EDIT_MARKER);
+	return skillContent.trimEnd() + "\n";
+}
+/**
+* Write a generated SKILL.md payload to a target path, creating parent dirs.
+*/
+async function writeSkillFile(targetPath, payload) {
+	await mkdir(dirname(targetPath), { recursive: true });
+	await writeFile(targetPath, payload);
+}
+/**
+* AGENTS.md managed-block markers. `CODEX_BEGIN_MARKER` is the stable PREFIX of
+* the begin line — the metadata (`format=fNN surface=agents-md`) follows it on the
+* same line, e.g. `<!-- BEGIN TBD INTEGRATION format=f02 surface=agents-md -->`.
+* Cleanup/upgrade code matches on this prefix so it finds both legacy
+* (`<!-- BEGIN TBD INTEGRATION -->`) and current marked blocks.
+*/
+const CODEX_BEGIN_MARKER = "<!-- BEGIN TBD INTEGRATION";
+const CODEX_END_MARKER = "<!-- END TBD INTEGRATION -->";
+/** The full begin marker line for newly generated blocks. */
+const CODEX_BEGIN_LINE = `${CODEX_BEGIN_MARKER} format=${AGENT_INTEGRATION_FORMAT} surface=agents-md -->`;
+/** Numeric value of an `fNN` format string, for ordering comparisons. */
+function formatToNumber(format) {
+	return Number.parseInt(format.replace(/^f/, ""), 10);
+}
+/**
+* Read the integration format (`fNN`) stamped in a generated artifact's begin
+* marker. Returns `f01` for a legacy marked block with no `format=` field, or
+* null when there is no tbd-managed block at all.
+*/
+function parseIntegrationFormat(content) {
+	const match = /format=f(\d+)/.exec(content);
+	if (match?.[1]) return `f${match[1]}`;
+	return content.includes(CODEX_BEGIN_MARKER) ? "f01" : null;
+}
+/**
+* Forward-compatibility guard. If a generated artifact was written by a NEWER
+* tbd than this one understands, refuse to rewrite it and tell the user to
+* upgrade tbd — overwriting would downgrade a newer managed format. This is what
+* makes pinning safe on a team: an older tbd fails loudly instead of clobbering.
+*/
+function assertNotNewerFormat(content, artifact) {
+	const format = parseIntegrationFormat(content);
+	if (format !== null && formatToNumber(format) > formatToNumber(AGENT_INTEGRATION_FORMAT)) throw new CLIError(`${artifact} was generated by a newer tbd (integration format ${format}; this tbd supports up to ${AGENT_INTEGRATION_FORMAT}).\nUpgrade tbd to manage it: npm install -g get-tbd@latest`);
+}
+/**
+* Get the tbd managed block for AGENTS.md.
+*
+* This is a COMPACT always-on bootstrap, not a copy of the full skill: it names
+* tbd, states the operating rule, and points to the CLI commands that provide
+* progressive disclosure (`tbd prime`, `tbd skill`, `tbd shortcut/guidelines
+* --list`). The full skill body lives in the SKILL.md surfaces, not here, so the
+* block stays well under the AGENTS.md prompt-budget guidance.
+*/
+function getCodexTbdSection() {
+	return `${CODEX_BEGIN_LINE}\n## tbd
+
+This repository uses **tbd** for git-native issue tracking (beads), spec-driven
+planning, and on-demand engineering guidelines.
+As the agent, you operate tbd on the user’s behalf — translate their requests into tbd
+actions rather than telling them to run commands.
+
+- Run \`tbd prime\` to load current project state and the full tbd workflow.
+- Run \`tbd skill\` for the complete reusable tbd skill instructions.
+- Run \`tbd shortcut --list\` and \`tbd guidelines --list\` for on-demand resources.
+- Track all work as beads: \`tbd create\`, \`tbd ready\`, \`tbd close\`, and \`tbd sync\`.
+\n${CODEX_END_MARKER}\n`;
 }
 /**
 * Script to ensure tbd CLI is installed and run tbd prime.
@@ -9884,82 +10488,32 @@ async function getCodexTbdSection(quiet = false) {
 *   tbd-session.sh --brief   # Ensure tbd + run tbd prime --brief (for PreCompact)
 */
 const TBD_SESSION_SCRIPT = `#!/bin/bash
-# Ensure tbd CLI is installed and run tbd prime for Claude Code sessions
-# Installed by: tbd setup --auto
-# This script runs on SessionStart and PreCompact
-
-# Get npm global bin directory (if npm is available)
-NPM_GLOBAL_BIN=""
-if command -v npm &> /dev/null; then
-    NPM_PREFIX=$(npm config get prefix 2>/dev/null)
-    if [ -n "$NPM_PREFIX" ] && [ -d "$NPM_PREFIX/bin" ]; then
-        NPM_GLOBAL_BIN="$NPM_PREFIX/bin"
-    fi
-fi
-
-# Add common binary locations to PATH (persists for entire script)
-# Include npm global bin if found
-export PATH="$NPM_GLOBAL_BIN:$HOME/.local/bin:$HOME/bin:/usr/local/bin:$PATH"
-
-# Function to ensure tbd is available
-ensure_tbd() {
-    # Check if tbd is already installed
-    if command -v tbd &> /dev/null; then
-        return 0
-    fi
-
-    echo "[tbd] CLI not found, installing..."
+# Ensure the tbd CLI is available and run \`tbd prime\`.
+# Installed by: tbd setup --auto. Runs on SessionStart and PreCompact.
+#
+# Local-first, then a VERSION-PINNED zero-install fallback. Pinning is both a
+# supply-chain control (an unpinned runner re-resolves to latest on every run
+# and bypasses any cool-off) and a consistency control (every teammate and agent
+# runs the same tbd version).
 
-    # Try npm first (most common for Node.js tools)
-    if command -v npm &> /dev/null; then
-        echo "[tbd] Installing via npm..."
-        npm install -g get-tbd 2>/dev/null || {
-            # If global install fails (permissions), try local install
-            echo "[tbd] Global npm install failed, trying user install..."
-            mkdir -p ~/.local/bin
-            npm install --prefix ~/.local get-tbd
-            # Create symlink if needed
-            if [ -f ~/.local/node_modules/.bin/tbd ]; then
-                ln -sf ~/.local/node_modules/.bin/tbd ~/.local/bin/tbd
-            fi
-        }
-    elif command -v pnpm &> /dev/null; then
-        echo "[tbd] Installing via pnpm..."
-        pnpm add -g get-tbd
-    elif command -v yarn &> /dev/null; then
-        echo "[tbd] Installing via yarn..."
-        yarn global add get-tbd
-    else
-        echo "[tbd] ERROR: No package manager found (npm, pnpm, or yarn required)"
-        echo "[tbd] Please install Node.js and npm, then run: npm install -g get-tbd"
-        return 1
-    fi
+# Prefer common local bin locations.
+export PATH="$HOME/.local/bin:$HOME/bin:/usr/local/bin:$PATH"
 
-    # Verify installation
-    if command -v tbd &> /dev/null; then
-        echo "[tbd] Successfully installed to $(which tbd)"
-        return 0
-    else
-        echo "[tbd] WARNING: tbd installed but not found in PATH"
-        echo "[tbd] Checking common locations..."
-        # Try to find and add to path (include npm global bin)
-        for dir in "$NPM_GLOBAL_BIN" ~/.local/bin ~/.local/node_modules/.bin /usr/local/bin; do
-            if [ -n "$dir" ] && [ -x "$dir/tbd" ]; then
-                export PATH="$dir:$PATH"
-                echo "[tbd] Found at $dir/tbd"
-                return 0
-            fi
-        done
-        echo "[tbd] Could not locate tbd after installation"
-        return 1
-    fi
-}
+# Local-first: use tbd if it is already on PATH.
+if command -v tbd &> /dev/null; then
+    tbd prime "$@"
+    exit $?
+fi
 
-# Main
-ensure_tbd || exit 1
+# Pinned zero-install fallback. Never use an unpinned runner here.
+if command -v npx &> /dev/null; then
+    npx --yes get-tbd@${VERSION} prime "$@"
+    exit $?
+fi
 
-# Run tbd prime with any passed arguments (e.g., --brief for PreCompact)
-tbd prime "$@"
+echo "[tbd] tbd CLI not found and npx is unavailable."
+echo "[tbd] Install it with: npm install -g get-tbd@${VERSION}"
+exit 1
 `;
 /**
 * Claude Code session hooks configuration.
@@ -10049,22 +10603,14 @@ async function loadBundledScript(name) {
 	throw new Error(`Bundled script not found: ${name}`);
 }
 /**
-* AGENTS.md integration markers for Codex/Factory.ai
-* Content is now generated dynamically from SKILL.md via getCodexTbdSection()
-*/
-const CODEX_BEGIN_MARKER = "<!-- BEGIN TBD INTEGRATION -->";
-const CODEX_END_MARKER = "<!-- END TBD INTEGRATION -->";
-/**
 * Generate a new AGENTS.md file with tbd integration.
-*
-* @param quiet - If true, suppress auto-sync output (default: false)
 */
-async function getCodexNewAgentsFile(quiet = false) {
+function getCodexNewAgentsFile() {
 	return `# Project Instructions for AI Agents
 
 This file provides instructions and context for AI coding agents working on this project.
 
-${await getCodexTbdSection(quiet)}
+${getCodexTbdSection()}
 ## Build & Test
 
 _Add your build and test commands here_
@@ -10085,6 +10631,54 @@ _Add your project-specific conventions here_
 `;
 }
 /**
+* Codex project-local script paths (relative to repo root). Codex hooks
+* reference ONLY these `.codex/` paths, never `.claude/`, so Codex setup stays
+* independent of Claude Code setup.
+*/
+const CODEX_SESSION_SCRIPT_REL = ".codex/tbd-session.sh";
+const CODEX_CLOSING_REMINDER_REL = ".codex/tbd-closing-reminder.sh";
+const CODEX_GH_CLI_SCRIPT_REL = ".codex/ensure-gh-cli.sh";
+/**
+* Build the Codex hooks.json content. Codex uses the same lifecycle event
+* schema as Claude Code (command handlers), so tbd's hooks map almost 1:1:
+* SessionStart and PreCompact run `tbd prime`, PostToolUse reminds about sync
+* after `git push`, and (when enabled) a second SessionStart entry ensures gh.
+*/
+function getCodexHooksConfig(useGhCli) {
+	const sessionStart = [{
+		matcher: "",
+		hooks: [{
+			type: "command",
+			command: `bash ${CODEX_SESSION_SCRIPT_REL}`
+		}]
+	}];
+	if (useGhCli) sessionStart.push({
+		matcher: "",
+		hooks: [{
+			type: "command",
+			command: `bash ${CODEX_GH_CLI_SCRIPT_REL}`,
+			timeout: 120
+		}]
+	});
+	return { hooks: {
+		SessionStart: sessionStart,
+		PreCompact: [{
+			matcher: "",
+			hooks: [{
+				type: "command",
+				command: `bash ${CODEX_SESSION_SCRIPT_REL} --brief`
+			}]
+		}],
+		PostToolUse: [{
+			matcher: "Bash",
+			hooks: [{
+				type: "command",
+				command: `bash ${CODEX_CLOSING_REMINDER_REL}`
+			}]
+		}]
+	} };
+}
+/**
 * Legacy script patterns to clean up from .claude/scripts/
 * These were used in older versions of tbd before hooks moved to `tbd prime`
 */
@@ -10345,13 +10939,7 @@ var SetupClaudeHandler = class extends BaseCommand {
 			await writeFile(claudePaths.closingReminder, TBD_CLOSE_PROTOCOL_SCRIPT);
 			await chmod(claudePaths.closingReminder, 493);
 			this.output.success("Installed sync reminder hook script");
-			await mkdir(dirname(skillPath), { recursive: true });
-			let skillContent = await loadSkillContent();
-			const directory = await getShortcutDirectory(this.ctx.quiet);
-			if (directory) skillContent = skillContent.trimEnd() + "\n\n" + directory;
-			skillContent = insertAfterFrontmatter(skillContent, "<!-- DO NOT EDIT: Generated by tbd setup.\nRun 'tbd setup' to update.\n-->");
-			skillContent = skillContent.trimEnd() + "\n";
-			await writeFile(skillPath, skillContent);
+			await writeSkillFile(skillPath, await buildSkillPayload(this.ctx.quiet));
 			this.output.success("Installed skill file");
 			this.output.info(`  ${skillPath}`);
 			this.output.info("");
@@ -10384,16 +10972,93 @@ var SetupCodexHandler = class extends BaseCommand {
 		this.projectDir = dir;
 	}
 	async run(options) {
-		const agentsPath = join(this.projectDir ?? process.cwd(), "AGENTS.md");
+		const cwd = this.projectDir ?? process.cwd();
+		const agentsPath = join(cwd, "AGENTS.md");
 		if (options.check) {
 			await this.checkCodexSetup(agentsPath);
 			return;
 		}
 		if (options.remove) {
 			await this.removeCodexSection(agentsPath);
+			await this.removeCodexHooks(cwd);
 			return;
 		}
 		await this.installCodexSection(agentsPath);
+		await this.installCodexHooks(cwd);
+	}
+	/**
+	* Read the use_gh_cli setting; defaults to true (so fresh setup installs it).
+	*/
+	async getUseGhCliSetting(cwd) {
+		try {
+			const tbdRoot = await findTbdRoot(cwd);
+			if (!tbdRoot) return true;
+			return (await readConfig(tbdRoot)).settings.use_gh_cli ?? true;
+		} catch {
+			return true;
+		}
+	}
+	/**
+	* Install Codex lifecycle hooks: writes .codex/ scripts and a .codex/hooks.json
+	* (merged idempotently with any user hooks). Scripts reuse the same bodies as
+	* the Claude install but live under .codex/ so Codex never references .claude/.
+	*/
+	async installCodexHooks(cwd) {
+		if (this.checkDryRun("Would install Codex hooks", { path: "./.codex/hooks.json" })) return;
+		const codexPaths = getCodexPaths(cwd);
+		await mkdir(codexPaths.dir, { recursive: true });
+		const useGhCli = await this.getUseGhCliSetting(cwd);
+		await writeFile(join(cwd, CODEX_SESSION_SCRIPT_REL), TBD_SESSION_SCRIPT);
+		await chmod(join(cwd, CODEX_SESSION_SCRIPT_REL), 493);
+		await writeFile(join(cwd, CODEX_CLOSING_REMINDER_REL), TBD_CLOSE_PROTOCOL_SCRIPT);
+		await chmod(join(cwd, CODEX_CLOSING_REMINDER_REL), 493);
+		if (useGhCli) {
+			const ghScriptContent = await loadBundledScript("ensure-gh-cli.sh");
+			await writeFile(join(cwd, CODEX_GH_CLI_SCRIPT_REL), ghScriptContent);
+			await chmod(join(cwd, CODEX_GH_CLI_SCRIPT_REL), 493);
+		} else await rm(join(cwd, CODEX_GH_CLI_SCRIPT_REL), { force: true });
+		let existing = {};
+		try {
+			existing = JSON.parse(await readFile(codexPaths.hooks, "utf-8"));
+		} catch {}
+		const isTbdOwned = (entry) => {
+			return (entry.hooks ?? []).some((h) => h.command?.includes(".codex/"));
+		};
+		const merged = { ...existing.hooks ?? {} };
+		const tbdHooks = getCodexHooksConfig(useGhCli).hooks;
+		for (const [event, entries] of Object.entries(tbdHooks)) merged[event] = [...(merged[event] ?? []).filter((e) => !isTbdOwned(e)), ...entries];
+		await writeFile(codexPaths.hooks, JSON.stringify({
+			...existing,
+			hooks: merged
+		}, null, 2) + "\n");
+		this.output.success("Installed Codex hooks (.codex/hooks.json)");
+	}
+	/**
+	* Remove tbd-owned Codex hook entries and scripts, preserving user hooks.
+	*/
+	async removeCodexHooks(cwd) {
+		const codexPaths = getCodexPaths(cwd);
+		try {
+			const existing = JSON.parse(await readFile(codexPaths.hooks, "utf-8"));
+			const hooks = existing.hooks ?? {};
+			for (const event of Object.keys(hooks)) {
+				const kept = (hooks[event] ?? []).filter((entry) => {
+					return !(entry.hooks ?? []).some((h) => h.command?.includes(".codex/"));
+				});
+				if (kept.length === 0) delete hooks[event];
+				else hooks[event] = kept;
+			}
+			if (Object.keys(hooks).length === 0) await rm(codexPaths.hooks, { force: true });
+			else await writeFile(codexPaths.hooks, JSON.stringify({
+				...existing,
+				hooks
+			}, null, 2) + "\n");
+		} catch {}
+		for (const rel of [
+			CODEX_SESSION_SCRIPT_REL,
+			CODEX_CLOSING_REMINDER_REL,
+			CODEX_GH_CLI_SCRIPT_REL
+		]) await rm(join(cwd, rel), { force: true });
 	}
 	async checkCodexSetup(agentsPath) {
 		const agentsRelPath = "./AGENTS.md";
@@ -10478,8 +11143,9 @@ var SetupCodexHandler = class extends BaseCommand {
 				existingContent = await readFile(agentsPath, "utf-8");
 			} catch {}
 			let newContent;
-			const tbdSection = await getCodexTbdSection(this.ctx.quiet);
+			const tbdSection = getCodexTbdSection();
 			if (existingContent) if (existingContent.includes(CODEX_BEGIN_MARKER)) {
+				assertNotNewerFormat(existingContent, "AGENTS.md");
 				newContent = this.updatetbdSection(existingContent, tbdSection);
 				await writeFile(agentsPath, newContent);
 				this.output.success("Updated existing tbd section in AGENTS.md");
@@ -10489,7 +11155,7 @@ var SetupCodexHandler = class extends BaseCommand {
 				this.output.success("Added tbd section to existing AGENTS.md");
 			}
 			else {
-				await writeFile(agentsPath, await getCodexNewAgentsFile(this.ctx.quiet));
+				await writeFile(agentsPath, getCodexNewAgentsFile());
 				this.output.success("Created new AGENTS.md with tbd integration");
 			}
 			this.output.info(`  File: ${agentsPath}`);
@@ -10552,25 +11218,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 (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 (needsConfigWrite) {
+			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);
@@ -10718,7 +11385,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)",
@@ -10749,7 +11416,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 {
@@ -10859,9 +11529,11 @@ var SetupAutoHandler = class extends BaseCommand {
 			console.log(colors.dim(`Cleaned up legacy ${parts.join(" and ")}`));
 		}
 		await this.syncDocs(cwd);
-		const claudeResult = await this.setupClaudeIfDetected(cwd);
+		const targeting = this.resolveTargeting();
+		await this.installPortableSkill(cwd);
+		const claudeResult = await this.setupClaudeIfDetected(cwd, targeting.claude);
 		results.push(claudeResult);
-		const codexResult = await this.setupCodexIfDetected(cwd);
+		const codexResult = await this.setupCodexIfDetected(cwd, targeting.codex);
 		results.push(codexResult);
 		const installed = results.filter((r) => r.installed && !r.alreadyInstalled);
 		const alreadyInstalled = results.filter((r) => r.alreadyInstalled);
@@ -10904,24 +11576,59 @@ var SetupAutoHandler = class extends BaseCommand {
 		if (result.pruned.length > 0) console.log(colors.dim(`Pruned ${result.pruned.length} stale config entry/entries`));
 		if (result.errors.length > 0) for (const { path, error } of result.errors) console.log(colors.warn(`Warning: ${path}: ${error}`));
 	}
-	async setupClaudeIfDetected(cwd) {
+	/**
+	* Write the canonical portable Agent Skill to .agents/skills/tbd/SKILL.md.
+	* Runs for every initialized repo, independent of agent detection, so the
+	* skill is portable across Codex, Gemini CLI, Cursor, and other clients.
+	*/
+	async installPortableSkill(cwd) {
+		const colors = this.output.getColors();
+		if (this.checkDryRun("Would install portable Agent Skill", { path: AGENTS_SKILL_DISPLAY })) return;
+		const { portable } = getAgentSkillPaths(cwd);
+		await writeSkillFile(portable, await buildSkillPayload(this.ctx.quiet));
+		console.log(`  ${colors.success("✓")} Portable Agent Skill (${AGENTS_SKILL_DISPLAY})`);
+	}
+	/**
+	* Resolve which agent surfaces to install from the explicit targeting flags.
+	* `--all`/`--claude`/`--codex` force surfaces on (and suppress auto-detection
+	* of untargeted surfaces); `--skip-claude`/`--skip-codex` force them off; with
+	* no targeting flag each surface falls back to detection-based auto behavior.
+	*/
+	resolveTargeting() {
+		const opts = this.cmd.optsWithGlobals();
+		const all = opts.all === true;
+		const anyPositive = all || opts.claude === true || opts.codex === true;
+		const resolve = (on, skip) => {
+			if (skip === true) return "off";
+			if (on === true || all) return "on";
+			return anyPositive ? "off" : "auto";
+		};
+		return {
+			claude: resolve(opts.claude, opts.skipClaude),
+			codex: resolve(opts.codex, opts.skipCodex)
+		};
+	}
+	async setupClaudeIfDetected(cwd, mode) {
 		const result = {
 			name: "Claude Code",
 			detected: false,
 			installed: false,
 			alreadyInstalled: false
 		};
-		const hasClaudeDir = await pathExists(GLOBAL_CLAUDE_DIR);
-		const hasClaudeEnv = Object.keys(process.env).some((k) => k.startsWith("CLAUDE_"));
-		if (!hasClaudeDir && !hasClaudeEnv) return result;
+		if (mode === "off") return result;
+		if (mode === "auto") {
+			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);
@@ -10933,17 +11640,20 @@ var SetupAutoHandler = class extends BaseCommand {
 		}
 		return result;
 	}
-	async setupCodexIfDetected(cwd) {
+	async setupCodexIfDetected(cwd, mode) {
 		const result = {
 			name: "Codex/AGENTS.md",
 			detected: false,
 			installed: false,
 			alreadyInstalled: false
 		};
+		if (mode === "off") return result;
 		const agentsPath = getAgentsMdPath(cwd);
-		const hasAgentsMd = await pathExists(agentsPath);
-		const hasCodexEnv = Object.keys(process.env).some((k) => k.startsWith("CODEX_"));
-		if (!hasAgentsMd && !hasCodexEnv) return result;
+		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;
+		}
 		result.detected = true;
 		if (hasAgentsMd) {
 			if ((await readFile(agentsPath, "utf-8")).includes("BEGIN TBD INTEGRATION")) result.alreadyInstalled = true;
@@ -10954,12 +11664,13 @@ var SetupAutoHandler = class extends BaseCommand {
 			await handler.run({});
 			result.installed = true;
 		} catch (error) {
+			if (error instanceof CLIError) throw error;
 			result.error = error.message;
 		}
 		return result;
 	}
 };
-const setupCommand = new Command("setup").description("Configure tbd integration with editors and tools").option("--auto", "Non-interactive mode with smart defaults (for agents/scripts)").option("--interactive", "Interactive mode with prompts (for humans)").option("--from-beads", "Migrate from Beads to tbd").option("--prefix <name>", "Project prefix for issue IDs (required for fresh setup)").option("--force", "Allow non-recommended prefix format (not 2-8 alphabetic)").option("--no-gh-cli", "Disable automatic GitHub CLI installation hook").action(async (options, command) => {
+const setupCommand = new Command("setup").description("Configure tbd integration with editors and tools").option("--auto", "Non-interactive mode with smart defaults (for agents/scripts)").option("--interactive", "Interactive mode with prompts (for humans)").option("--from-beads", "Migrate from Beads to tbd").option("--prefix <name>", "Project prefix for issue IDs (required for fresh setup)").option("--force", "Allow non-recommended prefix format (not 2-8 alphabetic)").option("--no-gh-cli", "Disable automatic GitHub CLI installation hook").option("--all", "Install every supported agent surface (Claude + Codex)").option("--claude", "Install the Claude Code surface (skill mirror + hooks)").option("--codex", "Install the Codex surface (AGENTS.md block + .codex hooks)").option("--skip-claude", "Skip the Claude Code surface even if detected").option("--skip-codex", "Skip the Codex surface even if detected").action(async (options, command) => {
 	if (options.auto || options.interactive) {
 		await new SetupDefaultHandler(command).run(options);
 		return;
@@ -11008,7 +11719,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,
@@ -11020,7 +11730,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;