@gajae-code/utils 0.17.1 → 0.17.4

package/dist/types/canonical-log-dir.d.ts

@@ -0,0 +1,20 @@
+interface ProjectEnvSnapshotLike {
+    values: Record<string, string>;
+    dynamic: Set<string>;
+}
+interface CanonicalLogDirInput {
+    home: string;
+    env: Record<string, string | undefined>;
+    projectEnv: ProjectEnvSnapshotLike;
+    xdgEligible: boolean;
+    pathExists?: (target: string) => boolean;
+}
+/**
+ * Resolve the canonical user log directory without mutating the environment.
+ *
+ * The caller supplies filesystem existence checks so this leaf stays free of
+ * filesystem and resolver side effects. Both the production directory resolver
+ * and the test preload use this exact path selection logic.
+ */
+export declare function resolveCanonicalLogsDir(input: CanonicalLogDirInput): string;
+export {};

package/dist/types/cli.d.ts

@@ -111,6 +111,14 @@ export interface CommandEntry {
     name: string;
     load: () => Promise<CommandCtor>;
     aliases?: string[];
+    /** Owns parsing, help, loading and failures for this family when supplied. */
+    dispatch?: (argv: string[], context: CommandEntryContext) => Promise<void>;
+}
+export interface CommandEntryContext {
+    bin: string;
+    version: string;
+    /** Canonical registered entry name, including when invoked through an alias. */
+    command: string;
 }
 export interface RunOptions {
     bin: string;

package/dist/types/crash-fingerprint.d.ts

@@ -59,6 +59,15 @@ export declare function normalizeCrashMessage(message: string, options?: CrashFi
 export declare function normalizeCrashFrames(stack: string, options?: CrashFingerprintOptions): string[];
 /** Compute the v1 fingerprint of an already-captured fatal diagnostic. */
 export declare function computeCrashFingerprint(input: CrashFingerprintInput, options?: CrashFingerprintOptions): CrashFingerprint;
+/**
+ * Compute the stable identity used for a handled tool error.
+ *
+ * Tool failures often carry command output or other per-occurrence detail in
+ * their message. That text is useful in the record body but is not the failure
+ * identity: handled errors group by error class and the first in-app frame
+ * where the failure originated, rather than the full wrapper stack.
+ */
+export declare function computeHandledErrorFingerprint(input: CrashFingerprintInput, options?: CrashFingerprintOptions): CrashFingerprint;
 /** The machine-readable identity line appended to every new crash record. */
 export declare function formatCrashRecordMarker(fingerprint: string, version: number, recordId: string): string;
 export interface CrashRecordMarker {

package/dist/types/dirs.d.ts

@@ -11,6 +11,8 @@
  * move data to the new locations. No filesystem existence checks are performed
  * — if the env var is set, gjc trusts that the migration has been done.
  */
+import { canonicalEnvKey } from "./env-file";
+export { canonicalEnvKey };
 /** App name (e.g. "gjc") */
 export declare const APP_NAME: string;
 /** Config directory name (e.g. ".gjc") */
@@ -50,14 +52,6 @@ export declare function relativePathWithinRoot(root: string, candidate: string):
 export declare function getProjectDir(): string;
 /** Set the project directory. */
 export declare function setProjectDir(dir: string): void;
-/**
- * Windows environment variable names are case-insensitive, so a project dotenv
- * line `userprofile=...` is what `process.env.USERPROFILE` resolves to. Every
- * provenance lookup here is spelled in upper case, so the snapshot must be
- * keyed the same way or the declaration is invisible to the guard while still
- * being live in the process. POSIX names are case-sensitive and must not fold.
- */
-export declare function canonicalEnvKey(name: string): string;
 export declare function getConfigAgentDirName(): string;
 /** Get the config root directory (~/.gjc). */
 export declare function getConfigRootDir(): string;
@@ -109,6 +103,29 @@ export declare function getReportsDir(): string;
 export declare function getLogsDir(): string;
 /** Get the path to a dated log file (~/.gjc/logs/gjc.YYYY-MM-DD.log). */
 export declare function getLogPath(date?: Date): string;
+/**
+ * The logs directory the process actually reads and writes.
+ *
+ * A trusted `GJC_LOG_DIR` redirects the sink — the test preload pins it to a
+ * per-process temp directory so `bun test` stops appending fixture
+ * `level:error` records to the operator's shared log (issue #5618) — and
+ * everything else falls back to {@link getLogsDir}.
+ *
+ * The override is provenance-checked through the same {@link trustedValue} rule
+ * as the config and agent directories: Bun loads `cwd/.env` into `process.env`
+ * before any module runs, so a repository could otherwise redirect where the
+ * operator's production logs are written. A dynamic (`$`/backtick) declaration
+ * is rejected there too, which fails closed onto the canonical path.
+ *
+ * This is deliberately *not* folded into {@link getLogsDir}: that function's
+ * config-root semantics are pinned by tests, and the preload sets `GJC_LOG_DIR`
+ * for every test process, so folding the override in would move it under every
+ * test. Writers and readers must both come through here instead — the split
+ * between the two is what let the transport and the log readers disagree.
+ */
+export declare function getEffectiveLogsDir(): string;
+/** Get the dated log file under {@link getEffectiveLogsDir}. */
+export declare function getEffectiveLogPath(date?: Date): string;
 /**
  * Get the plugins directory (~/.gjc/plugins or its XDG equivalent).
  *

package/dist/types/env-file.d.ts

@@ -32,3 +32,40 @@ export declare function parseShellEnvFile(filePath: string): Record<string, stri
 export declare function parseEnvFile(filePath: string): Record<string, string>;
 /** Parse dotenv content that has already been read from a trusted file. */
 export declare function parseEnvFileContent(content: string): Record<string, string>;
+/**
+ * What the caller's checkout declares through its dotenv files.
+ *
+ * `values` is the merged declaration set, later layers winning. `dynamic` holds
+ * the keys whose surviving declaration is one Bun expands at load time, which
+ * every provenance guard refuses outright because a value comparison cannot see
+ * what such a declaration became.
+ */
+export interface ProjectEnvSnapshot {
+    values: Record<string, string>;
+    dynamic: Set<string>;
+}
+/**
+ * Windows environment variable names are case-insensitive, so a project dotenv
+ * line `userprofile=...` is what `process.env.USERPROFILE` resolves to. Every
+ * provenance lookup is spelled in upper case, so the snapshot must be keyed the
+ * same way or the declaration is invisible to the guard while still being live
+ * in the process. POSIX names are case-sensitive and must not fold.
+ */
+export declare function canonicalEnvKey(name: string): string;
+/**
+ * The layered dotenv declarations Bun overlays into `process.env` for a cwd.
+ *
+ * Lives in this leaf module so every consumer shares ONE notion of provenance.
+ * `dirs.ts` resolves the config, agent and log directories from it, and
+ * `scripts/test-preload.ts` decides test isolation from it — a second, narrower
+ * reader (only `cwd/.env`, its own regex, its own dynamic test) is how a
+ * `GJC_LOG_DIR` declared in `.env.local` / `.env.$NODE_ENV` came to be honored
+ * by the preload and then rejected in production, silently routing test log
+ * records to the operator's canonical sink. This module imports only `node:fs`,
+ * `node:path` and the import-free `./spawn-env`, so importing it has no side
+ * effects and cannot freeze resolver state the way importing `dirs.ts` would.
+ *
+ * `.env.local` is deliberately skipped when `NODE_ENV === "test"`, matching the
+ * convention that a local override file is not part of a test run.
+ */
+export declare function projectEnvSnapshot(cwd?: string): ProjectEnvSnapshot;

package/dist/types/error-classification.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Cross-package classification for errors that describe an expected outcome
+ * rather than an unexpected failure.
+ *
+ * The symbol is registered globally so the marker survives package duplication
+ * and worker/VM boundaries without relying on a particular Error constructor.
+ */
+export declare const DESIGNED_ERROR: unique symbol;
+/** Mark an Error as a designed outcome before it crosses package boundaries. */
+export declare function markDesignedError<T extends Error>(error: T): T;
+/** Return true when a throwable carries the trusted designed-outcome marker. */
+export declare function isDesignedError(error: unknown): boolean;

package/dist/types/index.d.ts

@@ -7,6 +7,7 @@ export * from "./crash-journal";
 export * from "./crash-redaction";
 export * from "./dirs";
 export * from "./env";
+export * from "./error-classification";
 export * from "./fetch-retry";
 export * from "./format";
 export * from "./frontmatter";

package/dist/types/postmortem.d.ts

@@ -5,6 +5,7 @@
  * in response to process exit, signals, or fatal exceptions. It is intended to
  * allow reliably releasing resources or shutting down subprocesses, files, sockets, etc.
  */
+import { type CrashFingerprint } from "./crash-fingerprint";
 import type { CrashProvenance } from "./crash-journal";
 import { redactCrashSecrets } from "./crash-redaction";
 export declare enum Reason {
@@ -63,6 +64,7 @@ interface CrashRecordOptions {
     path?: string;
     now?: Date;
     provenance?: CrashProvenance;
+    fingerprint?: CrashFingerprint;
 }
 /**
  * Register a process cleanup callback, to be run on shutdown, signal, or fatal error.

package/dist/types/sanitize-text.d.ts

@@ -18,6 +18,7 @@ export declare function sanitizeText(text: string): string;
  * {@link sanitizeText} deliberately preserves `\n`, and width-based truncation
  * treats it as zero-width, so a value carrying line breaks can still inject
  * extra rows and evade a single-line width budget. Flatten every CR/LF run to a
- * single space before the usual control/ANSI strip.
+ * single space before the usual control/ANSI strip, then remove directional
+ * format controls that can visually reorder an otherwise safe row.
  */
 export declare function sanitizeDisplayLine(text: string): string;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/utils",
-	"version": "0.17.1",
+	"version": "0.17.4",
 	"description": "Shared utilities for pi packages",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo",
@@ -31,7 +31,7 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@gajae-code/natives": "0.17.1",
+		"@gajae-code/natives": "0.17.4",
 		"beautiful-mermaid": "^1.1.3",
 		"handlebars": "^4.7.9",
 		"winston": "^3.19.0",

package/src/canonical-log-dir.ts

@@ -0,0 +1,59 @@
+import * as path from "node:path";
+
+interface ProjectEnvSnapshotLike {
+	values: Record<string, string>;
+	dynamic: Set<string>;
+}
+
+interface CanonicalLogDirInput {
+	home: string;
+	env: Record<string, string | undefined>;
+	projectEnv: ProjectEnvSnapshotLike;
+	xdgEligible: boolean;
+	pathExists?: (target: string) => boolean;
+}
+
+const APP_NAME = "gjc";
+const DEFAULT_CONFIG_DIR_NAME = ".gjc";
+
+function canonicalEnvKey(name: string): string {
+	return process.platform === "win32" ? name.toUpperCase() : name;
+}
+
+function sanitizeConfigDirName(value: string | undefined): string | undefined {
+	const trimmed = value?.trim();
+	if (!trimmed || path.normalize(trimmed).split(/[\\/]/).includes("..")) return undefined;
+	return trimmed;
+}
+
+/** Resolve a caller environment value only when its dotenv provenance is trusted. */
+function trustedValue(name: string, input: CanonicalLogDirInput): string | undefined {
+	const value = input.env[name];
+	if (!value) return undefined;
+	const key = canonicalEnvKey(name);
+	if (input.projectEnv.dynamic.has(key) || input.projectEnv.values[key] === value) return undefined;
+	return value;
+}
+
+/**
+ * Resolve the canonical user log directory without mutating the environment.
+ *
+ * The caller supplies filesystem existence checks so this leaf stays free of
+ * filesystem and resolver side effects. Both the production directory resolver
+ * and the test preload use this exact path selection logic.
+ */
+export function resolveCanonicalLogsDir(input: CanonicalLogDirInput): string {
+	const configDirName =
+		sanitizeConfigDirName(trustedValue("GJC_CONFIG_DIR", input)) ??
+		sanitizeConfigDirName(trustedValue("PI_CONFIG_DIR", input)) ??
+		DEFAULT_CONFIG_DIR_NAME;
+	const xdgStateHome =
+		input.xdgEligible && (process.platform === "linux" || process.platform === "darwin")
+			? trustedValue("XDG_STATE_HOME", input)?.trim()
+			: undefined;
+	if (xdgStateHome) {
+		const xdgRoot = path.join(xdgStateHome, APP_NAME);
+		if (input.pathExists?.(xdgRoot) === true) return path.join(xdgRoot, "logs");
+	}
+	return path.join(input.home, configDirName, "logs");
+}

package/src/cli.ts

@@ -394,6 +394,15 @@ export interface CommandEntry {
 	name: string;
 	load: () => Promise<CommandCtor>;
 	aliases?: string[];
+	/** Owns parsing, help, loading and failures for this family when supplied. */
+	dispatch?: (argv: string[], context: CommandEntryContext) => Promise<void>;
+}
+
+export interface CommandEntryContext {
+	bin: string;
+	version: string;
+	/** Canonical registered entry name, including when invoked through an alias. */
+	command: string;
 }
 
 export interface RunOptions {
@@ -439,6 +448,12 @@ export async function run(opts: RunOptions): Promise<void> {
 		return;
 	}
 
+	const dispatchedEntry = findEntry(opts.commands, commandId);
+	if (dispatchedEntry?.dispatch) {
+		await dispatchedEntry.dispatch(commandArgv, { bin, version, command: dispatchedEntry.name });
+		return;
+	}
+
 	// Per-command help. Commands with nested subcommands can opt into receiving
 	// help flags themselves so `cmd subcommand --help` can render subcommand help.
 	const delimiterIndex = commandArgv.indexOf("--");

package/src/crash-fingerprint.ts

@@ -224,17 +224,18 @@ function canonicalSerialization(fields: readonly string[]): Buffer {
 	return Buffer.concat(parts);
 }
 
-/** Compute the v1 fingerprint of an already-captured fatal diagnostic. */
-export function computeCrashFingerprint(
+function computeFingerprint(
 	input: CrashFingerprintInput,
-	options: CrashFingerprintOptions = {},
+	options: CrashFingerprintOptions,
+	includeMessage: boolean,
 ): CrashFingerprint {
 	const errorName = truncateUtf8(normalizeCrashMessage(input.name, options) || "Error", 128);
 	const messageClass = normalizeCrashMessage(input.message, options);
 	const frames = normalizeCrashFrames(input.stack, options);
-	const digest = createHash("sha256")
-		.update(canonicalSerialization(["gjc-crash-fp.v1", errorName, messageClass, ...frames]))
-		.digest();
+	const identity = includeMessage
+		? ["gjc-crash-fp.v1", errorName, messageClass, ...frames]
+		: ["gjc-crash-fp.v1", "handled", errorName, frames[0] ?? NO_APP_FRAME];
+	const digest = createHash("sha256").update(canonicalSerialization(identity)).digest();
 	return {
 		fingerprint: digest.subarray(0, CRASH_FINGERPRINT_HEX_LENGTH / 2).toString("hex"),
 		version: CRASH_FINGERPRINT_VERSION,
@@ -244,6 +245,29 @@ export function computeCrashFingerprint(
 	};
 }
 
+/** Compute the v1 fingerprint of an already-captured fatal diagnostic. */
+export function computeCrashFingerprint(
+	input: CrashFingerprintInput,
+	options: CrashFingerprintOptions = {},
+): CrashFingerprint {
+	return computeFingerprint(input, options, true);
+}
+
+/**
+ * Compute the stable identity used for a handled tool error.
+ *
+ * Tool failures often carry command output or other per-occurrence detail in
+ * their message. That text is useful in the record body but is not the failure
+ * identity: handled errors group by error class and the first in-app frame
+ * where the failure originated, rather than the full wrapper stack.
+ */
+export function computeHandledErrorFingerprint(
+	input: CrashFingerprintInput,
+	options: CrashFingerprintOptions = {},
+): CrashFingerprint {
+	return computeFingerprint(input, options, false);
+}
+
 /** The machine-readable identity line appended to every new crash record. */
 export function formatCrashRecordMarker(fingerprint: string, version: number, recordId: string): string {
 	return `${CRASH_RECORD_MARKER} fp:${fingerprint} fpv:${version} id:${recordId}`;

package/src/dirs.ts

@@ -16,7 +16,16 @@ 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 { parseEnvFile } from "./env-file";
+import { resolveCanonicalLogsDir } from "./canonical-log-dir";
+import { canonicalEnvKey, type ProjectEnvSnapshot, projectEnvSnapshot } from "./env-file";
+
+// The provenance snapshot and its key fold live in the leaf `env-file` module so
+// `scripts/test-preload.ts` can share this exact logic without importing this
+// module (whose load-time resolver construction would freeze state before the
+// preload sets its isolation variables). Re-exported here because `env.ts` and
+// `test/env-provenance.windows.test.ts` import `canonicalEnvKey` from this
+// module's public surface.
+export { canonicalEnvKey };
 
 /** App name (e.g. "gjc") */
 export const APP_NAME: string = "gjc";
@@ -170,39 +179,6 @@ function sanitizeConfigDirName(value: string | undefined): string | undefined {
 	return trimmed;
 }
 
-/**
- * Windows environment variable names are case-insensitive, so a project dotenv
- * line `userprofile=...` is what `process.env.USERPROFILE` resolves to. Every
- * provenance lookup here is spelled in upper case, so the snapshot must be
- * keyed the same way or the declaration is invisible to the guard while still
- * being live in the process. POSIX names are case-sensitive and must not fold.
- */
-export function canonicalEnvKey(name: string): string {
-	return process.platform === "win32" ? name.toUpperCase() : name;
-}
-
-function projectEnvSnapshot(cwd = process.cwd()): { values: Record<string, string>; dynamic: Set<string> } {
-	const nodeEnv = process.env.NODE_ENV;
-	const validNodeEnv = nodeEnv && /^[A-Za-z0-9_-]+$/.test(nodeEnv) ? nodeEnv : undefined;
-	const files = [
-		".env",
-		...(validNodeEnv ? [`.env.${validNodeEnv}`] : []),
-		...(validNodeEnv !== "test" ? [".env.local"] : []),
-		...(validNodeEnv ? [`.env.${validNodeEnv}.local`] : []),
-	];
-	const values: Record<string, string> = {};
-	const dynamic = new Set<string>();
-	for (const file of files) {
-		for (const [rawKey, value] of Object.entries(parseEnvFile(path.join(cwd, file)))) {
-			const key = canonicalEnvKey(rawKey);
-			values[key] = value;
-			if (/[$`]/.test(value)) dynamic.add(key);
-			else dynamic.delete(key);
-		}
-	}
-	return { values, dynamic };
-}
-
 /**
  * Resolve an environment value only when it is not supplied by the caller's
  * project dotenv (or when the inherited value is observably distinct).
@@ -220,10 +196,7 @@ function projectEnvSnapshot(cwd = process.cwd()): { values: Record<string, strin
  * happens to carry the identical value loses the override, which is the same
  * trade-off `resolveLiveCredentialEnvValue` already makes.
  */
-function trustedValue(
-	name: string,
-	project: { values: Record<string, string>; dynamic: Set<string> },
-): string | undefined {
+function trustedValue(name: string, project: ProjectEnvSnapshot): string | undefined {
 	const value = process.env[name];
 	if (!value) return undefined;
 	const key = canonicalEnvKey(name);
@@ -232,7 +205,7 @@ function trustedValue(
 	return value;
 }
 
-function resolveConfigDirName(project: { values: Record<string, string>; dynamic: Set<string> }): string {
+function resolveConfigDirName(project: ProjectEnvSnapshot): string {
 	return (
 		sanitizeConfigDirName(trustedValue("GJC_CONFIG_DIR", project)) ??
 		sanitizeConfigDirName(trustedValue("PI_CONFIG_DIR", project)) ??
@@ -369,7 +342,7 @@ function accountHomeFromSystem(): AccountHome | undefined {
  * per call is what makes the contract call-time; the provenance comparison above
  * is what keeps an untrusted mutable home from being honored.
  */
-function resolveTrustedHome(project: { values: Record<string, string>; dynamic: Set<string> }): string {
+function resolveTrustedHome(project: ProjectEnvSnapshot): string {
 	const authoritativeHomeKey = process.platform === "win32" ? "USERPROFILE" : "HOME";
 	const declaredHomeKey = canonicalEnvKey(authoritativeHomeKey);
 	const declaredHome = project.values[declaredHomeKey];
@@ -425,7 +398,7 @@ type XdgCategory = "data" | "state" | "cache";
 class DirResolver {
 	configRoot: string;
 	agentDir: string;
-	readonly #projectEnv: { values: Record<string, string>; dynamic: Set<string> };
+	readonly #projectEnv: ProjectEnvSnapshot;
 	#configDirName: string;
 	readonly #agentDirOverride: boolean;
 	#trustedHome: string;
@@ -491,10 +464,7 @@ class DirResolver {
 	 * change storage lane when a home refresh made its path coincide with the
 	 * new default.
 	 */
-	private refreshCategoryDirs(
-		snapshot: { values: Record<string, string>; dynamic: Set<string> },
-		isDefault: boolean,
-	): void {
+	private refreshCategoryDirs(snapshot: ProjectEnvSnapshot, isDefault: boolean): void {
 		let xdgData: string | undefined;
 		let xdgState: string | undefined;
 		let xdgCache: string | undefined;
@@ -619,7 +589,7 @@ class DirResolver {
 		this.refreshConfigDirOverride();
 		if (!this.#homeAvailable) throw new Error("User state is unavailable: no trustworthy home directory");
 	}
-	get trustSnapshot(): { values: Record<string, string>; dynamic: Set<string> } {
+	get trustSnapshot(): ProjectEnvSnapshot {
 		return this.#projectEnv;
 	}
 }
@@ -732,12 +702,58 @@ export function getReportsDir(): string {
 
 /** Get the logs directory (~/.gjc/logs). */
 export function getLogsDir(): string {
-	return dirs.rootSubdir("logs", "state");
+	const home = getTrustedHomeDir();
+	return resolveCanonicalLogsDir({
+		home,
+		env: {
+			GJC_CONFIG_DIR: process.env.GJC_CONFIG_DIR,
+			PI_CONFIG_DIR: process.env.PI_CONFIG_DIR,
+			XDG_STATE_HOME: process.env.XDG_STATE_HOME,
+		},
+		projectEnv: dirs.trustSnapshot,
+		xdgEligible: dirs.profileAuthority === "default",
+		pathExists: fs.existsSync,
+	});
+}
+
+/** Dated log file name, shared by the canonical and effective log paths so they cannot drift. */
+function datedLogFileName(date: Date): string {
+	return `${APP_NAME}.${date.toISOString().slice(0, 10)}.log`;
 }
 
 /** Get the path to a dated log file (~/.gjc/logs/gjc.YYYY-MM-DD.log). */
 export function getLogPath(date = new Date()): string {
-	return path.join(getLogsDir(), `${APP_NAME}.${date.toISOString().slice(0, 10)}.log`);
+	return path.join(getLogsDir(), datedLogFileName(date));
+}
+
+/**
+ * The logs directory the process actually reads and writes.
+ *
+ * A trusted `GJC_LOG_DIR` redirects the sink — the test preload pins it to a
+ * per-process temp directory so `bun test` stops appending fixture
+ * `level:error` records to the operator's shared log (issue #5618) — and
+ * everything else falls back to {@link getLogsDir}.
+ *
+ * The override is provenance-checked through the same {@link trustedValue} rule
+ * as the config and agent directories: Bun loads `cwd/.env` into `process.env`
+ * before any module runs, so a repository could otherwise redirect where the
+ * operator's production logs are written. A dynamic (`$`/backtick) declaration
+ * is rejected there too, which fails closed onto the canonical path.
+ *
+ * This is deliberately *not* folded into {@link getLogsDir}: that function's
+ * config-root semantics are pinned by tests, and the preload sets `GJC_LOG_DIR`
+ * for every test process, so folding the override in would move it under every
+ * test. Writers and readers must both come through here instead — the split
+ * between the two is what let the transport and the log readers disagree.
+ */
+export function getEffectiveLogsDir(): string {
+	const override = trustedValue("GJC_LOG_DIR", dirs.trustSnapshot)?.trim();
+	return override || getLogsDir();
+}
+
+/** Get the dated log file under {@link getEffectiveLogsDir}. */
+export function getEffectiveLogPath(date = new Date()): string {
+	return path.join(getEffectiveLogsDir(), datedLogFileName(date));
 }
 
 /**

package/src/env-file.ts

@@ -6,6 +6,7 @@
  * below both of them.
  */
 import * as fs from "node:fs";
+import * as path from "node:path";
 import { isSafeEnvValue } from "./spawn-env";
 
 const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -155,3 +156,65 @@ export function parseEnvFileContent(content: string): Record<string, string> {
 
 	return result;
 }
+
+/**
+ * What the caller's checkout declares through its dotenv files.
+ *
+ * `values` is the merged declaration set, later layers winning. `dynamic` holds
+ * the keys whose surviving declaration is one Bun expands at load time, which
+ * every provenance guard refuses outright because a value comparison cannot see
+ * what such a declaration became.
+ */
+export interface ProjectEnvSnapshot {
+	values: Record<string, string>;
+	dynamic: Set<string>;
+}
+
+/**
+ * Windows environment variable names are case-insensitive, so a project dotenv
+ * line `userprofile=...` is what `process.env.USERPROFILE` resolves to. Every
+ * provenance lookup is spelled in upper case, so the snapshot must be keyed the
+ * same way or the declaration is invisible to the guard while still being live
+ * in the process. POSIX names are case-sensitive and must not fold.
+ */
+export function canonicalEnvKey(name: string): string {
+	return process.platform === "win32" ? name.toUpperCase() : name;
+}
+
+/**
+ * The layered dotenv declarations Bun overlays into `process.env` for a cwd.
+ *
+ * Lives in this leaf module so every consumer shares ONE notion of provenance.
+ * `dirs.ts` resolves the config, agent and log directories from it, and
+ * `scripts/test-preload.ts` decides test isolation from it — a second, narrower
+ * reader (only `cwd/.env`, its own regex, its own dynamic test) is how a
+ * `GJC_LOG_DIR` declared in `.env.local` / `.env.$NODE_ENV` came to be honored
+ * by the preload and then rejected in production, silently routing test log
+ * records to the operator's canonical sink. This module imports only `node:fs`,
+ * `node:path` and the import-free `./spawn-env`, so importing it has no side
+ * effects and cannot freeze resolver state the way importing `dirs.ts` would.
+ *
+ * `.env.local` is deliberately skipped when `NODE_ENV === "test"`, matching the
+ * convention that a local override file is not part of a test run.
+ */
+export function projectEnvSnapshot(cwd = process.cwd()): ProjectEnvSnapshot {
+	const nodeEnv = process.env.NODE_ENV;
+	const validNodeEnv = nodeEnv && /^[A-Za-z0-9_-]+$/.test(nodeEnv) ? nodeEnv : undefined;
+	const files = [
+		".env",
+		...(validNodeEnv ? [`.env.${validNodeEnv}`] : []),
+		...(validNodeEnv !== "test" ? [".env.local"] : []),
+		...(validNodeEnv ? [`.env.${validNodeEnv}.local`] : []),
+	];
+	const values: Record<string, string> = {};
+	const dynamic = new Set<string>();
+	for (const file of files) {
+		for (const [rawKey, value] of Object.entries(parseEnvFile(path.join(cwd, file)))) {
+			const key = canonicalEnvKey(rawKey);
+			values[key] = value;
+			if (/[$`]/.test(value)) dynamic.add(key);
+			else dynamic.delete(key);
+		}
+	}
+	return { values, dynamic };
+}

package/src/error-classification.ts

@@ -0,0 +1,31 @@
+/**
+ * Cross-package classification for errors that describe an expected outcome
+ * rather than an unexpected failure.
+ *
+ * The symbol is registered globally so the marker survives package duplication
+ * and worker/VM boundaries without relying on a particular Error constructor.
+ */
+export const DESIGNED_ERROR = Symbol.for("gajae-code.designed-error");
+
+type MarkedError = object & { readonly [DESIGNED_ERROR]?: unknown };
+
+/** Mark an Error as a designed outcome before it crosses package boundaries. */
+export function markDesignedError<T extends Error>(error: T): T {
+	Object.defineProperty(error, DESIGNED_ERROR, {
+		configurable: false,
+		enumerable: false,
+		value: true,
+		writable: false,
+	});
+	return error;
+}
+
+/** Return true when a throwable carries the trusted designed-outcome marker. */
+export function isDesignedError(error: unknown): boolean {
+	if ((typeof error !== "object" && typeof error !== "function") || error === null) return false;
+	try {
+		return (error as MarkedError)[DESIGNED_ERROR] === true;
+	} catch {
+		return false;
+	}
+}

package/src/index.ts

@@ -7,6 +7,7 @@ export * from "./crash-journal";
 export * from "./crash-redaction";
 export * from "./dirs";
 export * from "./env";
+export * from "./error-classification";
 export * from "./fetch-retry";
 export * from "./format";
 export * from "./frontmatter";

package/src/logger.ts

@@ -12,7 +12,7 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import * as fs from "node:fs";
 import type * as winston from "winston";
-import { getLogsDir } from "./dirs";
+import { getEffectiveLogsDir } from "./dirs";
 
 /** Ensure a logs directory exists; return the resolved path. */
 function ensureDir(dir: string): string {
@@ -73,10 +73,22 @@ function makeLogFormat(winston: WinstonModule): winston.Logform.Format {
 	);
 }
 
-/** Build a rotating file transport, materializing the target directory lazily. */
+/**
+ * Build a rotating file transport, materializing the target directory lazily.
+ *
+ * Destination precedence:
+ *   1. `dir` — an explicit path from {@link setTransports}(`{ file: "<path>" }`).
+ *   2. {@link getEffectiveLogsDir} — the provenance-checked `GJC_LOG_DIR`
+ *      override, else the real config root (`~/.gjc/logs`).
+ *
+ * The resolution is centralized in `dirs.ts` rather than read from the
+ * environment here: the log *readers* (report bundles, the debug log view, the
+ * HTTP dump directory) call the same helper, and a second env read in this file
+ * is what let the transport write somewhere the readers never looked.
+ */
 function makeFileTransport(DailyRotateFile: DailyRotateFileCtor, dir?: string): Transport {
 	return new DailyRotateFile({
-		dirname: ensureDir(dir ?? getLogsDir()),
+		dirname: ensureDir(dir ?? getEffectiveLogsDir()),
 		filename: "gjc.%DATE%.log",
 		datePattern: "YYYY-MM-DD",
 		maxSize: "10m",

package/src/postmortem.ts

@@ -12,11 +12,17 @@ import inspector from "node:inspector";
 import * as path from "node:path";
 import { isMainThread } from "node:worker_threads";
 import { BROKEN_PIPE_EXIT_CODE, createProcessStdoutEpipeClassifier } from "./broken-pipe";
-import { type CrashFingerprint, computeCrashFingerprint, formatCrashRecordMarker } from "./crash-fingerprint";
+import {
+	type CrashFingerprint,
+	computeCrashFingerprint,
+	computeHandledErrorFingerprint,
+	formatCrashRecordMarker,
+} from "./crash-fingerprint";
 import type { CrashProvenance } from "./crash-journal";
 import { appendCrashEvent, appendFatalCrashEvent, detectCrashProvenance } from "./crash-journal";
 import { redactCrashSecrets } from "./crash-redaction";
 import { getCrashEventsPath, getCrashLogPath, getHandledErrorEventsPath, getHandledErrorLogPath } from "./dirs";
+import { isDesignedError } from "./error-classification";
 import * as logger from "./logger";
 import { safeStderrWrite } from "./safe-stderr";
 
@@ -512,9 +518,15 @@ export function recordHandledError(
 	options: HandledErrorRecordOptions = {},
 ): string | undefined {
 	try {
-		if (!(error instanceof Error) || typeof error.stack !== "string" || error.stack.length === 0) return undefined;
+		if (
+			!(error instanceof Error) ||
+			isDesignedError(error) ||
+			typeof error.stack !== "string" ||
+			error.stack.length === 0
+		)
+			return undefined;
 		const fatal = describeFatal(error);
-		const fingerprint = computeCrashFingerprint(fatal).fingerprint;
+		const fingerprint = computeHandledErrorFingerprint(fatal).fingerprint;
 		if (handledErrorFingerprints.has(fingerprint)) {
 			// Still hot: dedupe, but refresh recency so an actively failing class
 			// is not the one evicted under pressure.
@@ -530,6 +542,7 @@ export function recordHandledError(
 		const written = writeCrashRecord(label, fatal, {
 			path: options.path ?? getHandledErrorLogPath(),
 			now: options.now,
+			fingerprint: computeHandledErrorFingerprint(fatal),
 		});
 		if (!written) {
 			handledErrorFingerprints.delete(fingerprint);
@@ -562,6 +575,7 @@ interface CrashRecordOptions {
 	path?: string;
 	now?: Date;
 	provenance?: CrashProvenance;
+	fingerprint?: CrashFingerprint;
 }
 
 interface WrittenCrashRecord {
@@ -595,7 +609,7 @@ function writeCrashRecord(
 		const payload = fatal.payload ? `${redactCrashSecrets(fatal.payload)}\n` : "";
 		// Identity is computed from the already-captured diagnostic text only; the
 		// throwable is never read again here.
-		const fingerprint = computeCrashFingerprint(fatal);
+		const fingerprint = options.fingerprint ?? computeCrashFingerprint(fatal);
 		const recordId = randomBytes(8).toString("hex");
 		const markerLine = `${formatCrashRecordMarker(fingerprint.fingerprint, fingerprint.version, recordId)}\n`;
 		// The marker is the record's identity, so it is budgeted first and appended

package/src/sanitize-text.ts

@@ -17,6 +17,7 @@ const ESC_CHAR = "\x1b";
 // Well-formed strings only need control/ANSI detection: C0 (excl. \t \n),
 // CR, DEL, and C1. ESC (0x1B) is in \x0B-\x1F.
 const CONTROL_RE = /[\x00-\x08\x0B-\x1F\x7F-\x9F]/g;
+const DISPLAY_FORMAT_RE = /[\u061C\u200E\u200F\u202A-\u202E\u2066-\u2069]/gu;
 
 const REPLACEMENT_CHAR = "\ufffd";
 
@@ -34,10 +35,11 @@ export function sanitizeText(text: string): string {
  * {@link sanitizeText} deliberately preserves `\n`, and width-based truncation
  * treats it as zero-width, so a value carrying line breaks can still inject
  * extra rows and evade a single-line width budget. Flatten every CR/LF run to a
- * single space before the usual control/ANSI strip.
+ * single space before the usual control/ANSI strip, then remove directional
+ * format controls that can visually reorder an otherwise safe row.
  */
 export function sanitizeDisplayLine(text: string): string {
-	return sanitizeText(text.replace(/[\r\n]+/gu, " "));
+	return sanitizeText(text.replace(/[\r\n]+/gu, " ")).replace(DISPLAY_FORMAT_RE, "");
 }
 
 function sanitizeWellFormedText(text: string): string {