@linxiraos/pi-utils 1.1.4 → 1.1.6

package/src/color.ts

@@ -272,6 +272,179 @@ function linearizeChannel(channel: number): number {
 	const c = channel / 255;
 	return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
 }
+/** Gamma-encode a linear 0..1 channel back to 0..255 sRGB. */
+function delinearizeChannel(linear: number): number {
+	const c = linear <= 0.0031308 ? linear * 12.92 : 1.055 * linear ** (1 / 2.4) - 0.055;
+	return c * 255;
+}
+
+export interface OKLCH {
+	/** Perceptual lightness (0-1) */
+	l: number;
+	/** Chroma (0 = gray; sRGB peaks around 0.37) */
+	c: number;
+	/** Hue in degrees (0-360) */
+	h: number;
+}
+
+/** Convert linear sRGB (0..1 channels) to OKLab (Björn Ottosson's reference matrices). */
+function linearRgbToOklab(r: number, g: number, b: number): { L: number; a: number; b: number } {
+	const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
+	const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
+	const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
+	return {
+		L: 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+		a: 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+		b: 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
+	};
+}
+
+/** Convert OKLab back to linear sRGB; channels may fall outside 0..1 when out of gamut. */
+function oklabToLinearRgb(L: number, a: number, b: number): { r: number; g: number; b: number } {
+	const l = (L + 0.3963377774 * a + 0.2158037573 * b) ** 3;
+	const m = (L - 0.1055613458 * a - 0.0638541728 * b) ** 3;
+	const s = (L - 0.0894841775 * a - 1.291485548 * b) ** 3;
+	return {
+		r: 4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+		g: -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+		b: -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
+	};
+}
+
+/**
+ * Convert a hex color to OKLCH (perceptual lightness/chroma/hue).
+ *
+ * Unlike HSL, equal `l`/`c` values look equally bright and colorful across
+ * hues, so carrying them between colors preserves the palette's "weight".
+ */
+export function hexToOklch(hex: string): OKLCH {
+	const rgb = hexToRgb(hex);
+	const lab = linearRgbToOklab(linearizeChannel(rgb.r), linearizeChannel(rgb.g), linearizeChannel(rgb.b));
+	const c = Math.hypot(lab.a, lab.b);
+	let h = (Math.atan2(lab.b, lab.a) * 180) / Math.PI;
+	if (h < 0) h += 360;
+	return { l: lab.L, c, h };
+}
+
+/**
+ * Max OKLab saturation (C/L) that stays inside sRGB for the hue direction
+ * `(a, b)`, via Björn Ottosson's polynomial fit plus one Halley refinement.
+ */
+function computeMaxSaturation(a: number, b: number): number {
+	// Select the channel that clips first for this hue direction.
+	let k0: number, k1: number, k2: number, k3: number, k4: number;
+	let wl: number, wm: number, ws: number;
+	if (-1.88170328 * a - 0.80936493 * b > 1) {
+		// red channel
+		k0 = 1.19086277;
+		k1 = 1.76576728;
+		k2 = 0.59662641;
+		k3 = 0.75515197;
+		k4 = 0.56771245;
+		wl = 4.0767416621;
+		wm = -3.3077115913;
+		ws = 0.2309699292;
+	} else if (1.81444104 * a - 1.19445276 * b > 1) {
+		// green channel
+		k0 = 0.73956515;
+		k1 = -0.45954404;
+		k2 = 0.08285427;
+		k3 = 0.1254107;
+		k4 = 0.14503204;
+		wl = -1.2684380046;
+		wm = 2.6097574011;
+		ws = -0.3413193965;
+	} else {
+		// blue channel
+		k0 = 1.35733652;
+		k1 = -0.00915799;
+		k2 = -1.1513021;
+		k3 = -0.50559606;
+		k4 = 0.00692167;
+		wl = -0.0041960863;
+		wm = -0.7034186147;
+		ws = 1.707614701;
+	}
+	const S = k0 + k1 * a + k2 * b + k3 * a * a + k4 * a * b;
+
+	// One Halley step against f = (channel at S) - 0: polishes the fit to
+	// well below hex quantization error.
+	const kl = 0.3963377774 * a + 0.2158037573 * b;
+	const km = -0.1055613458 * a - 0.0638541728 * b;
+	const ks = -0.0894841775 * a - 1.291485548 * b;
+	const l_ = 1 + S * kl;
+	const m_ = 1 + S * km;
+	const s_ = 1 + S * ks;
+	const f = wl * l_ ** 3 + wm * m_ ** 3 + ws * s_ ** 3;
+	const f1 = wl * 3 * kl * l_ * l_ + wm * 3 * km * m_ * m_ + ws * 3 * ks * s_ * s_;
+	const f2 = wl * 6 * kl * kl * l_ + wm * 6 * km * km * m_ + ws * 6 * ks * ks * s_;
+	return S - (f * f1) / (f1 * f1 - 0.5 * f * f2);
+}
+
+/**
+ * The sRGB gamut cusp for an OKLCH hue: the lightness/chroma point where the
+ * hue reaches its maximum chroma inside sRGB.
+ *
+ * The cusp lightness varies wildly per hue (yellow ≈ 0.97, blue ≈ 0.45), so
+ * transferring absolute OKLCH lightness/chroma between hues distorts
+ * vividness; normalize against the cusp instead. See `getSessionAccentHex`.
+ */
+export function oklchCusp(h: number): { l: number; c: number } {
+	const hRad = (h * Math.PI) / 180;
+	const a = Math.cos(hRad);
+	const b = Math.sin(hRad);
+	const sCusp = computeMaxSaturation(a, b);
+	const rgb = oklabToLinearRgb(1, sCusp * a, sCusp * b);
+	const lCusp = Math.cbrt(1 / Math.max(rgb.r, rgb.g, rgb.b));
+	return { l: lCusp, c: lCusp * sCusp };
+}
+
+/** Slack allowed on linear channels before a color counts as out of sRGB gamut. */
+const GAMUT_EPSILON = 1e-4;
+
+/** True when all linear channels sit inside sRGB (within {@link GAMUT_EPSILON}). */
+function inSrgbGamut(rgb: { r: number; g: number; b: number }): boolean {
+	return (
+		rgb.r >= -GAMUT_EPSILON &&
+		rgb.r <= 1 + GAMUT_EPSILON &&
+		rgb.g >= -GAMUT_EPSILON &&
+		rgb.g <= 1 + GAMUT_EPSILON &&
+		rgb.b >= -GAMUT_EPSILON &&
+		rgb.b <= 1 + GAMUT_EPSILON
+	);
+}
+
+/**
+ * Convert OKLCH to a CSS hex string, gamut-mapping by chroma reduction.
+ *
+ * Out-of-gamut inputs keep their lightness and hue while chroma is bisected
+ * down until the color fits sRGB, matching CSS Color 4's recommended intent.
+ */
+export function oklchToHex(oklch: OKLCH): string {
+	const l = Math.max(0, Math.min(1, oklch.l));
+	const hRad = (oklch.h * Math.PI) / 180;
+	const cos = Math.cos(hRad);
+	const sin = Math.sin(hRad);
+	const at = (c: number) => oklabToLinearRgb(l, c * cos, c * sin);
+
+	let rgb = at(oklch.c);
+	if (!inSrgbGamut(rgb)) {
+		// `lo` always fits (chroma 0 is the gray axis), `hi` never does.
+		let lo = 0;
+		let hi = oklch.c;
+		for (let i = 0; i < 20; i++) {
+			const mid = (lo + hi) / 2;
+			if (inSrgbGamut(at(mid))) lo = mid;
+			else hi = mid;
+		}
+		rgb = at(lo);
+	}
+	return rgbToHex({
+		r: Math.max(0, Math.min(255, delinearizeChannel(rgb.r))),
+		g: Math.max(0, Math.min(255, delinearizeChannel(rgb.g))),
+		b: Math.max(0, Math.min(255, delinearizeChannel(rgb.b))),
+	});
+}
 
 /**
  * Perceptual luma (gamma-encoded BT.709 weights over raw sRGB), normalized to 0..1.

package/src/dirs.ts

@@ -1,12 +1,12 @@
 /**
- * Centralized path helpers for omp config directories.
+ * Centralized path helpers for zeta config directories.
  *
  * Uses PI_CONFIG_DIR (default ".zeta") for the config root and
  * PI_CODING_AGENT_DIR to override the agent directory.
  *
  * On Linux, if XDG_DATA_HOME / XDG_STATE_HOME / XDG_CACHE_HOME environment
  * variables are set, paths are redirected to XDG-compliant locations under
- * $XDG_*_HOME/omp/. This requires running `zeta config migrate` first to
+ * $XDG_*_HOME/zeta/. This requires running `zeta config migrate` first to
  * move data to the new locations. No filesystem existence checks are performed
  * — if the env var is set, omp trusts that the migration has been done.
  */
@@ -15,8 +15,9 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { engines, version } from "../package.json" with { type: "json" };
+import { isEnoent, isEnotdir } from "./fs-error";
 
-/** App name (e.g. "zeta") */
+/** App name (e.g. "omp") */
 export const APP_NAME: string = "zeta";
 
 /** Config directory name (e.g. ".zeta") */
@@ -28,7 +29,7 @@ export const MAIN_CONFIG_FILENAMES = ["config.yml", "config.yaml"] as const;
 /** Version (e.g. "1.0.0") */
 export const VERSION: string = version;
 
-/** Default User-Agent header string (e.g. "zeta/1.0.10") */
+/** Default User-Agent header string (e.g. "zeta/1.1.5") */
 export const USER_AGENT = `zeta/${VERSION}`;
 
 /** Minimum Bun version */
@@ -178,17 +179,50 @@ export function relativePathWithinRoot(root: string, candidate: string): string
 	return relative || null;
 }
 
-let projectDir = standardizeMacOSPath(process.cwd());
+let projectDir: string | undefined;
 
 /** Get the project directory. */
 export function getProjectDir(): string {
+	if (projectDir === undefined) {
+		try {
+			projectDir = standardizeMacOSPath(process.cwd());
+		} catch {
+			const candidates = [process.env.PWD, os.homedir(), os.tmpdir()];
+			for (const candidate of candidates) {
+				if (!candidate || !path.isAbsolute(candidate)) continue;
+				try {
+					process.chdir(candidate);
+					projectDir = standardizeMacOSPath(candidate);
+					break;
+				} catch {}
+			}
+			if (projectDir === undefined) {
+				throw new Error("Unable to determine an accessible working directory");
+			}
+		}
+	}
 	return projectDir;
 }
 
 /** Set the project directory. */
 export function setProjectDir(dir: string): void {
-	projectDir = standardizeMacOSPath(path.resolve(dir));
-	process.chdir(projectDir);
+	const resolved = standardizeMacOSPath(path.resolve(dir));
+	process.chdir(resolved);
+	projectDir = resolved;
+}
+
+/** Reset the cached project directory (test seam). */
+export function __resetProjectDirCacheForTests(): void {
+	projectDir = undefined;
+}
+
+/** Whether a path is absent or not a directory. Other stat failures return false. */
+export async function directoryIsMissing(dir: string): Promise<boolean> {
+	try {
+		return !(await fs.promises.stat(dir)).isDirectory();
+	} catch (error) {
+		return isEnoent(error) || isEnotdir(error);
+	}
 }
 
 /**
@@ -205,33 +239,49 @@ export async function directoryExists(dir: string): Promise<boolean> {
 	}
 }
 
-/** Get the config directory name relative to home (e.g. ".zeta" or PI_CONFIG_DIR override). */
-export function getConfigDirName(): string {
-	if (process.env.PI_CONFIG_DIR) return process.env.PI_CONFIG_DIR;
-	return ".zeta";
-}
-
 /**
- * One-time migration of a legacy `~/.omp` config root to `~/.zeta`. Called
- * from the CLI entrypoint before any user data is written; it only moves the
- * directory when `.zeta` does not exist yet. Zeta keeps no `.omp`
- * compatibility surface afterwards (see AGENTS.md), so this is the single
- * exception that honors pre-existing installs.
+ * Whether `dir` both exists and can be entered. POSIX `stat` succeeds for a
+ * directory whose own search/execute permission is denied (it only needs
+ * +x on the parent chain), so existence alone does not imply `chdir` works.
+ * Callers that adopt a directory as a working directory must check this
+ * rather than {@link directoryExists} alone.
  */
-export function migrateLegacyOmpConfigDir(): void {
-	if (process.env.PI_CONFIG_DIR) return;
-	const home = os.homedir();
+export async function directoryIsEnterable(dir: string): Promise<boolean> {
+	try {
+		const [stats] = await Promise.all([fs.promises.stat(dir), fs.promises.access(dir, fs.constants.X_OK)]);
+		return stats.isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+/** Whether `dir` is enterable, synchronous variant. See {@link directoryIsEnterable}. */
+export function directoryIsEnterableSync(dir: string): boolean {
 	try {
-		const zetaDir = path.join(home, ".zeta");
-		if (fs.existsSync(zetaDir)) return;
-		const ompDir = path.join(home, ".omp");
-		if (!fs.existsSync(ompDir)) return;
-		fs.renameSync(ompDir, zetaDir);
+		fs.accessSync(dir, fs.constants.X_OK);
+		return fs.statSync(dir).isDirectory();
 	} catch {
-		// Migration is best-effort; a failed rename must not break startup.
+		return false;
 	}
 }
 
+/**
+ * Project directory when it is enterable, otherwise a safe fallback.
+ * Used by spawns that must preserve project-relative behavior when healthy.
+ */
+export function getSafeProjectCwd(): string {
+	try {
+		const dir = getProjectDir();
+		if (directoryIsEnterableSync(dir)) return dir;
+	} catch {}
+	return os.homedir();
+}
+
+/** Get the config directory name relative to home (e.g. ".zeta" or PI_CONFIG_DIR override). */
+export function getConfigDirName(): string {
+	return process.env.PI_CONFIG_DIR || CONFIG_DIR_NAME;
+}
+
 /** Get the config agent directory name relative to home (e.g. ".zeta/agent" or PI_CONFIG_DIR + "/agent"). */
 export function getConfigAgentDirName(): string {
 	const profile = getActiveProfile();
@@ -246,7 +296,7 @@ type XdgCategory = "data" | "state" | "cache";
 
 /**
  * Resolves and caches all omp directory paths. On Linux, when XDG environment
- * variables are set, paths are redirected under $XDG_*_HOME/omp/. A new
+ * variables are set, paths are redirected under $XDG_*_HOME/zeta/. A new
  * instance is created whenever the agent directory changes, which naturally
  * invalidates all cached paths.
  */
@@ -255,7 +305,7 @@ class DirResolver {
 	readonly agentDir: string;
 
 	// Per-category base dirs. Without XDG, all three equal configRoot / agentDir.
-	// With XDG on Linux, they point to $XDG_*_HOME/omp/.
+	// With XDG on Linux, they point to $XDG_*_HOME/zeta/.
 	readonly #rootDirs: Record<XdgCategory, string>;
 	readonly #agentDirs: Record<XdgCategory, string>;
 
@@ -272,14 +322,14 @@ class DirResolver {
 		const isDefault = this.agentDir === defaultAgent;
 
 		// XDG is a Linux convention. On supported platforms, default profile state
-		// resolves under $XDG_*_HOME/omp once `zeta config init-xdg` has migrated
+		// resolves under $XDG_*_HOME/zeta once `zeta config init-xdg` has migrated
 		// the user's data. Named profiles follow a stricter rule: the XDG choice
 		// is keyed on the profile-specific XDG path, never the base app root.
 		//
 		// Why: if we consulted the base app root for named profiles too, the same
 		// profile could resolve to `~/.zeta/profiles/<name>` on first activation
-		// (when no $XDG_*_HOME/omp exists yet) and then silently move to
-		// `$XDG_*_HOME/omp/profiles/<name>` the moment the base appeared, orphaning
+		// (when no $XDG_*_HOME/zeta exists yet) and then silently move to
+		// `$XDG_*_HOME/zeta/profiles/<name>` the moment the base appeared, orphaning
 		// the earlier state. Pinning on the profile path means a profile's location
 		// is decided at first activation and stays put until the user explicitly
 		// migrates it (e.g. by mkdir'ing the XDG profile dir).
@@ -521,7 +571,7 @@ export function getAgentDir(): string {
 
 /** Get the project-local config directory (.zeta). */
 export function getProjectAgentDir(cwd: string = getProjectDir()): string {
-	return path.join(cwd, ".zeta");
+	return path.join(cwd, CONFIG_DIR_NAME);
 }
 
 // =============================================================================
@@ -538,7 +588,7 @@ export function getLogsDir(): string {
 	return dirs.rootSubdir("logs", "state");
 }
 
-/** Get this process's dated log path (~/.zeta/logs/zeta.YYYY-MM-DD.PID.log). */
+/** Get this process's dated log path (~/.zeta/logs/omp.YYYY-MM-DD.PID.log). */
 export function getLogPath(date = new Date(), pid = process.pid): string {
 	return path.join(getLogsDir(), `${APP_NAME}.${date.toISOString().slice(0, 10)}.${pid}.log`);
 }
@@ -555,7 +605,7 @@ export function getLogPath(date = new Date(), pid = process.pid): string {
  */
 export function getPluginsDir(home?: string): string {
 	if (home !== undefined && home !== RESOLVER_HOME) {
-		return path.join(home, CONFIG_DIR_NAME, "plugins");
+		return path.join(home, getConfigDirName(), "plugins");
 	}
 	return dirs.rootSubdir("plugins", "data");
 }
@@ -570,9 +620,9 @@ export function getPluginsPackageJson(home?: string): string {
 	return path.join(getPluginsDir(home), "package.json");
 }
 
-/** Plugin lock file (~/.zeta/plugins/zeta-plugins.lock.json). */
+/** Plugin lock file (~/.zeta/plugins/omp-plugins.lock.json). */
 export function getPluginsLockfile(home?: string): string {
-	return path.join(getPluginsDir(home), "zeta-plugins.lock.json");
+	return path.join(getPluginsDir(home), "omp-plugins.lock.json");
 }
 
 /** Get the remote mount directory (~/.zeta/remote). */
@@ -585,7 +635,7 @@ export function getRemoteDir(): string {
  * empty/whitespace input or a path that is still relative after expansion.
  *
  * A worktree base is process-global and consumed by both creation
- * (PR checkout, task isolation) and cleanup (`zeta worktree`). A relative value
+ * (PR checkout, task isolation) and cleanup (`omp worktree`). A relative value
  * would resolve against whatever cwd happened to launch `omp`, so checkout and
  * cleanup could disagree — we refuse it rather than silently bind it to cwd.
  */
@@ -602,7 +652,7 @@ let worktreesDirOverride: string | undefined;
 
 /**
  * Relocate the base directory for agent-managed worktrees (PR checkouts, task
- * isolation, and `zeta worktree` cleanup all read the same base). Driven by the
+ * isolation, and `omp worktree` cleanup all read the same base). Driven by the
  * `worktree.base` setting in coding-agent; pass `undefined`/empty to clear and
  * fall back to `OMP_WORKTREE_DIR` or the `~/.zeta/wt` default.
  *
@@ -699,6 +749,15 @@ export function getGithubCacheDbPath(): string {
 	if (override) return override;
 	return dirs.rootSubdir(path.join("cache", "github-cache.db"), "cache");
 }
+/**
+ * Get the conventional commit inference cache database path (~/.zeta/cache/commit-inference.db).
+ * Honors `OMP_COMMIT_CACHE_DB` so tests and operators can isolate the cache.
+ */
+export function getCommitCacheDbPath(): string {
+	const override = process.env.OMP_COMMIT_CACHE_DB;
+	if (override) return override;
+	return dirs.rootSubdir(path.join("cache", "commit-inference.db"), "cache");
+}
 
 /** Get the legacy Pi extension parse cache database path. */
 export function getLegacyPiExtensionCacheDbPath(): string {
@@ -716,12 +775,12 @@ export function getAuthBrokerSnapshotCachePath(): string {
 	return dirs.rootSubdir(path.join("cache", "auth-broker-snapshot.enc"), "cache");
 }
 
-/** Get the local FastEmbed model cache directory (~/.zeta/cache/fastembed). */
-/** Get the commit-author avatar cache directory (~/.omp/cache/avatars). */
+/** Get the commit-author avatar cache directory (~/.zeta/cache/avatars). */
 export function getAvatarCacheDir(): string {
 	return dirs.rootSubdir(path.join("cache", "avatars"), "cache");
 }
-/** Get the local FastEmbed model cache directory (~/.omp/cache/fastembed). */
+
+/** Get the local FastEmbed model cache directory (~/.zeta/cache/fastembed). */
 export function getFastembedCacheDir(): string {
 	return dirs.rootSubdir(path.join("cache", "fastembed"), "cache");
 }
@@ -804,6 +863,10 @@ export function getTinyModelsCacheDir(agentDir?: string): string {
 export function getDocumentConversionCacheDir(agentDir?: string): string {
 	return dirs.agentSubdir(agentDir, path.join("cache", "document-conversions"), "cache");
 }
+/** Get the per-project composer speculative cache directory (~/.zeta/agent/cache/composer; XDG default: $XDG_CACHE_HOME/zeta/cache/composer). */
+export function getComposerCacheDir(agentDir?: string): string {
+	return dirs.agentSubdir(agentDir, path.join("cache", "composer"), "cache");
+}
 
 /** Get the sessions directory (~/.zeta/agent/sessions). */
 export function getSessionsDir(agentDir?: string): string {
@@ -850,12 +913,12 @@ export function getTerminalSessionsDir(agentDir?: string): string {
 	return dirs.agentSubdir(agentDir, "terminal-sessions", "state");
 }
 
-/** Get the crash log path (~/.zeta/agent/zeta-crash.log). */
+/** Get the crash log path (~/.zeta/agent/omp-crash.log). */
 export function getCrashLogPath(agentDir?: string): string {
-	return dirs.agentSubdir(agentDir, "zeta-crash.log", "state");
+	return dirs.agentSubdir(agentDir, "omp-crash.log", "state");
 }
 
-/** Get the debug log path (~/.zeta/agent/zeta-debug.log). */
+/** Get the debug log path (~/.zeta/agent/omp-debug.log). */
 export function getDebugLogPath(agentDir?: string): string {
 	return dirs.agentSubdir(agentDir, `${APP_NAME}-debug.log`, "state");
 }
@@ -961,20 +1024,6 @@ export function getSSHConfigPath(scope: "user" | "project", cwd: string = getPro
 	return path.join(getProjectAgentDir(cwd), "ssh.json");
 }
 
-// =============================================================================
-// Project tracking
-// =============================================================================
-
-/** Get the project-level tracking directory (<project>/.zeta/tracking). */
-export function getProjectTrackingDir(cwd: string = getProjectDir()): string {
-	return path.join(getProjectAgentDir(cwd), "tracking");
-}
-
-/** Get the global tracking index path (~/.zeta/agent/tracking-index.json). */
-export function getTrackingIndexPath(agentDir?: string): string {
-	return path.join(agentDir ?? getAgentDir(), "tracking-index.json");
-}
-
 // =============================================================================
 // Install identity
 // =============================================================================
@@ -982,6 +1031,17 @@ export function getTrackingIndexPath(agentDir?: string): string {
 let cachedInstallId: string | null = null;
 
 const INSTALL_ID_FILE = "install-id";
+/**
+ * Application label for usage attribution (`OMP_APP_NAME`), defaulting to
+ * `omp`. Embedders that drive omp programmatically (robomp, CI bots, …) set
+ * the env var so broker-side per-client burn tracking can answer "what did
+ * app X use" instead of folding everything into one install-wide bucket.
+ */
+export function getAppName(): string {
+	const value = process.env.OMP_APP_NAME?.trim();
+	return value ? value : "omp";
+}
+
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
 /**
@@ -1052,3 +1112,13 @@ export function getInstallId(): string {
 export function __resetInstallIdCacheForTests(): void {
 	cachedInstallId = null;
 }
+
+/** Get the project-level tracking directory (<project>/.zeta/tracking). */
+export function getProjectTrackingDir(cwd: string = getProjectDir()): string {
+	return path.join(getProjectAgentDir(cwd), "tracking");
+}
+
+/** Get the global tracking index path (~/.zeta/agent/tracking-index.json). */
+export function getTrackingIndexPath(agentDir?: string): string {
+	return path.join(agentDir ?? getAgentDir(), "tracking-index.json");
+}

package/src/env.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { getAgentDir, getConfigRootDir, refreshDirsFromEnv } from "./dirs";
+import { getAgentDir, getConfigRootDir, getProjectDir, refreshDirsFromEnv } from "./dirs";
 
 export * from "./worker-host";
 
@@ -228,7 +228,7 @@ export function parseEnvFile(filePath: string): Record<string, string> {
 const homeEnv = parseEnvFile(path.join(os.homedir(), ".env"));
 const piEnv = parseEnvFile(path.join(getConfigRootDir(), ".env"));
 const agentEnv = parseEnvFile(path.join(getAgentDir(), ".env"));
-const projectEnv = parseEnvFile(path.join(process.cwd(), ".env"));
+const projectEnv = parseEnvFile(path.join(getProjectDir(), ".env"));
 
 for (const key of Object.keys(Bun.env)) {
 	const value = Bun.env[key];

package/src/index.ts

@@ -14,6 +14,7 @@ export * from "./json";
 export * from "./json-parse";
 export * as logger from "./logger";
 export * from "./loop-phase";
+export * from "./math-delimiters";
 export * from "./mermaid-ascii";
 export * from "./mime";
 export * from "./path";

package/src/json.ts

@@ -21,3 +21,26 @@ export function tryParseJson<T = unknown>(content: string): T | null {
 export function stringifyJson(value: unknown, space?: string | number): string | undefined {
 	return JSON.stringify(value, (_key, item) => (typeof item === "bigint" ? item.toString() : item), space);
 }
+
+function stableJsonClone(value: unknown): unknown {
+	if (Array.isArray(value)) return value.map(stableJsonClone);
+	if (value !== null && typeof value === "object") {
+		const sorted = Object.create(null) as Record<string, unknown>;
+		for (const key of Object.keys(value).sort()) {
+			sorted[key] = stableJsonClone(Reflect.get(value, key));
+		}
+		return sorted;
+	}
+	return value;
+}
+
+/**
+ * Deterministically serialize JSON-shaped data by sorting object keys at every
+ * depth while preserving array order. Throws for values JSON cannot represent
+ * as a top-level value instead of returning an easy-to-misuse undefined.
+ */
+export function stableStringifyJson(value: unknown): string {
+	const serialized = JSON.stringify(stableJsonClone(value));
+	if (serialized === undefined) throw new TypeError("Value is not JSON-serializable");
+	return serialized;
+}