get-tbd 0.2.2 → 0.3.0

package/dist/lockfile-BR0laSDy.mjs

@@ -0,0 +1,198 @@
+import { mkdir, rename, rmdir, stat } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+
+//#region src/utils/lockfile.ts
+/**
+* Directory-based mutual exclusion for concurrent file access.
+*
+* Note: Despite the name "lockfile", this is NOT a POSIX file lock (flock/fcntl).
+* It uses mkdir to create a lock *directory* as a coordination convention; no
+* OS-level file locking syscalls are involved. This makes it portable across all
+* filesystems, including NFS and other network mounts where flock/fcntl locks
+* are unreliable or unsupported.
+*
+* This is the same strategy used by:
+*
+* - **Git** for ref updates (e.g., `.git/refs/heads/main.lock`)
+*   See: https://git-scm.com/docs/gitrepository-layout ("lockfile protocol")
+* - **npm** for package-lock.json concurrent access
+*
+* ## Why mkdir?
+*
+* `mkdir(2)` is atomic on all common filesystems (local and network): it either
+* creates the directory or returns EEXIST. Unlike `open(O_CREAT|O_EXCL)`,
+* a directory lock is trivially distinguishable from normal files.
+*
+* Node.js `fs.mkdir` maps directly to the mkdir(2) syscall, preserving
+* the atomicity guarantee:
+*   https://nodejs.org/api/fs.html#fsmkdirpath-options-callback
+*
+* ## Lock lifecycle
+*
+* 1. **Acquire**: `mkdir(lockDir)`; fails with EEXIST if held by another process
+* 2. **Hold**: Execute the critical section
+* 3. **Release**: `rmdir(lockDir)`, in a finally block, with a bounded retry to
+*    absorb transient Windows failures (EBUSY/EPERM from AV scanners or lingering
+*    handles) that would otherwise orphan the lock directory.
+* 4. **Stale detection**: If lock mtime exceeds a threshold, assume the holder
+*    crashed and break the lock. Breaking is done **atomically** by renaming the
+*    stale directory aside (only one waiter can win the rename), so two waiters can
+*    never both break the same lock and end up running concurrently. This is a
+*    heuristic; safe when the critical section is short-lived (sub-second for
+*    file I/O).
+*
+* ## Failure on timeout
+*
+* If the lock cannot be acquired within the timeout, a LockAcquisitionError is
+* thrown. This prevents the dangerous "degraded mode" where the critical section
+* runs without mutual exclusion, which can cause data loss (e.g., lost ID
+* mappings during concurrent `tbd create`).
+*
+* IMPORTANT: `timeoutMs` must be greater than `staleMs` so stale locks from
+* crashed processes are always detected and broken before the timeout expires.
+*/
+const DEFAULT_TIMEOUT_MS = 1e4;
+const DEFAULT_POLL_MS = 50;
+const DEFAULT_STALE_MS = 5e3;
+/**
+* Lock timing profile for shared data-sync operations.
+*
+* Issue sync can include fetch, merge, push, and outbox import work, so it must
+* not use the short stale window intended for single-file writes. `timeoutMs`
+* is kept just above `staleMs` so a crashed-process lock is always broken as
+* stale before the timeout expires, matching the invariant documented above.
+*
+* Accepted trade-off (no heartbeat): a live `tbd sync` that hangs longer than
+* `staleMs` (30 min) can have its lock broken by another process mid-operation.
+* For current data sizes this is acceptable; single-repo sync workloads
+* complete well under the window, and adding heartbeat metadata adds
+* cross-process state machinery without changing the common case. If sync
+* workloads grow or the lock-break race becomes observable in practice,
+* revisit by adding heartbeat metadata inside the lock directory (touch mtime
+* periodically; treat as stale only if heartbeat is older than `staleMs`).
+* See: plan-2026-05-17-shared-common-dir-sync-worktree.md §Post-Review
+* Hardening H6.
+*/
+const DATA_SYNC_LOCK_OPTIONS = {
+	timeoutMs: 35 * 6e4,
+	pollMs: 250,
+	staleMs: 30 * 6e4
+};
+/**
+* Error thrown when the lock cannot be acquired within the timeout.
+*/
+var LockAcquisitionError = class extends Error {
+	constructor(lockPath, timeoutMs) {
+		super(`Failed to acquire lock at ${lockPath} within ${timeoutMs}ms. Another process may be holding the lock. If this persists, delete the lock directory manually and retry.`);
+		this.name = "LockAcquisitionError";
+	}
+};
+/** Filesystem error codes that are transient on Windows and worth retrying. */
+const TRANSIENT_RMDIR_CODES = new Set([
+	"EBUSY",
+	"EPERM",
+	"EACCES",
+	"ENOTEMPTY"
+]);
+/**
+* Remove a lock directory, tolerating transient Windows failures.
+*
+* `rmdir` can intermittently fail with EBUSY/EPERM on Windows (antivirus scanners
+* or lingering directory handles). A few short retries make release reliable; if it
+* still fails, we give up and let stale detection reclaim the directory rather than
+* throwing from a best-effort cleanup path.
+*/
+async function removeLockDir(lockPath, attempts = 5) {
+	for (let attempt = 0; attempt < attempts; attempt++) try {
+		await rmdir(lockPath);
+		return;
+	} catch (error) {
+		const code = error.code;
+		if (code === "ENOENT") return;
+		if (attempt < attempts - 1 && code && TRANSIENT_RMDIR_CODES.has(code)) {
+			await new Promise((resolve) => setTimeout(resolve, 20 * (attempt + 1)));
+			continue;
+		}
+		return;
+	}
+}
+/**
+* Atomically break a stale lock.
+*
+* Renames the stale directory to a unique sidecar path and removes it. `rename` is
+* atomic, so when several waiters race to break the same stale lock only one wins the
+* rename; the losers see ENOENT and simply retry. This prevents the classic
+* non-atomic break race (rmdir + mkdir) where two waiters both break the lock and both
+* acquire it, defeating mutual exclusion.
+*/
+async function breakStaleLock(lockPath) {
+	const sidecar = `${lockPath}.stale-${randomUUID()}`;
+	try {
+		await rename(lockPath, sidecar);
+	} catch {
+		return;
+	}
+	await removeLockDir(sidecar);
+}
+/**
+* Execute `fn` while holding a lockfile.
+*
+* The lock is a directory at `lockPath` (typically `<target-file>.lock`).
+* Concurrent callers will wait up to `timeoutMs` for the lock, polling
+* every `pollMs`. Stale locks older than `staleMs` are broken automatically.
+*
+* If the lock cannot be acquired within the timeout, a LockAcquisitionError
+* is thrown. This ensures mutual exclusion is never silently bypassed, which
+* prevents data loss from concurrent writes.
+*
+* @param lockPath - Path to use as the lock directory (e.g., "/path/to/ids.yml.lock")
+* @param fn - Critical section to execute under the lock
+* @param options - Timing parameters for lock acquisition
+* @returns The return value of `fn`
+* @throws LockAcquisitionError if the lock cannot be acquired within the timeout
+*
+* @example
+* ```ts
+* await withLockfile('/path/to/ids.yml.lock', async () => {
+*   const data = await readFile('/path/to/ids.yml', 'utf-8');
+*   const updated = mergeEntries(data, newEntries);
+*   await writeFile('/path/to/ids.yml', updated);
+* });
+* ```
+*/
+async function withLockfile(lockPath, fn, options) {
+	const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const pollMs = options?.pollMs ?? DEFAULT_POLL_MS;
+	const staleMs = options?.staleMs ?? DEFAULT_STALE_MS;
+	const deadline = Date.now() + timeoutMs;
+	let acquired = false;
+	while (Date.now() < deadline) try {
+		await mkdir(lockPath);
+		acquired = true;
+		break;
+	} catch (error) {
+		if (error.code !== "EEXIST") throw error;
+		let lockStat;
+		try {
+			lockStat = await stat(lockPath);
+		} catch {
+			continue;
+		}
+		if (!lockStat.isDirectory()) throw new Error(`Lock path exists but is not a directory: ${lockPath}. Refusing to break it; remove the conflicting file and retry.`);
+		if (Date.now() - lockStat.mtimeMs > staleMs) {
+			await breakStaleLock(lockPath);
+			continue;
+		}
+		await new Promise((resolve) => setTimeout(resolve, pollMs));
+	}
+	if (!acquired) throw new LockAcquisitionError(lockPath, timeoutMs);
+	try {
+		return await fn();
+	} finally {
+		await removeLockDir(lockPath);
+	}
+}
+
+//#endregion
+export { withLockfile as n, DATA_SYNC_LOCK_OPTIONS as t };
+//# sourceMappingURL=lockfile-BR0laSDy.mjs.map

package/dist/lockfile-BR0laSDy.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"lockfile-BR0laSDy.mjs","names":[],"sources":["../src/utils/lockfile.ts"],"sourcesContent":["/**\n * Directory-based mutual exclusion for concurrent file access.\n *\n * Note: Despite the name \"lockfile\", this is NOT a POSIX file lock (flock/fcntl).\n * It uses mkdir to create a lock *directory* as a coordination convention; no\n * OS-level file locking syscalls are involved. This makes it portable across all\n * filesystems, including NFS and other network mounts where flock/fcntl locks\n * are unreliable or unsupported.\n *\n * This is the same strategy used by:\n *\n * - **Git** for ref updates (e.g., `.git/refs/heads/main.lock`)\n *   See: https://git-scm.com/docs/gitrepository-layout (\"lockfile protocol\")\n * - **npm** for package-lock.json concurrent access\n *\n * ## Why mkdir?\n *\n * `mkdir(2)` is atomic on all common filesystems (local and network): it either\n * creates the directory or returns EEXIST. Unlike `open(O_CREAT|O_EXCL)`,\n * a directory lock is trivially distinguishable from normal files.\n *\n * Node.js `fs.mkdir` maps directly to the mkdir(2) syscall, preserving\n * the atomicity guarantee:\n *   https://nodejs.org/api/fs.html#fsmkdirpath-options-callback\n *\n * ## Lock lifecycle\n *\n * 1. **Acquire**: `mkdir(lockDir)`; fails with EEXIST if held by another process\n * 2. **Hold**: Execute the critical section\n * 3. **Release**: `rmdir(lockDir)`, in a finally block, with a bounded retry to\n *    absorb transient Windows failures (EBUSY/EPERM from AV scanners or lingering\n *    handles) that would otherwise orphan the lock directory.\n * 4. **Stale detection**: If lock mtime exceeds a threshold, assume the holder\n *    crashed and break the lock. Breaking is done **atomically** by renaming the\n *    stale directory aside (only one waiter can win the rename), so two waiters can\n *    never both break the same lock and end up running concurrently. This is a\n *    heuristic; safe when the critical section is short-lived (sub-second for\n *    file I/O).\n *\n * ## Failure on timeout\n *\n * If the lock cannot be acquired within the timeout, a LockAcquisitionError is\n * thrown. This prevents the dangerous \"degraded mode\" where the critical section\n * runs without mutual exclusion, which can cause data loss (e.g., lost ID\n * mappings during concurrent `tbd create`).\n *\n * IMPORTANT: `timeoutMs` must be greater than `staleMs` so stale locks from\n * crashed processes are always detected and broken before the timeout expires.\n */\n\nimport { mkdir, rename, rmdir, stat } from 'node:fs/promises';\nimport { randomUUID } from 'node:crypto';\n\n/** Options for `withLockfile`. */\nexport interface LockfileOptions {\n  /** Maximum time (ms) to wait for the lock. Default: 10000 */\n  timeoutMs?: number;\n  /** Polling interval (ms) between acquisition attempts. Default: 50 */\n  pollMs?: number;\n  /** Age (ms) after which a lock is considered stale. Default: 5000 */\n  staleMs?: number;\n}\n\nconst DEFAULT_TIMEOUT_MS = 10_000;\nconst DEFAULT_POLL_MS = 50;\nconst DEFAULT_STALE_MS = 5_000;\n\n/**\n * Lock timing profile for shared data-sync operations.\n *\n * Issue sync can include fetch, merge, push, and outbox import work, so it must\n * not use the short stale window intended for single-file writes. `timeoutMs`\n * is kept just above `staleMs` so a crashed-process lock is always broken as\n * stale before the timeout expires, matching the invariant documented above.\n *\n * Accepted trade-off (no heartbeat): a live `tbd sync` that hangs longer than\n * `staleMs` (30 min) can have its lock broken by another process mid-operation.\n * For current data sizes this is acceptable; single-repo sync workloads\n * complete well under the window, and adding heartbeat metadata adds\n * cross-process state machinery without changing the common case. If sync\n * workloads grow or the lock-break race becomes observable in practice,\n * revisit by adding heartbeat metadata inside the lock directory (touch mtime\n * periodically; treat as stale only if heartbeat is older than `staleMs`).\n * See: plan-2026-05-17-shared-common-dir-sync-worktree.md §Post-Review\n * Hardening H6.\n */\nexport const DATA_SYNC_LOCK_OPTIONS: Required<LockfileOptions> = {\n  timeoutMs: 35 * 60_000,\n  pollMs: 250,\n  staleMs: 30 * 60_000,\n};\n\n/**\n * Error thrown when the lock cannot be acquired within the timeout.\n */\nexport class LockAcquisitionError extends Error {\n  constructor(lockPath: string, timeoutMs: number) {\n    super(\n      `Failed to acquire lock at ${lockPath} within ${timeoutMs}ms. ` +\n        `Another process may be holding the lock. If this persists, ` +\n        `delete the lock directory manually and retry.`,\n    );\n    this.name = 'LockAcquisitionError';\n  }\n}\n\n/** Filesystem error codes that are transient on Windows and worth retrying. */\nconst TRANSIENT_RMDIR_CODES = new Set(['EBUSY', 'EPERM', 'EACCES', 'ENOTEMPTY']);\n\n/**\n * Remove a lock directory, tolerating transient Windows failures.\n *\n * `rmdir` can intermittently fail with EBUSY/EPERM on Windows (antivirus scanners\n * or lingering directory handles). A few short retries make release reliable; if it\n * still fails, we give up and let stale detection reclaim the directory rather than\n * throwing from a best-effort cleanup path.\n */\nasync function removeLockDir(lockPath: string, attempts = 5): Promise<void> {\n  for (let attempt = 0; attempt < attempts; attempt++) {\n    try {\n      await rmdir(lockPath);\n      return;\n    } catch (error) {\n      const code = (error as NodeJS.ErrnoException).code;\n      if (code === 'ENOENT') {\n        return; // Already gone; nothing to do.\n      }\n      if (attempt < attempts - 1 && code && TRANSIENT_RMDIR_CODES.has(code)) {\n        await new Promise((resolve) => setTimeout(resolve, 20 * (attempt + 1)));\n        continue;\n      }\n      return; // Non-transient or out of attempts: best-effort, leave for stale detection.\n    }\n  }\n}\n\n/**\n * Atomically break a stale lock.\n *\n * Renames the stale directory to a unique sidecar path and removes it. `rename` is\n * atomic, so when several waiters race to break the same stale lock only one wins the\n * rename; the losers see ENOENT and simply retry. This prevents the classic\n * non-atomic break race (rmdir + mkdir) where two waiters both break the lock and both\n * acquire it, defeating mutual exclusion.\n */\nasync function breakStaleLock(lockPath: string): Promise<void> {\n  const sidecar = `${lockPath}.stale-${randomUUID()}`;\n  try {\n    await rename(lockPath, sidecar);\n  } catch {\n    // Another waiter already broke or released it, or the holder is no longer stale.\n    return;\n  }\n  await removeLockDir(sidecar);\n}\n\n/**\n * Execute `fn` while holding a lockfile.\n *\n * The lock is a directory at `lockPath` (typically `<target-file>.lock`).\n * Concurrent callers will wait up to `timeoutMs` for the lock, polling\n * every `pollMs`. Stale locks older than `staleMs` are broken automatically.\n *\n * If the lock cannot be acquired within the timeout, a LockAcquisitionError\n * is thrown. This ensures mutual exclusion is never silently bypassed, which\n * prevents data loss from concurrent writes.\n *\n * @param lockPath - Path to use as the lock directory (e.g., \"/path/to/ids.yml.lock\")\n * @param fn - Critical section to execute under the lock\n * @param options - Timing parameters for lock acquisition\n * @returns The return value of `fn`\n * @throws LockAcquisitionError if the lock cannot be acquired within the timeout\n *\n * @example\n * ```ts\n * await withLockfile('/path/to/ids.yml.lock', async () => {\n *   const data = await readFile('/path/to/ids.yml', 'utf-8');\n *   const updated = mergeEntries(data, newEntries);\n *   await writeFile('/path/to/ids.yml', updated);\n * });\n * ```\n */\nexport async function withLockfile<T>(\n  lockPath: string,\n  fn: () => Promise<T>,\n  options?: LockfileOptions,\n): Promise<T> {\n  const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n  const pollMs = options?.pollMs ?? DEFAULT_POLL_MS;\n  const staleMs = options?.staleMs ?? DEFAULT_STALE_MS;\n\n  const deadline = Date.now() + timeoutMs;\n  let acquired = false;\n\n  while (Date.now() < deadline) {\n    try {\n      // mkdir is atomic per POSIX.1-2017; fails with EEXIST if already held\n      await mkdir(lockPath);\n      acquired = true;\n      break;\n    } catch (error) {\n      if ((error as NodeJS.ErrnoException).code !== 'EEXIST') {\n        // Unexpected error (permissions, disk full, missing parent, etc.):\n        // preserve the original failure instead of misreporting lock contention.\n        throw error;\n      }\n\n      // Lock exists; inspect it.\n      let lockStat;\n      try {\n        lockStat = await stat(lockPath);\n      } catch {\n        // Lock was released between our mkdir and stat; retry immediately\n        continue;\n      }\n\n      // A non-directory at the lock path is unexpected filesystem state. Do not\n      // rename it aside: that would move the user's file out of the way and let the\n      // critical section run unprotected. Fail loudly instead (mirrors how an\n      // unexpected mkdir error is surfaced rather than masked as contention).\n      if (!lockStat.isDirectory()) {\n        throw new Error(\n          `Lock path exists but is not a directory: ${lockPath}. ` +\n            `Refusing to break it; remove the conflicting file and retry.`,\n        );\n      }\n\n      if (Date.now() - lockStat.mtimeMs > staleMs) {\n        // Break atomically so concurrent waiters can't both acquire.\n        await breakStaleLock(lockPath);\n        continue; // Retry immediately after breaking stale lock\n      }\n\n      // Lock is fresh; wait and retry\n      await new Promise((resolve) => setTimeout(resolve, pollMs));\n    }\n  }\n\n  if (!acquired) {\n    throw new LockAcquisitionError(lockPath, timeoutMs);\n  }\n\n  try {\n    return await fn();\n  } finally {\n    // Best-effort cleanup with retry; stale lock detection handles the rest.\n    await removeLockDir(lockPath);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+DA,MAAM,qBAAqB;AAC3B,MAAM,kBAAkB;AACxB,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;AAqBzB,MAAa,yBAAoD;CAC/D,WAAW,KAAK;CAChB,QAAQ;CACR,SAAS,KAAK;CACf;;;;AAKD,IAAa,uBAAb,cAA0C,MAAM;CAC9C,YAAY,UAAkB,WAAmB;AAC/C,QACE,6BAA6B,SAAS,UAAU,UAAU,8GAG3D;AACD,OAAK,OAAO;;;;AAKhB,MAAM,wBAAwB,IAAI,IAAI;CAAC;CAAS;CAAS;CAAU;CAAY,CAAC;;;;;;;;;AAUhF,eAAe,cAAc,UAAkB,WAAW,GAAkB;AAC1E,MAAK,IAAI,UAAU,GAAG,UAAU,UAAU,UACxC,KAAI;AACF,QAAM,MAAM,SAAS;AACrB;UACO,OAAO;EACd,MAAM,OAAQ,MAAgC;AAC9C,MAAI,SAAS,SACX;AAEF,MAAI,UAAU,WAAW,KAAK,QAAQ,sBAAsB,IAAI,KAAK,EAAE;AACrE,SAAM,IAAI,SAAS,YAAY,WAAW,SAAS,MAAM,UAAU,GAAG,CAAC;AACvE;;AAEF;;;;;;;;;;;;AAcN,eAAe,eAAe,UAAiC;CAC7D,MAAM,UAAU,GAAG,SAAS,SAAS,YAAY;AACjD,KAAI;AACF,QAAM,OAAO,UAAU,QAAQ;SACzB;AAEN;;AAEF,OAAM,cAAc,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6B9B,eAAsB,aACpB,UACA,IACA,SACY;CACZ,MAAM,YAAY,SAAS,aAAa;CACxC,MAAM,SAAS,SAAS,UAAU;CAClC,MAAM,UAAU,SAAS,WAAW;CAEpC,MAAM,WAAW,KAAK,KAAK,GAAG;CAC9B,IAAI,WAAW;AAEf,QAAO,KAAK,KAAK,GAAG,SAClB,KAAI;AAEF,QAAM,MAAM,SAAS;AACrB,aAAW;AACX;UACO,OAAO;AACd,MAAK,MAAgC,SAAS,SAG5C,OAAM;EAIR,IAAI;AACJ,MAAI;AACF,cAAW,MAAM,KAAK,SAAS;UACzB;AAEN;;AAOF,MAAI,CAAC,SAAS,aAAa,CACzB,OAAM,IAAI,MACR,4CAA4C,SAAS,gEAEtD;AAGH,MAAI,KAAK,KAAK,GAAG,SAAS,UAAU,SAAS;AAE3C,SAAM,eAAe,SAAS;AAC9B;;AAIF,QAAM,IAAI,SAAS,YAAY,WAAW,SAAS,OAAO,CAAC;;AAI/D,KAAI,CAAC,SACH,OAAM,IAAI,qBAAqB,UAAU,UAAU;AAGrD,KAAI;AACF,SAAO,MAAM,IAAI;WACT;AAER,QAAM,cAAc,SAAS"}

package/dist/paths-C1DpnZJW.mjs

@@ -0,0 +1,405 @@
+import { execFile } from "node:child_process";
+import { access, realpath } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { promisify } from "node:util";
+
+//#region src/lib/git-env.ts
+/**
+* Ambient-git-environment isolation for every git subprocess tbd spawns.
+*
+* tbd is a repo-local tool: it discovers its `.tbd` root by walking up from
+* cwd, so its git context must come from cwd too. But git exports GIT_DIR
+* (and related vars) into hook environments (always, when a hook runs) and
+* an inherited *absolute* GIT_DIR overrides cwd-based discovery in every git
+* child process, `-C <dir>` included. A user running tbd inside any git hook
+* (post-merge, pre-push, …) would otherwise have tbd resolve the hook's
+* repository instead of cwd's and read/write the WRONG repo's tbd data; this
+* is the product-level half of the tbd-a1lc incident (tracked as tbd-tgwi),
+* where exactly that path rewrote a real repo's data-sync state.
+*
+* Policy: tbd always operates on the repository containing cwd. Git location
+* variables are stripped from every git subprocess, and a one-line warning is
+* printed (once per process) when an ambient GIT_DIR was present, so anyone
+* setting it intentionally learns it does not redirect tbd.
+*
+* The same variable list is used by tests/scrub-git-env.ts (vitest worker
+* hygiene) and mirrored in scripts/scrub-git-env.mjs (lefthook wrapper).
+*/
+/** Environment variables through which git overrides cwd-based discovery. */
+const GIT_LOCATION_VARS = [
+	"GIT_DIR",
+	"GIT_WORK_TREE",
+	"GIT_INDEX_FILE",
+	"GIT_COMMON_DIR",
+	"GIT_OBJECT_DIRECTORY",
+	"GIT_ALTERNATE_OBJECT_DIRECTORIES",
+	"GIT_PREFIX",
+	"GIT_NAMESPACE"
+];
+let warnedAmbientGitDir = false;
+/**
+* A copy of process.env with git location variables removed (plus optional
+* overrides), for use as the `env` of any spawned git process. Emits the
+* one-time ambient-GIT_DIR warning as a side effect of first use.
+*/
+function gitSafeEnv(extra) {
+	warnIfAmbientGitEnv();
+	const env = {
+		...process.env,
+		...extra
+	};
+	for (const name of GIT_LOCATION_VARS) delete env[name];
+	return env;
+}
+/**
+* Warn once per process when an ambient GIT_DIR/GIT_WORK_TREE is being
+* ignored. Stderr keeps piped stdout clean; once keeps hooks readable.
+*/
+function warnIfAmbientGitEnv() {
+	if (warnedAmbientGitDir) return;
+	if ((process.env.GIT_DIR ?? process.env.GIT_WORK_TREE) === void 0) return;
+	warnedAmbientGitDir = true;
+	process.stderr.write(`(ignoring inherited GIT_DIR: tbd operates on the repository containing the current directory)\n`);
+}
+
+//#endregion
+//#region src/lib/paths.ts
+/**
+* Centralized path constants for tbd.
+*
+* Directory structure (per spec):
+*
+* On main/dev branches:
+*   .tbd/
+*     Committed to the repo:
+*       config.yml            - Project configuration
+*       .gitignore            - Controls what's gitignored below
+*       workspaces/           - Persistent state (outbox, named workspaces)
+*     Gitignored (local only):
+*       state.yml             - Local state
+*       docs/                 - Installed documentation (regenerated on setup)
+*
+* In the Git common dir shared by all linked worktrees:
+*   $GIT_COMMON_DIR/tbd/
+*     layout.yml              - Shared layout metadata
+*     locks/data-sync.lock/   - Repo-scoped lock directory
+*     backups/                - Local repair/migration backups
+*     data-sync-worktree/     - Hidden worktree checkout of tbd-sync branch
+*       .tbd/data-sync/       - issues/, mappings/, attic/, meta.yml
+*
+* On tbd-sync branch:
+*   .tbd/
+*     data-sync/
+*       issues/
+*       mappings/
+*       attic/
+*       meta.yml
+*/
+/** The tbd configuration directory on main branch */
+const TBD_DIR = ".tbd";
+/** The config file path */
+const CONFIG_FILE = join(TBD_DIR, "config.yml");
+/** The local state file (gitignored) */
+const STATE_FILE = join(TBD_DIR, "state.yml");
+/** The worktree directory name */
+const WORKTREE_DIR_NAME = "data-sync-worktree";
+/** Legacy per-checkout worktree path used by f03 and earlier clients. */
+const LEGACY_WORKTREE_DIR = join(TBD_DIR, WORKTREE_DIR_NAME);
+/**
+* @internal Primary-checkout relative path to the shared sync worktree.
+*
+* Only valid when `.git` is a directory (i.e., the primary checkout). Production
+* code must call resolveSharedTbdPaths() instead: linked worktrees have a `.git`
+* file, so this constant resolves to the wrong location for them. Intended for
+* tests and the non-git fallback in resolveDataSyncDir().
+*/
+const PRIMARY_CHECKOUT_WORKTREE_DIR = join(".git", "tbd", WORKTREE_DIR_NAME);
+/** The data directory name on the sync branch */
+const DATA_SYNC_DIR_NAME = "data-sync";
+/**
+* The data directory path as it appears on the tbd-sync branch.
+* In a normal checkout this same relative path is a legacy/wrong-location fallback;
+* production callers should resolve the absolute shared worktree path with
+* resolveDataSyncDir().
+*/
+const DATA_SYNC_DIR = join(TBD_DIR, DATA_SYNC_DIR_NAME);
+/**
+* @internal Primary-checkout relative path to the synced data via the shared worktree.
+*
+* Same caveat as `PRIMARY_CHECKOUT_WORKTREE_DIR`: only valid for a primary checkout.
+* Production code should resolve the absolute path with resolveDataSyncDir(); this
+* constant is intended for tests and the non-git fallback path.
+*/
+const PRIMARY_CHECKOUT_DATA_SYNC_DIR = join(PRIMARY_CHECKOUT_WORKTREE_DIR, TBD_DIR, DATA_SYNC_DIR_NAME);
+/** Issues directory */
+const ISSUES_DIR = join(DATA_SYNC_DIR, "issues");
+/** Mappings directory */
+const MAPPINGS_DIR = join(DATA_SYNC_DIR, "mappings");
+/** Attic directory for conflict resolution */
+const ATTIC_DIR = join(DATA_SYNC_DIR, "attic");
+/** Meta file for schema version */
+const META_FILE = join(DATA_SYNC_DIR, "meta.yml");
+/** The sync branch name */
+const SYNC_BRANCH = "tbd-sync";
+const execFileAsync = promisify(execFile);
+/** Directory name under $GIT_COMMON_DIR for tbd local machinery. */
+const GIT_COMMON_TBD_DIR_NAME = "tbd";
+/** Common-dir layout metadata file name. */
+const COMMON_DIR_LAYOUT_FILE_NAME = "layout.yml";
+/** Shared lock directory name under $GIT_COMMON_DIR/tbd/. */
+const SHARED_LOCKS_DIR_NAME = "locks";
+/** Shared backups directory name under $GIT_COMMON_DIR/tbd/. */
+const SHARED_BACKUPS_DIR_NAME = "backups";
+/** Directory-lock name for shared data-sync operations. */
+const DATA_SYNC_LOCK_DIR_NAME = "data-sync.lock";
+/**
+* Resolve Git's common directory from any checkout or linked worktree.
+*/
+async function resolveGitCommonDir(cwd) {
+	let output;
+	try {
+		const { stdout } = await execFileAsync("git", [
+			"-C",
+			cwd,
+			"rev-parse",
+			"--git-common-dir"
+		], {
+			env: gitSafeEnv(),
+			maxBuffer: 1024 * 1024
+		});
+		output = stdout.trim();
+	} catch {
+		const { stdout } = await execFileAsync("git", [
+			"-C",
+			cwd,
+			"rev-parse",
+			"--path-format=absolute",
+			"--git-common-dir"
+		], {
+			env: gitSafeEnv(),
+			maxBuffer: 1024 * 1024
+		});
+		output = stdout.trim();
+	}
+	if (!output) throw new Error(`Unable to resolve Git common directory from ${cwd}`);
+	const gitCommonDir = isAbsolute(output) ? output : resolve(cwd, output);
+	return realpath(gitCommonDir).catch(() => gitCommonDir);
+}
+/**
+* Build all shared tbd paths from an absolute Git common directory.
+*/
+function buildSharedTbdPaths(gitCommonDir) {
+	const sharedTbdDir = join(gitCommonDir, GIT_COMMON_TBD_DIR_NAME);
+	const sharedWorktreePath = join(sharedTbdDir, WORKTREE_DIR_NAME);
+	const sharedDataSyncDir = join(sharedWorktreePath, TBD_DIR, DATA_SYNC_DIR_NAME);
+	const sharedLayoutPath = join(sharedTbdDir, COMMON_DIR_LAYOUT_FILE_NAME);
+	const sharedLocksDir = join(sharedTbdDir, SHARED_LOCKS_DIR_NAME);
+	return {
+		gitCommonDir,
+		sharedTbdDir,
+		sharedWorktreePath,
+		sharedDataSyncDir,
+		sharedLayoutPath,
+		sharedLocksDir,
+		sharedLockPath: join(sharedLocksDir, DATA_SYNC_LOCK_DIR_NAME),
+		sharedBackupsDir: join(sharedTbdDir, SHARED_BACKUPS_DIR_NAME)
+	};
+}
+/**
+* Resolve the shared tbd paths for the repository containing baseDir.
+*/
+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/ */
+const WORKSPACES_DIR = join(TBD_DIR, WORKSPACES_DIR_NAME);
+/**
+* Get the path to a named workspace directory.
+*
+* Workspaces are stored at: .tbd/workspaces/{name}/
+*
+* @param workspaceName - The name of the workspace (e.g., 'outbox', 'my-feature')
+* @returns Path to the workspace directory
+*/
+function getWorkspaceDir(workspaceName) {
+	return join(WORKSPACES_DIR, workspaceName);
+}
+/**
+* Validate a workspace name.
+*
+* Valid workspace names:
+* - Lowercase alphanumeric characters
+* - Hyphens and underscores allowed
+* - Must not be empty
+* - Must not contain path separators or dots at start
+*
+* @param name - The workspace name to validate
+* @returns true if the name is valid
+*/
+function isValidWorkspaceName(name) {
+	if (!name || name.length === 0) return false;
+	if (name.startsWith(".")) return false;
+	return /^[a-z0-9][a-z0-9_-]*$/.test(name);
+}
+/** Docs directory name within .tbd/ */
+const DOCS_DIR = "docs";
+/** Shortcuts directory name within docs/ */
+const SHORTCUTS_DIR = "shortcuts";
+/** System shortcuts directory name (core docs like skill-baseline.md) */
+const SYSTEM_DIR = "system";
+/** Standard shortcuts directory name (workflow shortcuts) */
+const STANDARD_DIR = "standard";
+/** Guidelines directory name (coding rules and best practices) */
+const GUIDELINES_DIR = "guidelines";
+/** Templates directory name (document templates) */
+const TEMPLATES_DIR = "templates";
+/** Full path to docs directory: .tbd/docs/ */
+const TBD_DOCS_DIR = join(TBD_DIR, DOCS_DIR);
+/** Full path to shortcuts directory: .tbd/docs/shortcuts/ */
+const TBD_SHORTCUTS_DIR = join(TBD_DOCS_DIR, SHORTCUTS_DIR);
+/** Full path to system shortcuts: .tbd/docs/shortcuts/system/ */
+const TBD_SHORTCUTS_SYSTEM = join(TBD_SHORTCUTS_DIR, SYSTEM_DIR);
+/** Full path to standard shortcuts: .tbd/docs/shortcuts/standard/ */
+const TBD_SHORTCUTS_STANDARD = join(TBD_SHORTCUTS_DIR, STANDARD_DIR);
+/** Full path to guidelines: .tbd/docs/guidelines/ (top-level, not under shortcuts) */
+const TBD_GUIDELINES_DIR = join(TBD_DOCS_DIR, GUIDELINES_DIR);
+/** Full path to templates: .tbd/docs/templates/ (top-level, not under shortcuts) */
+const TBD_TEMPLATES_DIR = join(TBD_DOCS_DIR, TEMPLATES_DIR);
+/** Built-in docs source paths (relative to package docs/) */
+const BUILTIN_SHORTCUTS_SYSTEM = join(SHORTCUTS_DIR, SYSTEM_DIR);
+const BUILTIN_SHORTCUTS_STANDARD = join(SHORTCUTS_DIR, STANDARD_DIR);
+/** References directory name (tbd self-docs and format references). */
+const REFERENCES_DIR = "references";
+/** Cached reference docs directory (docref/docmap formats, tbd-docs, tbd-design). */
+const TBD_REFERENCES_DIR = join(TBD_DOCS_DIR, REFERENCES_DIR);
+/**
+* Default fork directory (repo-relative), where forked docs are made visible.
+* A POSIX literal, not join()'d: this value is committed (manifest paths) and
+* printed, so it must be identical on every platform; fs access joins it with
+* the root via join(), which accepts forward slashes on Windows.
+*/
+const FORK_DIR = "docs/tbd";
+/** Fork-dir kind subdirectories (repo-relative). */
+const FORK_SHORTCUTS_DIR = `${FORK_DIR}/${SHORTCUTS_DIR}`;
+const FORK_GUIDELINES_DIR = `${FORK_DIR}/${GUIDELINES_DIR}`;
+const FORK_TEMPLATES_DIR = `${FORK_DIR}/${TEMPLATES_DIR}`;
+const FORK_REFERENCES_DIR = `${FORK_DIR}/${REFERENCES_DIR}`;
+/**
+* Cache-only lookup paths (the gitignored `.tbd/docs/` cache), used when forking
+* needs the pristine upstream content rather than a possibly-forked copy.
+*/
+const CACHE_SHORTCUT_PATHS = [TBD_SHORTCUTS_SYSTEM, TBD_SHORTCUTS_STANDARD];
+const CACHE_GUIDELINES_PATHS = [TBD_GUIDELINES_DIR];
+const CACHE_TEMPLATE_PATHS = [TBD_TEMPLATES_DIR];
+const CACHE_REFERENCE_PATHS = [TBD_REFERENCES_DIR];
+/**
+* Default shortcut lookup paths (searched in order, relative to tbd root).
+* Earlier paths take precedence: the fork dir shadows the cache, so a forked doc
+* is served wherever the upstream one was. Missing dirs are skipped, so repos with
+* no forks behave exactly as before.
+*/
+const DEFAULT_SHORTCUT_PATHS = [FORK_SHORTCUTS_DIR, ...CACHE_SHORTCUT_PATHS];
+/**
+* Default guidelines lookup paths (relative to tbd root).
+*/
+const DEFAULT_GUIDELINES_PATHS = [FORK_GUIDELINES_DIR, ...CACHE_GUIDELINES_PATHS];
+/**
+* Default template lookup paths (relative to tbd root).
+*/
+const DEFAULT_TEMPLATE_PATHS = [FORK_TEMPLATES_DIR, ...CACHE_TEMPLATE_PATHS];
+/**
+* Default reference-doc lookup paths (relative to tbd root).
+*/
+const DEFAULT_REFERENCE_PATHS = [FORK_REFERENCES_DIR, ...CACHE_REFERENCE_PATHS];
+/**
+* Error thrown when worktree is missing and fallback is not allowed.
+* Defined inline to avoid circular dependency with errors.ts.
+*/
+var WorktreeMissingError = class extends Error {
+	constructor(message = "Shared worktree not found under $GIT_COMMON_DIR/tbd/data-sync-worktree/. Run 'tbd doctor --fix' to repair.") {
+		super(message);
+		this.name = "WorktreeMissingError";
+	}
+};
+/**
+* Cache for resolved data sync directory.
+* Reset when baseDir changes.
+*/
+let _resolvedDataSyncDir = null;
+let _resolvedBaseDir = null;
+let _resolvedAllowFallback = null;
+/**
+* Resolve the actual data sync directory path.
+*
+* This function detects whether we're running with a git worktree
+* (production) or in a test environment without worktree.
+*
+* Order of preference:
+* 1. Shared worktree path if it exists:
+*    $GIT_COMMON_DIR/tbd/data-sync-worktree/.tbd/data-sync/
+* 2. Direct path as fallback (only if allowFallback: true, for tests/diagnostics)
+*
+* @param baseDir - The tbd root directory (from requireInit or findTbdRoot)
+* @param options - Options for path resolution
+* @returns Resolved data sync directory path
+* @throws WorktreeMissingError if worktree missing and allowFallback is false
+*
+* See: plan-2026-01-28-sync-worktree-recovery-and-hardening.md
+*/
+async function resolveDataSyncDir(baseDir, options) {
+	const allowFallback = options?.allowFallback ?? true;
+	if (_resolvedDataSyncDir && _resolvedBaseDir === baseDir && _resolvedAllowFallback === allowFallback) return _resolvedDataSyncDir;
+	let worktreePath = null;
+	try {
+		worktreePath = (await resolveSharedTbdPaths(baseDir)).sharedDataSyncDir;
+	} catch {
+		worktreePath = join(baseDir, PRIMARY_CHECKOUT_DATA_SYNC_DIR);
+	}
+	const directPath = join(baseDir, DATA_SYNC_DIR);
+	if (worktreePath) try {
+		await access(worktreePath);
+		_resolvedDataSyncDir = worktreePath;
+		_resolvedBaseDir = baseDir;
+		_resolvedAllowFallback = allowFallback;
+		return worktreePath;
+	} catch {}
+	if (!allowFallback) throw new WorktreeMissingError();
+	if (process.env.DEBUG || process.env.TBD_DEBUG) console.warn("[tbd:paths] resolveDataSyncDir: worktree not found, falling back to direct path");
+	return directPath;
+}
+/**
+* Resolve attic directory path.
+*/
+async function resolveAtticDir(baseDir, options) {
+	return join(await resolveDataSyncDir(baseDir, options), "attic");
+}
+/**
+* Characters per token ratio for estimating token counts.
+*
+* Based on research of OpenAI (tiktoken) and Claude tokenizers:
+* - Pure English prose: ~4-5 chars/token
+* - Code and symbols: ~3 chars/token
+* - Mixed markdown/code docs: ~3.5 chars/token
+*
+* We use 3.5 as our docs are markdown with code examples.
+* This provides ~15-20% accuracy, sufficient for cost estimation.
+*/
+const CHARS_PER_TOKEN = 3.5;
+
+//#endregion
+export { isCommonDirOutsideProject as A, TBD_GUIDELINES_DIR as C, WORKSPACES_DIR as D, TBD_TEMPLATES_DIR as E, gitSafeEnv as F, resolveAtticDir as M, resolveDataSyncDir as N, WORKTREE_DIR_NAME as O, resolveSharedTbdPaths as P, TBD_DOCS_DIR as S, TBD_SHORTCUTS_SYSTEM as T, FORK_TEMPLATES_DIR as _, CHARS_PER_TOKEN as a, SYNC_BRANCH as b, DATA_SYNC_DIR_NAME as c, DEFAULT_SHORTCUT_PATHS as d, DEFAULT_TEMPLATE_PATHS as f, FORK_SHORTCUTS_DIR as g, FORK_REFERENCES_DIR as h, CACHE_TEMPLATE_PATHS as i, isValidWorkspaceName as j, getWorkspaceDir as k, DEFAULT_GUIDELINES_PATHS as l, FORK_GUIDELINES_DIR as m, CACHE_REFERENCE_PATHS as n, CONFIG_FILE as o, FORK_DIR as p, CACHE_SHORTCUT_PATHS as r, DATA_SYNC_DIR as s, CACHE_GUIDELINES_PATHS as t, DEFAULT_REFERENCE_PATHS as u, LEGACY_WORKTREE_DIR as v, TBD_SHORTCUTS_STANDARD as w, TBD_DIR as x, STATE_FILE as y };
+//# sourceMappingURL=paths-C1DpnZJW.mjs.map