get-tbd 0.2.1 → 0.2.3

package/dist/bin.mjs

@@ -6,7 +6,7 @@ import path, { basename, dirname, isAbsolute, join, normalize, parse, relative,
 import fs, { createWriteStream } from "node:fs";
 import process$1 from "node:process";
 import matter from "gray-matter";
-import os, { homedir } from "node:os";
+import os from "node:os";
 import tty from "node:tty";
 import { access, chmod, cp, mkdir, readFile, readdir, realpath, rename, rm, rmdir, stat, unlink } from "node:fs/promises";
 import { Readable } from "node:stream";
@@ -14104,7 +14104,7 @@ function serializeIssue(issue) {
 * Package version, derived from git at build time.
 * Format: X.Y.Z for releases, X.Y.Z-dev.N.hash for dev builds.
 */
-const VERSION$1 = "0.2.1";
+const VERSION$1 = "0.2.3";
 
 //#endregion
 //#region src/cli/lib/version.ts
@@ -14119,18 +14119,38 @@ const VERSION$1 = "0.2.1";
 * No git dependency at runtime - git version is computed at build time
 * or by the dev script wrapper.
 */
+/** Read the package.json version (dev fallback, when running from source). */
+function readPackageVersion() {
+	return createRequire(import.meta.url)("../../../package.json").version;
+}
 /**
 * Get the CLI version.
 */
 function getVersion() {
 	if (VERSION$1 !== "development") return VERSION$1;
 	if (process.env.TBD_DEV_VERSION) return process.env.TBD_DEV_VERSION;
-	return createRequire(import.meta.url)("../../../package.json").version;
+	return readPackageVersion();
+}
+/**
+* Clean published npm version for pinned `get-tbd@<version>` fallbacks (the
+* session script and any other generated install hint). Always the package.json
+* semver — NOT the git-describe display version, which for a local/dirty build
+* is an unpublished string like `0.2.3-dev.2.abc1234-dirty` that npm cannot
+* install and that would churn generated files on every build.
+*/
+function getPinnedNpmVersion() {
+	return "0.2.3";
 }
 /**
 * CLI version - use this instead of importing VERSION directly from index.ts
 */
 const VERSION = getVersion();
+/**
+* Pinned npm version for `get-tbd@<version>` install fallbacks. Use this (not
+* VERSION) anywhere a version is written into a generated file as an installable
+* pin, so dev/dirty builds do not stamp unpublished, churn-prone strings.
+*/
+const PINNED_NPM_VERSION = getPinnedNpmVersion();
 
 //#endregion
 //#region ../../node_modules/.pnpm/picocolors@1.1.1/node_modules/picocolors/picocolors.js
@@ -97643,6 +97663,18 @@ function buildSharedTbdPaths(gitCommonDir) {
 async function resolveSharedTbdPaths(baseDir) {
 	return buildSharedTbdPaths(await resolveGitCommonDir(baseDir));
 }
+/**
+* True when the Git common dir lives outside the project checkout — the linked
+* worktree shape where the checkout can be writable while `$GIT_COMMON_DIR/tbd`
+* (shared sync state + lock) is not. This is the generic signal behind the
+* Codex-sandbox case in #164; it does not depend on any `CODEX_*` env var, which
+* that sandbox did not expose. Used by both the `doctor` lock-writability finding
+* and the write-side `SharedLockUnwritableError` so their wording matches.
+*/
+function isCommonDirOutsideProject(gitCommonDir, projectRoot) {
+	const rel = relative(resolve(projectRoot), resolve(gitCommonDir));
+	return rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel);
+}
 /** The workspaces directory name within .tbd/ */
 const WORKSPACES_DIR_NAME = "workspaces";
 /** Full path to workspaces directory: .tbd/workspaces/ */
@@ -99934,7 +99966,7 @@ const FIELD_STRATEGIES = {
 	priority: "lww",
 	assignee: "lww",
 	parent_id: "lww",
-	child_order_hints: "lww",
+	child_order_hints: "union",
 	updated_at: "max",
 	closed_at: "lww",
 	close_reason: "lww",
@@ -100066,7 +100098,7 @@ function mergeIssues(base, local, remote) {
 				}
 				break;
 			case "union":
-				merged[key] = unionArrays(localVal, remoteVal);
+				merged[key] = unionArrays(Array.isArray(localVal) ? localVal : [], Array.isArray(remoteVal) ? remoteVal : []);
 				break;
 			case "max":
 				merged[key] = Math.max(localVal, remoteVal);
@@ -100135,30 +100167,29 @@ function isNonFastForward(error) {
 async function pushWithRetry(syncBranch, remote, onMergeNeeded, baseDir) {
 	const refspec = `refs/heads/${syncBranch}:refs/heads/${syncBranch}`;
 	const dirArgs = baseDir ? ["-C", baseDir] : [];
+	const allConflicts = [];
 	for (let attempt = 1; attempt <= MAX_PUSH_RETRIES; attempt++) try {
 		await git(...dirArgs, "push", remote, refspec);
 		return {
 			success: true,
-			attempt
+			attempt,
+			conflicts: allConflicts.length > 0 ? allConflicts : void 0
 		};
 	} catch (error) {
 		if (!isNonFastForward(error)) return {
 			success: false,
 			attempt,
-			error: error instanceof Error ? error.message : String(error)
+			error: error instanceof Error ? error.message : String(error),
+			conflicts: allConflicts.length > 0 ? allConflicts : void 0
 		};
 		if (attempt === MAX_PUSH_RETRIES) return {
 			success: false,
 			attempt,
-			error: `Push failed after ${MAX_PUSH_RETRIES} attempts. Remote has conflicting changes.`
+			error: `Push failed after ${MAX_PUSH_RETRIES} attempts. Remote has conflicting changes.`,
+			conflicts: allConflicts.length > 0 ? allConflicts : void 0
 		};
 		await git(...dirArgs, "fetch", remote, syncBranch);
-		const conflicts = await onMergeNeeded();
-		if (conflicts.length > 0) return {
-			success: false,
-			attempt,
-			conflicts
-		};
+		allConflicts.push(...await onMergeNeeded());
 	}
 	return {
 		success: false,
@@ -100692,6 +100723,52 @@ async function readBranchMapping(baseDir, ref) {
 		};
 	}
 }
+/**
+* Three-way merge a single bead read directly from git refs.
+*
+* Resolves the common ancestor with `git merge-base` and reads base/ours/theirs
+* from committed blobs (never the working tree), so a conflict-marker-corrupted
+* working file is never parsed. Feeds the field-level {@link mergeIssues} engine
+* a real base, which is what lets `union` fields (e.g. child_order_hints) combine
+* both sides instead of one side winning.
+*
+* Returns `null` when the bead does not exist on the `theirsRef` side (nothing to
+* merge — keep ours). Used by sync's conflict paths in place of git's line-based
+* text merge. See issue #155.
+*
+* @param repoDir - Directory to run git in (the data-sync worktree). `oursRef` and
+*   `theirsRef` (e.g. `HEAD`/`MERGE_HEAD`, or a branch and `origin/<branch>`) must
+*   resolve there.
+*/
+async function mergeBeadAcrossRefs(repoDir, issueId, oursRef, theirsRef) {
+	const path = `${DATA_SYNC_DIR}/issues/${issueId}.md`;
+	const ours = parseIssue(await git("-C", repoDir, "show", `${oursRef}:${path}`));
+	let theirsContent;
+	try {
+		theirsContent = await git("-C", repoDir, "show", `${theirsRef}:${path}`);
+	} catch (err) {
+		if (err instanceof GitError) return null;
+		throw err;
+	}
+	const theirs = parseIssue(theirsContent);
+	let baseSha = "";
+	try {
+		baseSha = (await git("-C", repoDir, "merge-base", oursRef, theirsRef)).trim();
+	} catch (err) {
+		if (exitCodeOf(err) !== 1) throw err;
+	}
+	let base = null;
+	if (baseSha) {
+		let baseContent = null;
+		try {
+			baseContent = await git("-C", repoDir, "show", `${baseSha}:${path}`);
+		} catch (err) {
+			if (!(err instanceof GitError)) throw err;
+		}
+		if (baseContent !== null) base = parseIssue(baseContent);
+	}
+	return mergeIssues(base, ours, theirs);
+}
 /** Preserve a losing issue version explicitly under attic/conflicts/. */
 async function preserveLosingVersion(dataSyncPath, loser) {
 	const conflictsDir = join(dataSyncPath, "attic", "conflicts");
@@ -100707,13 +100784,20 @@ async function preserveLosingVersion(dataSyncPath, loser) {
 * backup branch is created, so the pre-rescue HEAD is always recoverable and
 * the rescue is restartable.
 *
-* MUST be called while holding `withSharedDataSyncLock`. Aborts if the
-* data-sync worktree is dirty or has a merge in progress.
+* MUST be called while holding `withSharedDataSyncLock`. A merge in progress
+* aborts the rescue; a merely-dirty worktree does not — its uncommitted
+* tbd-owned data-sync changes are committed first (so the backup branch captures
+* them), while any dirty path outside the data-sync tree aborts. See issue #158.
 */
 async function rescueUnrelatedHistory(baseDir, remote = "origin", syncBranch = SYNC_BRANCH) {
 	const { sharedWorktreePath: worktreePath, sharedDataSyncDir: dataSyncPath } = await getSharedPaths(baseDir);
-	if ((await git("-C", worktreePath, "status", "--porcelain")).trim()) throw new Error("Refusing to rescue: the tbd-sync worktree has uncommitted changes. Commit or stash them, then retry.");
-	if (await git("-C", worktreePath, "rev-parse", "-q", "--verify", "MERGE_HEAD").then(() => true).catch(() => false)) throw new Error("Refusing to rescue: a merge is in progress in the tbd-sync worktree. Resolve or abort it, then retry.");
+	if (await git("-C", worktreePath, "rev-parse", "-q", "--verify", "MERGE_HEAD").then(() => true).catch(() => false)) throw new Error(`Refusing to rescue: a merge is in progress in the tbd-sync worktree at ${worktreePath}. Run \`git -C "${worktreePath}" merge --abort\`, then re-run \`tbd doctor --fix\`.`);
+	if ((await git("-C", worktreePath, "status", "--porcelain")).trim()) {
+		const foreign = (await git("-C", worktreePath, "status", "--porcelain", "--", ".", `:!${DATA_SYNC_DIR}`)).trim();
+		if (foreign) throw new Error(`Refusing to rescue: the tbd-sync worktree has changes outside the data-sync tree:\n${foreign}\nRemove or commit them, then re-run \`tbd doctor --fix\`.`);
+		await git("-C", worktreePath, "add", "-A");
+		await gitCommit(worktreePath, "--no-verify", "-m", "tbd rescue: snapshot uncommitted data-sync state before rescue");
+	}
 	await gitNoPrompt("-C", baseDir, "fetch", remote, syncBranch);
 	const localIssues = await listIssues(dataSyncPath);
 	const localMapping = await loadIdMapping(dataSyncPath);
@@ -100981,12 +101065,59 @@ async function ensureCommonDirLayout(paths, config) {
 	return writeCommonDirLayout(paths, config);
 }
 /**
+* Error thrown when the shared data-sync lock cannot be created because the lock
+* path is not writable by this process (EPERM/EACCES).
+*
+* The common trigger is an agent sandbox (e.g. Codex) where the *checkout* is
+* writable but `$GIT_COMMON_DIR/tbd` — which holds the shared sync worktree and
+* the lock — lives in the user's original repo directory, outside the sandbox's
+* writable boundary. Read-only commands work, but any write needs the lock and
+* fails here. This is fatal for the command: without the lock we cannot safely
+* mutate shared state. See issue #164.
+*/
+var SharedLockUnwritableError = class extends Error {
+	constructor(code, paths, projectRoot) {
+		const outside = isCommonDirOutsideProject(paths.gitCommonDir, projectRoot);
+		const cause = outside ? `The checkout is writable, but the shared tbd state under ${paths.sharedTbdDir} is outside this process's writable area (a common agent-sandbox shape, e.g. Codex worktrees), so write commands cannot proceed.` : `The shared tbd state under ${paths.sharedTbdDir} is not writable by this process, so write commands cannot proceed.`;
+		const fix = outside ? `Fix: grant write access to ${paths.sharedTbdDir} — in an agent sandbox such as Codex add it to the writable roots, or re-run with sandbox escalation.` : `Fix: ensure ${paths.sharedTbdDir} is writable by this user (check filesystem permissions).`;
+		super(`Cannot acquire the shared tbd data-sync lock (${code}): ${paths.sharedLockPath}\n${cause}\n${fix} Run \`tbd doctor\` to confirm the diagnosis.`);
+		this.code = code;
+		this.name = "SharedLockUnwritableError";
+	}
+};
+/**
+* Return the EPERM/EACCES code if `error` is a filesystem permission error,
+* otherwise undefined. Used to translate raw lock-creation failures into a
+* clear, actionable error.
+*/
+function lockPermissionCode(error) {
+	const code = error?.code;
+	return code === "EPERM" || code === "EACCES" ? code : void 0;
+}
+/**
 * Run a critical section while holding the repo-scoped data-sync lock.
+*
+* A permission failure creating either the locks directory or the lock itself
+* is rethrown as a `SharedLockUnwritableError` with remediation. The lock-path
+* match keeps an unrelated EPERM thrown by `fn` (e.g. writing issue data) from
+* being misreported as a lock-writability problem.
 */
 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);
+	try {
+		await mkdir(paths.sharedLocksDir, { recursive: true });
+	} catch (error) {
+		const code = lockPermissionCode(error);
+		if (code) throw new SharedLockUnwritableError(code, paths, tbdRoot);
+		throw error;
+	}
+	try {
+		return await withLockfile(paths.sharedLockPath, fn, DATA_SYNC_LOCK_OPTIONS);
+	} catch (error) {
+		const code = lockPermissionCode(error);
+		if (code && error?.path === paths.sharedLockPath) throw new SharedLockUnwritableError(code, paths, tbdRoot);
+		throw error;
+	}
 }
 
 //#endregion
@@ -101354,6 +101485,20 @@ function notifyConfigMigrated(fromFormat, toFormat) {
 	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`);
 }
+/**
+* Emit a one-line stderr notice when a data command auto-materialized a missing
+* sync worktree at the point of use.
+*
+* The shared worktree can be absent in a fresh/ephemeral clone (or if it was
+* deleted). `withDataSyncContext` heals it transparently, but a silent heal on a
+* read/write command looks indistinguishable from "the tracker is empty" or "my
+* issue was saved normally" — the exact confusion reported in #135. A terse
+* stderr note keeps stdout (and JSON) clean while making the heal visible.
+*/
+function notifyWorktreeRepaired(status) {
+	if (status !== "missing" && status !== "prunable") return;
+	process.stderr.write(`• tbd-sync worktree was ${status} — auto-materialized it (fresh clone, or the worktree was removed).\n`);
+}
 async function assembleDataContext(tbdRoot, probe, repairedWorktreeStatus) {
 	const dataSyncDir = await resolveDataSyncDir(tbdRoot, { allowFallback: false });
 	return {
@@ -101402,7 +101547,10 @@ async function withDataSyncContext(tbdRoot, options, fn) {
 * migration or worktree repair.
 */
 async function loadDataContext(tbdRoot) {
-	return withDataSyncContext(tbdRoot, { lock: false }, async (context) => context);
+	return withDataSyncContext(tbdRoot, { lock: false }, async (context) => {
+		notifyWorktreeRepaired(context.repairedWorktreeStatus);
+		return context;
+	});
 }
 /**
 * Load unified command context with CLI options, data, and helper methods.
@@ -101492,7 +101640,8 @@ var CreateHandler = class extends BaseCommand {
 		let prefix;
 		let issue;
 		await this.execute(async () => {
-			await withDataSyncContext(tbdRoot, { lock: true }, async ({ dataSyncDir, config, mapping }) => {
+			await withDataSyncContext(tbdRoot, { lock: true }, async ({ dataSyncDir, config, mapping, repairedWorktreeStatus }) => {
+				notifyWorktreeRepaired(repairedWorktreeStatus);
 				prefix = config.display.id_prefix;
 				shortId = generateUniqueShortId(mapping);
 				addIdMapping(mapping, ulid, shortId);
@@ -104073,6 +104222,19 @@ async function workspaceExists(tbdRoot, name) {
 *
 * See: tbd-design.md §4.7 Sync Commands
 */
+/**
+* List bead files in a data-sync directory that fail to parse. Used as a
+* post-merge guard so sync never reports success over a corrupted store (e.g. a
+* bead left holding git conflict markers). See issue #155.
+*/
+async function findInvalidBeads(dataSyncDir) {
+	const invalid = [];
+	await listIssues(dataSyncDir, {
+		warnOnInvalid: false,
+		onInvalidIssue: (entry) => invalid.push(entry)
+	});
+	return invalid;
+}
 var SyncHandler = class extends BaseCommand {
 	dataSyncDir = "";
 	tbdRoot = "";
@@ -104218,7 +104380,7 @@ var SyncHandler = class extends BaseCommand {
 				this.output.debug("Remote branch does not exist");
 			}
 			if (behind > 0) {
-				const logOutput = await git("log", "--oneline", `${syncBranch}..${remote}/${syncBranch}`, "--limit=10");
+				const logOutput = await git("log", "--oneline", `${syncBranch}..${remote}/${syncBranch}`, "--max-count=10");
 				for (const line of logOutput.split("\n")) if (line) remoteChanges.push(line);
 			}
 		} catch {
@@ -104282,6 +104444,15 @@ var SyncHandler = class extends BaseCommand {
 			throw error;
 		}
 	}
+	/**
+	* Abort the sync if any bead file fails to parse, naming the offending
+	* file(s). Prevents the silent "received N updated" success over a store left
+	* corrupted by a merge. See issue #155.
+	*/
+	async assertNoCorruptBeads() {
+		const invalid = await findInvalidBeads(this.dataSyncDir);
+		if (invalid.length > 0) throw new SyncError(`Sync left ${invalid.length} unreadable bead file(s):\n` + invalid.map((i) => `  - ${i.file}: ${i.reason}`).join("\n") + `\n\nThis is a bug in tbd sync. Please report it and resolve the file(s) in:\n  ${this.worktreePath}`);
+	}
 	async pushChanges(syncBranch, remote) {
 		const spinner = this.output.spinner("Pushing to remote...");
 		try {
@@ -104311,8 +104482,8 @@ var SyncHandler = class extends BaseCommand {
 			}
 			const result = await this.doPushWithRetry(syncBranch, remote);
 			spinner.stop();
-			if (result.success) this.output.success(`Pushed ${ahead} commit(s) to ${remote}/${syncBranch}`);
-			else if (result.conflicts && result.conflicts.length > 0) this.output.warn(`Push completed with ${result.conflicts.length} conflict(s) (see attic for details)`);
+			if (result.success) if (result.conflicts && result.conflicts.length > 0) this.output.success(`Pushed to ${remote}/${syncBranch} (${result.conflicts.length} conflict(s) preserved in attic)`);
+			else this.output.success(`Pushed ${ahead} commit(s) to ${remote}/${syncBranch}`);
 			else throw new SyncError(`Failed to push: ${result.error}`);
 		} catch (error) {
 			spinner.stop();
@@ -104320,20 +104491,104 @@ var SyncHandler = class extends BaseCommand {
 			throw new SyncError(`Failed to push: ${error.message}`);
 		}
 	}
-	async doPushWithRetry(syncBranch, remote) {
-		return pushWithRetry(syncBranch, remote, async () => {
-			const conflicts = [];
-			const localIssues = await listIssues(this.dataSyncDir);
-			for (const localIssue of localIssues) try {
-				if (await git("show", `${remote}/${syncBranch}:${DATA_SYNC_DIR}/issues/${localIssue.id}.md`)) {
-					const result = mergeIssues(null, localIssue, await readIssue(this.dataSyncDir, localIssue.id));
+	/**
+	* Integrate the remote sync branch into the local worktree with a real git
+	* merge, resolving bead conflicts through the structured field-level engine
+	* (never git's line-based text merge), reconciling ID mappings, committing the
+	* result, and asserting no bead was left corrupt.
+	*
+	* Shared by the pull/full-sync path and the push-retry path so both integrate
+	* the remote identically — and so a rejected push actually advances local
+	* `tbd-sync` to include the remote before retrying, instead of looping on the
+	* same non-fast-forward commit. See issue #155.
+	*
+	* @returns field-level conflict entries (the caller preserves them in attic).
+	*/
+	async mergeRemoteIntoSyncBranch(syncBranch, remote) {
+		const worktreePath = this.worktreePath;
+		const conflicts = [];
+		let headBeforeMerge = "";
+		try {
+			headBeforeMerge = (await git("-C", worktreePath, "rev-parse", "HEAD")).trim();
+		} catch {}
+		try {
+			await git("-C", worktreePath, "merge", `${remote}/${syncBranch}`, "-m", "tbd sync: merge remote changes");
+			this.output.debug("Merged remote changes");
+			if (headBeforeMerge) await this.showGitLogDebug("Commits received", `${headBeforeMerge}..${syncBranch}`);
+			const postMergeIssues = await listIssues(this.dataSyncDir);
+			const postMergeMapping = await loadIdMapping(this.dataSyncDir);
+			let historicalMapping;
+			try {
+				const remoteIdsContent = await git("show", `${remote}/${syncBranch}:${DATA_SYNC_DIR}/mappings/ids.yml`);
+				if (remoteIdsContent) historicalMapping = parseIdMappingFromYaml(remoteIdsContent);
+			} catch {}
+			const reconcileResult = reconcileMappings(postMergeIssues.map((i) => i.id), postMergeMapping, historicalMapping);
+			const totalReconciled = reconcileResult.created.length + reconcileResult.recovered.length;
+			if (totalReconciled > 0) {
+				await saveIdMapping(this.dataSyncDir, postMergeMapping);
+				await git("-C", worktreePath, "add", "-A");
+				try {
+					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)`);
+			}
+		} catch {
+			this.output.info(`Merge conflict, attempting file-level resolution`);
+			const conflictedIds = (await git("-C", worktreePath, "diff", "--name-only", "--diff-filter=U", "--", `${DATA_SYNC_DIR}/issues`)).split("\n").map((f) => f.trim()).filter((f) => f.endsWith(".md")).map((f) => basename(f, ".md"));
+			for (const id of conflictedIds) {
+				let result;
+				try {
+					result = await mergeBeadAcrossRefs(worktreePath, id, "HEAD", "MERGE_HEAD");
+				} catch (error) {
+					throw new SyncError(`Failed to merge bead ${id} during sync: ${error.message}`);
+				}
+				if (result) {
 					await writeIssue(this.dataSyncDir, result.merged);
 					conflicts.push(...result.conflicts);
 				}
+			}
+			let conflictRemoteMapping;
+			try {
+				const remoteIdsContent = await git("show", `${remote}/${syncBranch}:${DATA_SYNC_DIR}/mappings/ids.yml`);
+				if (remoteIdsContent) {
+					conflictRemoteMapping = parseIdMappingFromYaml(remoteIdsContent);
+					const localMapping = resolveIdMappingConflicts(await readFile(join(this.dataSyncDir, "mappings", "ids.yml"), "utf-8"));
+					const mergedMapping = mergeIdMappings(localMapping, conflictRemoteMapping);
+					await saveIdMapping(this.dataSyncDir, mergedMapping);
+					this.output.debug(`Merged ID mappings: ${localMapping.shortToUlid.size} local + ${conflictRemoteMapping.shortToUlid.size} remote = ${mergedMapping.shortToUlid.size} total`);
+				}
+			} catch (error) {
+				this.output.debug(`Could not merge ids.yml: ${error.message}`);
+			}
+			{
+				const allIssues = await listIssues(this.dataSyncDir);
+				const currentMapping = await loadIdMapping(this.dataSyncDir);
+				const reconcileResult = reconcileMappings(allIssues.map((i) => i.id), currentMapping, conflictRemoteMapping);
+				if (reconcileResult.created.length + reconcileResult.recovered.length > 0) {
+					await saveIdMapping(this.dataSyncDir, currentMapping);
+					if (reconcileResult.recovered.length > 0) this.output.debug(`Recovered ${reconcileResult.recovered.length} ID mapping(s) from remote`);
+					if (reconcileResult.created.length > 0) this.output.debug(`Created ${reconcileResult.created.length} new ID mapping(s) after conflict resolution`);
+				}
+			}
+			await git("-C", worktreePath, "add", "-A");
+			const conflictCheck = await git("-C", worktreePath, "diff", "--cached", "-S<<<<<<< ", "--name-only");
+			if (conflictCheck.trim()) {
+				const conflictedFiles = conflictCheck.trim().split("\n");
+				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 gitCommit(worktreePath, "--no-verify", "-m", "tbd sync: resolved merge conflicts");
 			} catch {
-				this.output.debug(`Issue ${localIssue.id} not on remote, no merge needed`);
+				this.output.debug("No merge commit needed (conflicts already resolved)");
 			}
-			return conflicts;
+		}
+		await this.assertNoCorruptBeads();
+		return conflicts;
+	}
+	async doPushWithRetry(syncBranch, remote) {
+		return pushWithRetry(syncBranch, remote, async () => {
+			return this.mergeRemoteIntoSyncBranch(syncBranch, remote);
 		}, this.tbdRoot);
 	}
 	/**
@@ -104398,79 +104653,8 @@ var SyncHandler = class extends BaseCommand {
 				}
 			}
 			if (behindCommits > 0) {
-				let headBeforeMerge = "";
-				try {
-					headBeforeMerge = (await git("-C", worktreePath, "rev-parse", "HEAD")).trim();
-				} catch {}
-				try {
-					await git("-C", worktreePath, "merge", `${remote}/${syncBranch}`, "-m", "tbd sync: merge remote changes");
-					this.output.debug(`Merged ${behindCommits} commit(s) from remote`);
-					if (headBeforeMerge) await this.showGitLogDebug("Commits received", `${headBeforeMerge}..${syncBranch}`);
-					const postMergeIssues = await listIssues(this.dataSyncDir);
-					const postMergeMapping = await loadIdMapping(this.dataSyncDir);
-					let historicalMapping;
-					try {
-						const remoteIdsContent = await git("show", `${remote}/${syncBranch}:${DATA_SYNC_DIR}/mappings/ids.yml`);
-						if (remoteIdsContent) historicalMapping = parseIdMappingFromYaml(remoteIdsContent);
-					} catch {}
-					const reconcileResult = reconcileMappings(postMergeIssues.map((i) => i.id), postMergeMapping, historicalMapping);
-					const totalReconciled = reconcileResult.created.length + reconcileResult.recovered.length;
-					if (totalReconciled > 0) {
-						await saveIdMapping(this.dataSyncDir, postMergeMapping);
-						await git("-C", worktreePath, "add", "-A");
-						try {
-							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)`);
-					}
-				} catch {
-					this.output.info(`Merge conflict, attempting file-level resolution`);
-					const localIssues = await listIssues(this.dataSyncDir);
-					for (const localIssue of localIssues) try {
-						if (await git("show", `${remote}/${syncBranch}:${DATA_SYNC_DIR}/issues/${localIssue.id}.md`)) {
-							const result = mergeIssues(null, localIssue, await readIssue(this.dataSyncDir, localIssue.id));
-							await writeIssue(this.dataSyncDir, result.merged);
-							conflicts.push(...result.conflicts);
-						}
-					} catch {
-						this.output.debug(`Issue ${localIssue.id} not on remote, keeping local`);
-					}
-					let conflictRemoteMapping;
-					try {
-						const remoteIdsContent = await git("show", `${remote}/${syncBranch}:${DATA_SYNC_DIR}/mappings/ids.yml`);
-						if (remoteIdsContent) {
-							conflictRemoteMapping = parseIdMappingFromYaml(remoteIdsContent);
-							const localMapping = resolveIdMappingConflicts(await readFile(join(this.dataSyncDir, "mappings", "ids.yml"), "utf-8"));
-							const mergedMapping = mergeIdMappings(localMapping, conflictRemoteMapping);
-							await saveIdMapping(this.dataSyncDir, mergedMapping);
-							this.output.debug(`Merged ID mappings: ${localMapping.shortToUlid.size} local + ${conflictRemoteMapping.shortToUlid.size} remote = ${mergedMapping.shortToUlid.size} total`);
-						}
-					} catch (error) {
-						this.output.debug(`Could not merge ids.yml: ${error.message}`);
-					}
-					{
-						const allIssues = await listIssues(this.dataSyncDir);
-						const currentMapping = await loadIdMapping(this.dataSyncDir);
-						const reconcileResult = reconcileMappings(allIssues.map((i) => i.id), currentMapping, conflictRemoteMapping);
-						if (reconcileResult.created.length + reconcileResult.recovered.length > 0) {
-							await saveIdMapping(this.dataSyncDir, currentMapping);
-							if (reconcileResult.recovered.length > 0) this.output.debug(`Recovered ${reconcileResult.recovered.length} ID mapping(s) from remote`);
-							if (reconcileResult.created.length > 0) this.output.debug(`Created ${reconcileResult.created.length} new ID mapping(s) after conflict resolution`);
-						}
-					}
-					await git("-C", worktreePath, "add", "-A");
-					const conflictCheck = await git("-C", worktreePath, "diff", "--cached", "-S<<<<<<< ", "--name-only");
-					if (conflictCheck.trim()) {
-						const conflictedFiles = conflictCheck.trim().split("\n");
-						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 gitCommit(worktreePath, "--no-verify", "-m", "tbd sync: resolved merge conflicts");
-					} catch {
-						this.output.debug("No merge commit needed (conflicts already resolved)");
-					}
-				}
+				const mergeConflicts = await this.mergeRemoteIntoSyncBranch(syncBranch, remote);
+				conflicts.push(...mergeConflicts);
 			}
 		} catch (error) {
 			if (error instanceof SyncError) throw error;
@@ -104524,7 +104708,8 @@ var SyncHandler = class extends BaseCommand {
 				this.output.error(`Push failed: ${displayError}`);
 				console.log(`  ${aheadCommits} commit(s) not pushed to remote.`);
 			});
-			if (errorType === "permanent" && options.autoSave !== false) await this.handlePermanentFailure();
+			let recovered = false;
+			if (errorType === "permanent" && options.autoSave !== false) recovered = await this.handlePermanentFailure();
 			else if (!this.ctx.json) if (errorType === "transient") {
 				console.log("");
 				console.log("  This appears to be a temporary issue. Options:");
@@ -104537,6 +104722,7 @@ var SyncHandler = class extends BaseCommand {
 				console.log("    • Run 'tbd sync --status' to check status");
 				console.log("    • Save for later:  tbd save --outbox");
 			}
+			if (!recovered) process.exitCode = 1;
 			return;
 		}
 		if (options.outbox !== false) await this.maybeImportOutbox(syncBranch, remote);
@@ -104552,12 +104738,16 @@ var SyncHandler = class extends BaseCommand {
 	/**
 	* Handle permanent push failure by auto-saving to outbox.
 	* Called when push fails with a permanent error (e.g., HTTP 403).
+	*
+	* @returns true if the local changes are durably safe (saved to the outbox, or
+	*   nothing needed saving); false if the auto-save itself failed. The caller
+	*   uses this to decide the process exit code. (#158)
 	*/
 	async handlePermanentFailure() {
 		if ((await listIssues(this.dataSyncDir)).length === 0) {
 			console.log("");
 			console.log("  No unsynced issues to save (already in sync with remote).");
-			return;
+			return true;
 		}
 		let existingOutboxCount = 0;
 		if (await workspaceExists(this.tbdRoot, "outbox")) {
@@ -104596,12 +104786,14 @@ var SyncHandler = class extends BaseCommand {
 				console.log("");
 				console.log("  WARNING: Do NOT add .tbd/workspaces/ to .gitignore -- that would cause data loss.");
 			}
+			return true;
 		} catch (saveError) {
 			const saveErrorMsg = saveError instanceof Error ? saveError.message : String(saveError);
 			console.log("");
 			this.output.error(`Auto-save to outbox also failed: ${saveErrorMsg}`);
 			console.log("");
 			console.log("  Run 'tbd save --outbox' manually, or 'tbd doctor' to diagnose.");
+			return false;
 		}
 	}
 	/**
@@ -105084,12 +105276,6 @@ const CODEX_HOOKS_REL = ".codex/hooks.json";
 */
 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.
-*/
-const GLOBAL_CLAUDE_DIR = join(homedir(), ".claude");
-/**
 * Get project-local Claude Code paths.
 *
 * @param projectRoot - The project root directory (containing .tbd/)
@@ -105348,7 +105534,7 @@ var StatusHandler = class extends BaseCommand {
 				path: data.integrations.claude_code_path
 			},
 			{
-				name: "Codex AGENTS.md",
+				name: "AGENTS.md",
 				installed: data.integrations.codex,
 				path: data.integrations.codex_path
 			},
@@ -105672,6 +105858,71 @@ function classifyRemoteSyncHealth(health, remote, syncBranch) {
 		message: `${remote}/${syncBranch}`
 	};
 }
+/**
+* The "Sync consistency" finding for a branch that is both ahead and behind.
+*
+* When the histories are unrelated, the remediation is the rescue
+* (`tbd doctor --fix`), NOT `tbd sync` — otherwise the unrelated-history error
+* (which says "run doctor --fix") and this warning (which would say "run sync")
+* point at each other in a loop with no terminating instruction. See #158.
+*/
+function divergenceFinding(ahead, behind, unrelated) {
+	if (unrelated) return {
+		name: "Sync consistency",
+		status: "warn",
+		message: `diverged (${ahead} ahead, ${behind} behind) — unrelated histories`,
+		suggestion: "Run: tbd doctor --fix to reconcile the unrelated histories"
+	};
+	return {
+		name: "Sync consistency",
+		status: "warn",
+		message: `diverged (${ahead} ahead, ${behind} behind)`,
+		suggestion: "Run: tbd sync to reconcile"
+	};
+}
+/**
+* Build the "Shared lock writability" finding from a probe result.
+*
+* `code` is the errno from attempting to create a directory under the shared
+* locks dir, or undefined on success. EPERM/EACCES is a hard error: every write
+* command must acquire this lock, so an unwritable lock path breaks all writes
+* (the #164 Codex-sandbox case) — and a lock tbd needs but cannot take is a
+* fatal condition, not a soft warning. Any other probe failure is reported as a
+* warning since it cannot be positively interpreted. Never `fixable`: tbd cannot
+* widen a sandbox or change filesystem permissions itself.
+*/
+function buildLockWritabilityFinding(params) {
+	const { code, sharedLockPath, sharedLocksDir, sharedTbdDir, gitCommonDir, projectRoot } = params;
+	if (!code) return {
+		name: "Shared lock writability",
+		status: "ok",
+		path: sharedLocksDir
+	};
+	if (code === "EPERM" || code === "EACCES") {
+		const outsideProject = isCommonDirOutsideProject(gitCommonDir, projectRoot);
+		const details = [
+			`Cannot create the shared data-sync lock (${code}): ${sharedLockPath}`,
+			"Read-only commands work, but every write command (create, update, sync) needs",
+			"this lock, so they will fail until the lock path is writable."
+		];
+		if (outsideProject) details.push(`The checkout (${projectRoot}) is writable, but the shared tbd state under`, `${sharedTbdDir} lives in the Git common dir (${gitCommonDir}) outside it —`, "a common situation in agent sandboxes such as Codex worktrees.");
+		const suggestion = outsideProject ? `Grant write access to ${sharedTbdDir} (in an agent sandbox such as Codex, add it to the writable roots), or re-run the write command with sandbox escalation.` : `Ensure ${sharedTbdDir} is writable by this user (check filesystem permissions).`;
+		return {
+			name: "Shared lock writability",
+			status: "error",
+			message: `lock path not writable (${code})`,
+			path: sharedLockPath,
+			details,
+			suggestion
+		};
+	}
+	return {
+		name: "Shared lock writability",
+		status: "warn",
+		message: `unable to verify (${code})`,
+		path: sharedLocksDir
+	};
+}
 const CONFIG_DIR = TBD_DIR;
 var DoctorHandler = class extends BaseCommand {
 	dataSyncDir = "";
@@ -105696,18 +105947,19 @@ var DoctorHandler = class extends BaseCommand {
 		const statusInfo = await this.gatherStatusInfo();
 		const statsInfo = await this.gatherStatsInfo();
 		const healthChecks = [];
-		healthChecks.push(await this.checkGitVersion());
-		healthChecks.push(await this.checkConfig());
-		healthChecks.push(await this.checkIssuesDirectory());
-		healthChecks.push(this.checkOrphanedDependencies(this.issues));
-		healthChecks.push(this.checkDuplicateIds(this.issues));
-		healthChecks.push(await this.checkIdMappingConflicts(options.fix));
-		healthChecks.push(await this.checkIdMappingDuplicates(options.fix));
-		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(await this.safeCheck("Git version", () => this.checkGitVersion()));
+		healthChecks.push(await this.safeCheck("Config file", () => this.checkConfig()));
+		healthChecks.push(await this.safeCheck("Issues directory", () => this.checkIssuesDirectory()));
+		healthChecks.push(await this.safeCheck("Dependencies", async () => this.checkOrphanedDependencies(this.issues)));
+		healthChecks.push(await this.safeCheck("Unique IDs", async () => this.checkDuplicateIds(this.issues)));
+		healthChecks.push(await this.safeCheck("ID mapping conflicts", () => this.checkIdMappingConflicts(options.fix)));
+		healthChecks.push(await this.safeCheck("ID mapping keys", () => this.checkIdMappingDuplicates(options.fix)));
+		healthChecks.push(await this.safeCheck("Temp files", () => this.checkTempFiles(options.fix)));
+		healthChecks.push(await this.safeCheck("Issue validity", async () => this.checkIssueValidity(this.issues, this.invalidIssueFiles)));
+		healthChecks.push(await this.safeCheck("Worktree", () => this.checkWorktree(options.fix)));
+		healthChecks.push(await this.safeCheck("Common-dir layout", () => this.checkCommonDirLayout(options.fix)));
+		healthChecks.push(await this.safeCheck("Shared lock writability", () => this.checkSharedLockWritability()));
+		const dataLocationResult = await this.safeCheck("Data location", () => this.checkDataLocation(options.fix));
 		healthChecks.push(dataLocationResult);
 		if (dataLocationResult.status === "ok" && dataLocationResult.message?.includes("migrated")) {
 			this.dataSyncDir = (await resolveSharedTbdPaths(this.cwd)).sharedDataSyncDir;
@@ -105721,17 +105973,17 @@ var DoctorHandler = class extends BaseCommand {
 		}
 		const parsedMaxHistory = options.maxHistory ? parseInt(options.maxHistory, 10) : 50;
 		const maxHistory = Number.isNaN(parsedMaxHistory) || parsedMaxHistory < 0 ? 50 : parsedMaxHistory;
-		healthChecks.push(await this.checkMissingMappings(options.fix, maxHistory));
-		healthChecks.push(await this.checkLocalSyncBranch());
-		healthChecks.push(await this.checkRemoteSyncBranch(options.fix));
-		healthChecks.push(await this.checkLocalVsRemoteData());
-		healthChecks.push(await this.checkCloneScenarios());
-		healthChecks.push(await this.checkSyncConsistency());
+		healthChecks.push(await this.safeCheck("ID mapping coverage", () => this.checkMissingMappings(options.fix, maxHistory)));
+		healthChecks.push(await this.safeCheck("Local sync branch", () => this.checkLocalSyncBranch()));
+		healthChecks.push(await this.safeCheck("Remote sync branch", () => this.checkRemoteSyncBranch(options.fix)));
+		healthChecks.push(await this.safeCheck("Sync status", () => this.checkLocalVsRemoteData()));
+		healthChecks.push(await this.safeCheck("Clone status", () => this.checkCloneScenarios()));
+		healthChecks.push(await this.safeCheck("Sync consistency", () => this.checkSyncConsistency()));
 		const integrationChecks = [];
-		integrationChecks.push(await this.checkPortableSkill());
-		integrationChecks.push(await this.checkClaudeSkill());
-		integrationChecks.push(await this.checkCodexAgents());
-		integrationChecks.push(await this.checkCodexHooks());
+		integrationChecks.push(await this.safeCheck("Portable Agent Skill", () => this.checkPortableSkill()));
+		integrationChecks.push(await this.safeCheck("Claude Code skill", () => this.checkClaudeSkill()));
+		integrationChecks.push(await this.safeCheck("AGENTS.md", () => this.checkCodexAgents()));
+		integrationChecks.push(await this.safeCheck("Codex hooks", () => this.checkCodexHooks()));
 		const allChecks = [...healthChecks, ...integrationChecks];
 		const allOk = allChecks.every((c) => c.status === "ok");
 		const hasErrors = allChecks.some((c) => c.status === "error");
@@ -106266,12 +106518,12 @@ var DoctorHandler = class extends BaseCommand {
 		try {
 			await access(agentsPath);
 			if ((await readFile(agentsPath, "utf-8")).includes("BEGIN TBD INTEGRATION")) return {
-				name: "Codex AGENTS.md",
+				name: "AGENTS.md",
 				status: "ok",
 				path: AGENTS_MD_REL
 			};
 			return {
-				name: "Codex AGENTS.md",
+				name: "AGENTS.md",
 				status: "warn",
 				message: "exists but missing tbd integration",
 				path: AGENTS_MD_REL,
@@ -106279,7 +106531,7 @@ var DoctorHandler = class extends BaseCommand {
 			};
 		} catch {
 			return {
-				name: "Codex AGENTS.md",
+				name: "AGENTS.md",
 				status: "warn",
 				message: "not installed",
 				path: AGENTS_MD_REL,
@@ -106449,6 +106701,63 @@ var DoctorHandler = class extends BaseCommand {
 		}
 	}
 	/**
+	* Probe whether this process can create the shared data-sync lock.
+	*
+	* Read-only diagnostics never take the lock, so a checkout whose
+	* `$GIT_COMMON_DIR/tbd` is outside the writable sandbox (e.g. a Codex
+	* worktree) looks healthy here while every write command fails with EPERM on
+	* the lock mkdir. This probe mirrors `withSharedDataSyncLock`: ensure the
+	* locks dir, then create and remove a uniquely named probe directory inside
+	* it. It is fully self-contained and never throws, so it cannot abort the
+	* doctor run. See issue #164.
+	*/
+	async checkSharedLockWritability() {
+		let paths;
+		try {
+			paths = await resolveSharedTbdPaths(this.cwd);
+		} catch (error) {
+			return {
+				name: "Shared lock writability",
+				status: "warn",
+				message: `unable to resolve shared paths: ${error instanceof Error ? error.message : String(error)}`
+			};
+		}
+		const probeDir = join(paths.sharedLocksDir, `.tbd-doctor-probe-${randomUUID()}.lock`);
+		let code;
+		try {
+			await mkdir(paths.sharedLocksDir, { recursive: true });
+			await mkdir(probeDir);
+		} catch (error) {
+			code = error?.code ?? "UNKNOWN";
+		} finally {
+			await rmdir(probeDir).catch(() => {});
+		}
+		return buildLockWritabilityFinding({
+			code,
+			sharedLockPath: paths.sharedLockPath,
+			sharedLocksDir: paths.sharedLocksDir,
+			sharedTbdDir: paths.sharedTbdDir,
+			gitCommonDir: paths.gitCommonDir,
+			projectRoot: this.cwd
+		});
+	}
+	/**
+	* Run a single diagnostic check, converting an unexpected throw into an error
+	* finding instead of letting it abort the whole `tbd doctor` run. Doctor must
+	* surface every issue it can find, not just the first failure. (issue #164)
+	*/
+	async safeCheck(name, fn) {
+		try {
+			return await fn();
+		} catch (error) {
+			return {
+				name,
+				status: "error",
+				message: `check could not complete: ${error instanceof Error ? error.message : String(error)}`
+			};
+		}
+	}
+	/**
 	* Check for issues in wrong location.
 	* See: plan-2026-01-28-sync-worktree-recovery-and-hardening.md §5
 	*
@@ -106691,12 +107000,10 @@ var DoctorHandler = class extends BaseCommand {
 				fixable: true,
 				suggestion: "Run: tbd doctor --fix to synchronize"
 			};
-			if (consistency.localAhead > 0 && consistency.localBehind > 0) return {
-				name: "Sync consistency",
-				status: "warn",
-				message: `diverged (${consistency.localAhead} ahead, ${consistency.localBehind} behind)`,
-				suggestion: "Run: tbd sync to reconcile"
-			};
+			if (consistency.localAhead > 0 && consistency.localBehind > 0) {
+				const { unrelated } = await checkRemoteBranchHealth(remote, syncBranch, this.cwd);
+				return divergenceFinding(consistency.localAhead, consistency.localBehind, unrelated);
+			}
 			if (consistency.localAhead > 0) return {
 				name: "Sync consistency",
 				status: "ok",
@@ -108272,6 +108579,32 @@ var DocCache = class {
 */
 const SHORTCUT_DIRECTORY_BEGIN = "<!-- BEGIN SHORTCUT DIRECTORY -->";
 const SHORTCUT_DIRECTORY_END = "<!-- END SHORTCUT DIRECTORY -->";
+const GUIDELINE_GROUPS = [
+	{
+		heading: "General engineering",
+		note: "Read all of these for any engineering work (writing or reviewing code).",
+		match: (n) => n.startsWith("general-") || n === "error-handling-rules" || n === "backward-compatibility-rules" || n === "commit-conventions" || n.includes("tdd") || n.includes("testing") || n.includes("golden")
+	},
+	{
+		heading: "TypeScript & JS ecosystem",
+		note: "Also load these when working in TypeScript or JavaScript.",
+		match: (n) => n.startsWith("typescript-") || n.endsWith("monorepo-patterns") || n.startsWith("electron-")
+	},
+	{
+		heading: "Python",
+		note: "Also load these when working in Python.",
+		match: (n) => n.startsWith("python-")
+	},
+	{
+		heading: "Convex",
+		note: "Also load these when working with Convex.",
+		match: (n) => n.startsWith("convex-")
+	},
+	{
+		heading: "Docs, process & tooling",
+		match: () => true
+	}
+];
 /**
 * Build table rows from docs (shared helper for shortcuts and guidelines).
 */
@@ -108292,7 +108625,8 @@ function buildTableRows(docs, skipNames = []) {
 * The output includes:
 * 1. Marker comments for incremental updates
 * 2. Available Shortcuts section with name and description
-* 3. Available Guidelines section with name and description (if provided)
+* 3. Available Guidelines section, grouped by area (General engineering first, then
+*    language/framework groups), with name and description (if provided)
 *
 * @param shortcuts - Array of shortcut CachedDoc objects
 * @param guidelines - Optional array of guideline CachedDoc objects
@@ -108308,8 +108642,12 @@ function buildTableRows(docs, skipNames = []) {
 * // | code-review-and-commit | Run pre-commit checks, review changes, and commit code |
 * // ...
 * // ## Available Guidelines
+* // ### General engineering
 * // | Name | Description |
 * // | --- | --- |
+* // | error-handling-rules | Rules for handling errors... |
+* // ...
+* // ### TypeScript & JS ecosystem
 * // | typescript-rules | TypeScript coding rules and best practices |
 * // ...
 * // <!-- END SHORTCUT DIRECTORY -->
@@ -108333,16 +108671,32 @@ function generateShortcutDirectory(shortcuts, guidelines = []) {
 		lines.push(...shortcutRows);
 	}
 	if (guidelines.length > 0) {
-		const guidelineRows = buildTableRows(guidelines);
-		if (guidelineRows.length > 0) {
+		const grouped = GUIDELINE_GROUPS.map((group) => ({
+			group,
+			docs: []
+		}));
+		const catchAll = grouped[grouped.length - 1];
+		for (const doc of guidelines) (grouped.find((g) => g.group.match(doc.name)) ?? catchAll)?.docs.push(doc);
+		if (grouped.some((g) => g.docs.length > 0)) {
 			lines.push("");
 			lines.push("## Available Guidelines");
 			lines.push("");
-			lines.push("Run `tbd guidelines <name>` to apply any of these guidelines:");
-			lines.push("");
-			lines.push("| Name | Description |");
-			lines.push("| --- | --- |");
-			lines.push(...guidelineRows);
+			lines.push("Run `tbd guidelines <name>` to apply any of these guidelines.");
+			lines.push("Load the **General engineering** group first, then the language or framework group.");
+			for (const { group, docs } of grouped) {
+				const rows = buildTableRows(docs);
+				if (rows.length === 0) continue;
+				lines.push("");
+				lines.push(`### ${group.heading}`);
+				if (group.note) {
+					lines.push("");
+					lines.push(`*${group.note}*`);
+				}
+				lines.push("");
+				lines.push("| Name | Description |");
+				lines.push("| --- | --- |");
+				lines.push(...rows);
+			}
 		}
 	}
 	lines.push("");
@@ -109546,12 +109900,12 @@ fi
 
 # Pinned zero-install fallback. Never use an unpinned runner here.
 if command -v npx &> /dev/null; then
-    npx --yes get-tbd@${VERSION} prime "$@"
+    npx --yes get-tbd@${PINNED_NPM_VERSION} prime "$@"
     exit $?
 fi
 
 echo "[tbd] tbd CLI not found and npx is unavailable."
-echo "[tbd] Install it with: npm install -g get-tbd@${VERSION}"
+echo "[tbd] Install it with: npm install -g get-tbd@${PINNED_NPM_VERSION}"
 exit 1
 `;
 /**
@@ -110025,6 +110379,16 @@ var SetupCodexHandler = class extends BaseCommand {
 		await this.installCodexSection(agentsPath);
 		await this.installCodexHooks(cwd);
 	}
+	/** Install only the AGENTS.md managed block (the `agents-md` surface). */
+	async runAgentsMdOnly() {
+		const cwd = this.projectDir ?? process.cwd();
+		await this.installCodexSection(join(cwd, "AGENTS.md"));
+	}
+	/** Install only the Codex lifecycle hooks (the `codex` surface). */
+	async runCodexHooksOnly() {
+		const cwd = this.projectDir ?? process.cwd();
+		await this.installCodexHooks(cwd);
+	}
 	/**
 	* Read the use_gh_cli setting; defaults to true (so fresh setup installs it).
 	*/
@@ -110481,6 +110845,24 @@ Example:
 		}
 	}
 };
+/**
+* Agent integration surfaces that `tbd setup` can install, in install/report
+* order. Each is selectable via `--surfaces=<comma-list>`; with the flag omitted,
+* all are installed. Adding an agent is one entry here plus a case in
+* `installSurface` — there is no per-agent flag to add.
+*/
+const SETUP_SURFACE_IDS = [
+	"portable",
+	"agents-md",
+	"claude",
+	"codex"
+];
+const SURFACE_DISPLAY_NAME = {
+	portable: "Portable Agent Skill",
+	"agents-md": "AGENTS.md",
+	claude: "Claude Code",
+	codex: "Codex hooks"
+};
 var SetupAutoHandler = class extends BaseCommand {
 	cmd;
 	constructor(command) {
@@ -110500,10 +110882,16 @@ var SetupAutoHandler = class extends BaseCommand {
 			const entries = await readdir(scriptsDir, { withFileTypes: true });
 			for (const entry of entries) if (entry.isFile()) {
 				const filename = entry.name;
-				if (LEGACY_TBD_SCRIPTS.includes(filename)) try {
-					await rm(join(scriptsDir, filename));
-					scriptsRemoved.push(filename);
-				} catch {}
+				if (LEGACY_TBD_SCRIPTS.includes(filename)) {
+					if (this.ctx.dryRun) {
+						scriptsRemoved.push(filename);
+						continue;
+					}
+					try {
+						await rm(join(scriptsDir, filename));
+						scriptsRemoved.push(filename);
+					} catch {}
+				}
 			}
 		} catch {}
 		return scriptsRemoved;
@@ -110547,7 +110935,7 @@ var SetupAutoHandler = class extends BaseCommand {
 						modified = true;
 					}
 				}
-				if (modified) {
+				if (modified && !this.ctx.dryRun) {
 					if (Object.keys(hooks).length === 0) delete settings.hooks;
 					await writeFile(projectSettingsPath, JSON.stringify(settings, null, 2) + "\n");
 				}
@@ -110565,18 +110953,22 @@ var SetupAutoHandler = class extends BaseCommand {
 			const parts = [];
 			if (scriptsRemoved.length > 0) parts.push(`${scriptsRemoved.length} script(s)`);
 			if (hooksRemoved > 0) parts.push(`${hooksRemoved} hook(s)`);
-			console.log(colors.dim(`Cleaned up legacy ${parts.join(" and ")}`));
+			if (this.ctx.dryRun) this.output.dryRun(`Would clean up legacy ${parts.join(" and ")}`);
+			else console.log(colors.dim(`Cleaned up legacy ${parts.join(" and ")}`));
 		}
 		await this.syncDocs(cwd);
-		const targeting = this.resolveTargeting();
-		await this.installPortableSkill(cwd);
-		const claudeResult = await this.setupClaudeIfDetected(cwd, targeting.claude);
-		results.push(claudeResult);
-		const codexResult = await this.setupCodexIfDetected(cwd, targeting.codex);
-		results.push(codexResult);
+		const selected = this.resolveSurfaces();
+		const skippedSurfaces = [];
+		for (const id of SETUP_SURFACE_IDS) {
+			if (!selected.has(id)) {
+				skippedSurfaces.push(SURFACE_DISPLAY_NAME[id]);
+				continue;
+			}
+			results.push(await this.installSurface(id, cwd));
+		}
 		const installed = results.filter((r) => r.installed && !r.alreadyInstalled);
 		const alreadyInstalled = results.filter((r) => r.alreadyInstalled);
-		const skipped = results.filter((r) => !r.detected);
+		const failed = results.filter((r) => r.error);
 		if (installed.length > 0) {
 			console.log(colors.bold("Configured integrations:"));
 			for (const r of installed) console.log(`  ${colors.success("✓")} ${r.name}`);
@@ -110585,16 +110977,11 @@ var SetupAutoHandler = class extends BaseCommand {
 			console.log(colors.dim("Already configured:"));
 			for (const r of alreadyInstalled) console.log(`  ${colors.dim("✓")} ${r.name}`);
 		}
-		if (skipped.length > 0 && (installed.length > 0 || alreadyInstalled.length > 0)) {
-			console.log(colors.dim("Not detected (skipped):"));
-			for (const r of skipped) console.log(`  ${colors.dim("-")} ${r.name}`);
-		}
-		if (installed.length === 0 && alreadyInstalled.length === 0) {
-			console.log(colors.dim("No coding agents detected."));
-			console.log("");
-			console.log("Install a coding agent (Claude Code, Codex, or any AGENTS.md-compatible tool) and re-run:");
-			console.log("  tbd setup --auto");
+		if (skippedSurfaces.length > 0) {
+			console.log(colors.dim("Skipped (not in --surfaces):"));
+			for (const name of skippedSurfaces) console.log(`  ${colors.dim("-")} ${name}`);
 		}
+		if (failed.length > 0) for (const r of failed) console.log(colors.warn(`  ! ${r.name}: ${r.error}`));
 	}
 	/**
 	* Sync docs using syncDocsWithDefaults.
@@ -110616,51 +111003,72 @@ var SetupAutoHandler = class extends BaseCommand {
 		if (result.errors.length > 0) for (const { path, error } of result.errors) console.log(colors.warn(`Warning: ${path}: ${error}`));
 	}
 	/**
-	* 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.
+	* Resolve the set of surfaces to install from `--surfaces=<comma-list>`. With
+	* the flag omitted, every surface is installed. `all` is an alias for the full
+	* set; an unknown surface ID is a hard error.
 	*/
-	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})`);
+	resolveSurfaces() {
+		const opts = this.cmd.optsWithGlobals();
+		if (opts.surfaces === void 0) return new Set(SETUP_SURFACE_IDS);
+		const valid = new Set(SETUP_SURFACE_IDS);
+		const requested = opts.surfaces.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+		const selected = /* @__PURE__ */ new Set();
+		for (const name of requested) {
+			if (name === "all") {
+				for (const id of SETUP_SURFACE_IDS) selected.add(id);
+				continue;
+			}
+			if (valid.has(name)) {
+				selected.add(name);
+				continue;
+			}
+			throw new CLIError(`Unknown surface "${name}". Valid surfaces: ${SETUP_SURFACE_IDS.join(", ")}, all.`);
+		}
+		return selected;
+	}
+	/** Dispatch the install for a single surface by ID. */
+	async installSurface(id, cwd) {
+		switch (id) {
+			case "portable": return this.installPortableSurface(cwd);
+			case "agents-md": return this.installAgentsMdSurface(cwd);
+			case "claude": return this.installClaudeSurface(cwd);
+			case "codex": return this.installCodexSurface(cwd);
+			default: {
+				const unhandled = id;
+				throw new Error(`Unhandled setup surface: ${String(unhandled)}`);
+			}
+		}
 	}
 	/**
-	* 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.
+	* Write the canonical portable Agent Skill to .agents/skills/tbd/SKILL.md.
+	* Read natively by Codex, Gemini CLI, Cursor, and other Agent Skills clients.
 	*/
-	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 installPortableSurface(cwd) {
+		const result = {
+			name: SURFACE_DISPLAY_NAME.portable,
+			detected: true,
+			installed: false,
+			alreadyInstalled: false
 		};
+		if (this.checkDryRun("Would install portable Agent Skill", { path: AGENTS_SKILL_DISPLAY })) return result;
+		try {
+			const { portable } = getAgentSkillPaths(cwd);
+			await writeSkillFile(portable, await buildSkillPayload(this.ctx.quiet));
+			result.installed = true;
+		} catch (error) {
+			if (error instanceof CLIError) throw error;
+			result.error = error.message;
+		}
+		return result;
 	}
-	async setupClaudeIfDetected(cwd, mode) {
+	/** Install the Claude Code surface: skill mirror + .claude/settings.json hooks. */
+	async installClaudeSurface(cwd) {
 		const result = {
-			name: "Claude Code",
-			detected: false,
+			name: SURFACE_DISPLAY_NAME.claude,
+			detected: true,
 			installed: false,
 			alreadyInstalled: false
 		};
-		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$1(claudePaths.settings)) {
@@ -110675,32 +111083,47 @@ 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;
 	}
-	async setupCodexIfDetected(cwd, mode) {
+	/** Install the AGENTS.md surface: the tbd managed block only (no Codex hooks). */
+	async installAgentsMdSurface(cwd) {
 		const result = {
-			name: "Codex/AGENTS.md",
-			detected: false,
+			name: SURFACE_DISPLAY_NAME["agents-md"],
+			detected: true,
 			installed: false,
 			alreadyInstalled: false
 		};
-		if (mode === "off") return result;
-		const agentsPath = getAgentsMdPath(cwd);
-		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;
+		try {
+			const agentsPath = getAgentsMdPath(cwd);
+			if (await pathExists$1(agentsPath)) {
+				if ((await readFile(agentsPath, "utf-8")).includes("BEGIN TBD INTEGRATION")) result.alreadyInstalled = true;
+			}
+			const handler = new SetupCodexHandler(this.cmd);
+			handler.setProjectDir(cwd);
+			await handler.runAgentsMdOnly();
+			result.installed = true;
+		} catch (error) {
+			if (error instanceof CLIError) throw error;
+			result.error = error.message;
 		}
+		return result;
+	}
+	/** Install the Codex surface: .codex/hooks.json + .codex/ lifecycle scripts. */
+	async installCodexSurface(cwd) {
+		const result = {
+			name: SURFACE_DISPLAY_NAME.codex,
+			detected: true,
+			installed: false,
+			alreadyInstalled: false
+		};
 		try {
+			if (await pathExists$1(getCodexPaths(cwd).hooks)) result.alreadyInstalled = true;
 			const handler = new SetupCodexHandler(this.cmd);
 			handler.setProjectDir(cwd);
-			await handler.run({});
+			await handler.runCodexHooksOnly();
 			result.installed = true;
 		} catch (error) {
 			if (error instanceof CLIError) throw error;
@@ -110709,7 +111132,7 @@ var SetupAutoHandler = class extends BaseCommand {
 		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").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) => {
+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("--surfaces <list>", "Comma-separated agent surfaces to install: portable, agents-md, claude, codex (or \"all\"). Default: all").action(async (options, command) => {
 	if (options.auto || options.interactive) {
 		await new SetupDefaultHandler(command).run(options);
 		return;
@@ -110736,6 +111159,7 @@ const setupCommand = new Command("setup").description("Configure tbd integration
 	console.log("  --prefix <name>     Project prefix for issue IDs (2-8 alphabetic recommended)");
 	console.log("  --force             Allow non-recommended prefix format");
 	console.log("  --no-gh-cli         Disable automatic GitHub CLI installation hook");
+	console.log("  --surfaces <list>   Agent surfaces to install: portable,agents-md,claude,codex,all (default: all)");
 	console.log("");
 	console.log("Examples:");
 	console.log("  tbd setup --auto --prefix=tbd   # Full automatic setup with prefix");