@gajae-code/utils 0.14.2 → 0.15.0

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

@@ -4,7 +4,7 @@ export declare const CRASH_EVENT_MAX_BYTES = 512;
 export declare const CRASH_EVENT_KIND = "gjc-crash-event.v1";
 /** Preview cap for the message class carried by an event. */
 export declare const CRASH_EVENT_MESSAGE_MAX_BYTES = 256;
-export type CrashEvent = CrashOccurrenceEvent | CrashReportedEvent | CrashRelayedEvent | CrashAcknowledgedEvent | CrashNudgedEvent;
+export type CrashEvent = CrashOccurrenceEvent | CrashRefusedEvent | CrashReportedEvent | CrashRelayedEvent | CrashAcknowledgedEvent | CrashNudgedEvent;
 export interface CrashOccurrenceEvent {
     readonly kind: "occurrence";
     readonly fingerprint: string;
@@ -14,6 +14,14 @@ export interface CrashOccurrenceEvent {
     readonly errorName: string;
     readonly messageClass: string;
 }
+export interface CrashRefusedEvent {
+    readonly kind: "refused";
+    readonly fingerprint: string;
+    readonly fpv: number;
+    readonly recordId: string;
+    readonly contractVersion: string;
+    readonly at: number;
+}
 export interface CrashReportedEvent {
     readonly kind: "reported";
     readonly fingerprint: string;

package/dist/types/dirs.d.ts

@@ -50,15 +50,39 @@ export declare function relativePathWithinRoot(root: string, candidate: string):
 export declare function getProjectDir(): string;
 /** Set the project directory. */
 export declare function setProjectDir(dir: string): void;
-export declare function getConfigDirName(): string;
-/** Get the config agent directory name relative to home (e.g. ".gjc/agent" or PI_CONFIG_DIR + "/agent"). */
+/**
+ * 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;
-/** Set the coding agent directory. Creates a fresh resolver, invalidating all cached paths. */
+/**
+ * The authoritative home for user-scope state.
+ *
+ * Provenance-checked and resolved at call time: a home established or changed
+ * after this module loaded is honored, while a home the project dotenv could
+ * have planted is rejected in favor of the OS account database. See
+ * {@link resolveTrustedHome}.
+ */
+export declare function getTrustedHomeDir(): string;
+/** Trusted config root, resolved at call time; preserves the configured nested config-dir name. */
+export declare function getTrustedConfigRootDir(): string;
+/**
+ * Set the coding agent directory. Creates a fresh resolver, invalidating all
+ * cached paths.
+ *
+ * This also exports `GJC_CODING_AGENT_DIR`, so child processes inherit the same
+ * selection and resolve the same storage lane.
+ */
 export declare function setAgentDir(dir: string): void;
 /** Get the agent config directory (~/.gjc/agent). */
 export declare function getAgentDir(): string;
+export declare function getConfigDirName(): string;
 /**
  * Join a file under the provenance-checked agent directory, never the XDG
  * state category. Automatic crash relay must not follow `XDG_STATE_HOME`:
@@ -80,11 +104,12 @@ export declare function getLogPath(date?: Date): string;
  * Get the plugins directory (~/.gjc/plugins or its XDG equivalent).
  *
  * No-arg form (production callers) goes through the XDG-aware DirResolver so
- * reads and writes always agree. The optional `home` parameter is for test
- * isolation: when it differs from `os.homedir()` it short-circuits the resolver
- * and returns `<home>/<configDir>/plugins` so tests with a temp HOME get a
- * deterministic path. Passing `os.homedir()` explicitly is identical to the
- * no-arg form — XDG semantics are preserved.
+ * reads and writes always agree. The optional `home` parameter names an explicit
+ * home: when it differs from the authoritative home resolved right now it
+ * short-circuits the resolver and returns `<home>/<configDir>/plugins`, giving
+ * callers that carry their own home (and tests with a temp HOME) a deterministic
+ * path. Passing the authoritative home explicitly is identical to the no-arg
+ * form — XDG semantics are preserved.
  */
 export declare function getPluginsDir(home?: string): string;
 /** Where npm installs packages (~/.gjc/plugins/node_modules). */
@@ -133,14 +158,6 @@ export declare function getToolChoiceCapabilityCachePath(): string;
 export declare function getNativesDir(): string;
 /** Get the stats database path (~/.gjc/stats.db). */
 export declare function getStatsDbPath(): string;
-/** Get the autoresearch state directory (~/.gjc/autoresearch). */
-export declare function getAutoresearchDir(): string;
-/** Get the per-project autoresearch state directory (~/.gjc/autoresearch/<encoded-project>). */
-export declare function getAutoresearchProjectDir(encodedProject: string): string;
-/** Get the per-project autoresearch SQLite database path (~/.gjc/autoresearch/<encoded-project>.db). */
-export declare function getAutoresearchDbPath(encodedProject: string): string;
-/** Get the per-run artifact directory (~/.gjc/autoresearch/<encoded-project>/runs/<runId>). */
-export declare function getAutoresearchRunDir(encodedProject: string, runId: number): string;
 /** Get the path to agent.db (SQLite database for settings and auth storage). */
 export declare function getAgentDbPath(agentDir?: string): string;
 /** Get the path to history.db (SQLite database for session history). */
@@ -189,7 +206,14 @@ export declare function getProjectModulesDir(cwd?: string): string;
 export declare function getProjectPromptsDir(cwd?: string): string;
 /** Get the project-level plugin overrides path (.gjc/plugin-overrides.json). */
 export declare function getProjectPluginOverridesPath(cwd?: string): string;
-/** Get the primary MCP config file path (first candidate). */
-export declare function getMCPConfigPath(scope: "user" | "project", cwd?: string): string;
+/**
+ * Get the primary MCP config file path (first candidate).
+ *
+ * User scope lives in the agent directory, so a profile override
+ * (`--agent-dir`, `GJC_CODING_AGENT_DIR`, `setAgentDir()`) moves it. Pass
+ * `agentDir` to resolve the scope of a session whose agent directory differs
+ * from the process-wide one.
+ */
+export declare function getMCPConfigPath(scope: "user" | "project", cwd?: string, agentDir?: string): string;
 /** Get the SSH config file path. */
 export declare function getSSHConfigPath(scope: "user" | "project", cwd?: string): string;

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

@@ -22,7 +22,7 @@ export declare function parseShellEnvFile(filePath: string): Record<string, stri
  * `filterCredentialInheritedEnv`) decide provenance by comparing
  * `process.env` against this parse, so the accepted syntax must be a superset
  * of what Bun's own dotenv loader honors in `cwd/.env`: `export KEY=value`,
- * whitespace around `=`, and `#` comments after unquoted values (quotes keep
+ * whitespace around `=` or `:`, and `#` comments after unquoted values (quotes keep
  * their `#`). Values that Bun would expand (`$VAR`, `${VAR}`, backticks,
  * command substitution) are kept as their literal text: the trust rule only
  * needs the parser to see the key at all, and an operator environment value

package/dist/types/header-value.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Sanitize a value destined for an HTTP header.
+ *
+ * OS-derived components (kernel release, hostname, os.version) can contain
+ * non-ASCII characters — e.g. Android kernel releases such as
+ * `4.4.302-Minimal™-EAS-QTI_Haptic-R26` — which `Headers`/`fetch` reject
+ * before the request is ever sent. Strip everything outside printable
+ * ASCII so header construction can never throw on runtime-derived values.
+ */
+export declare function sanitizeHeaderComponent(value: string): string;

package/dist/types/index.d.ts

@@ -12,6 +12,7 @@ export * from "./format";
 export * from "./frontmatter";
 export * from "./fs-error";
 export * from "./glob";
+export * from "./header-value";
 export * from "./hook-fetch";
 export * from "./json";
 export * as logger from "./logger";

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

@@ -12,3 +12,12 @@
  * string after the control probe.
  */
 export declare function sanitizeText(text: string): string;
+/**
+ * Sanitize untrusted text that must occupy exactly one rendered row.
+ *
+ * {@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.
+ */
+export declare function sanitizeDisplayLine(text: string): string;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/utils",
-	"version": "0.14.2",
+	"version": "0.15.0",
 	"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.14.2",
+		"@gajae-code/natives": "0.15.0",
 		"beautiful-mermaid": "^1.1.3",
 		"handlebars": "^4.7.9",
 		"winston": "^3.19.0",
@@ -41,7 +41,7 @@
 		"@types/bun": "^1.3.14"
 	},
 	"engines": {
-		"bun": ">=1.3.14"
+		"bun": ">=1.4.0"
 	},
 	"files": [
 		"src",

package/src/crash-journal.ts

@@ -24,6 +24,7 @@ export const CRASH_EVENT_MESSAGE_MAX_BYTES = 256;
 
 export type CrashEvent =
 	| CrashOccurrenceEvent
+	| CrashRefusedEvent
 	| CrashReportedEvent
 	| CrashRelayedEvent
 	| CrashAcknowledgedEvent
@@ -39,6 +40,15 @@ export interface CrashOccurrenceEvent {
 	readonly messageClass: string;
 }
 
+export interface CrashRefusedEvent {
+	readonly kind: "refused";
+	readonly fingerprint: string;
+	readonly fpv: number;
+	readonly recordId: string;
+	readonly contractVersion: string;
+	readonly at: number;
+}
+
 export interface CrashReportedEvent {
 	readonly kind: "reported";
 	readonly fingerprint: string;
@@ -109,11 +119,20 @@ export function formatCrashEventLine(event: CrashEvent): string {
 							u: sanitizeEventText(truncateUtf8(event.issueUrl, 256)),
 							...(event.commented ? { c: 1 } : {}),
 						}
-					: event.kind === "relayed"
-						? { k: "relayed", fp: event.fingerprint, at: event.at, e: event.eventId, r: event.recordId }
-						: event.kind === "acknowledged"
-							? { k: "acknowledged", fp: event.fingerprint, at: event.at }
-							: { k: "nudged", at: event.at };
+					: event.kind === "refused"
+						? {
+								k: "refused",
+								fp: event.fingerprint,
+								v: event.fpv,
+								r: event.recordId,
+								c: sanitizeEventText(truncateUtf8(event.contractVersion, 64)),
+								at: event.at,
+							}
+						: event.kind === "relayed"
+							? { k: "relayed", fp: event.fingerprint, at: event.at, e: event.eventId, r: event.recordId }
+							: event.kind === "acknowledged"
+								? { k: "acknowledged", fp: event.fingerprint, at: event.at }
+								: { k: "nudged", at: event.at };
 		return `${CRASH_EVENT_KIND} ${JSON.stringify(body)}\n`;
 	};
 
@@ -169,6 +188,14 @@ export function parseCrashEventLine(line: string): CrashEvent | undefined {
 			if (typeof body.u !== "string" || body.u.length === 0) return undefined;
 			return { kind: "reported", fingerprint, at, issueUrl: sanitizeEventText(body.u), commented: body.c === 1 };
 		}
+		case "refused": {
+			if (!fingerprint) return undefined;
+			if (typeof body.r !== "string" || !/^[0-9a-f]{8,32}$/.test(body.r)) return undefined;
+			if (typeof body.v !== "number" || !Number.isSafeInteger(body.v) || body.v < 1) return undefined;
+			if (typeof body.c !== "string" || body.c.length === 0 || /[\u0000-\u001f\u007f-\u009f]/.test(body.c))
+				return undefined;
+			return { kind: "refused", fingerprint, fpv: body.v, recordId: body.r, contractVersion: body.c, at };
+		}
 		case "relayed": {
 			if (!fingerprint) return undefined;
 			if (typeof body.e !== "string" || !/^[0-9a-f]{32}$/.test(body.e)) return undefined;

package/src/dirs.ts

@@ -145,8 +145,9 @@ export function getProjectDir(): string {
 
 /** 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 = standardizeMacOSPath(process.cwd());
 }
 
 /**
@@ -169,9 +170,42 @@ function sanitizeConfigDirName(value: string | undefined): string | undefined {
 	return trimmed;
 }
 
-/** Get the config directory name relative to home (e.g. ".gjc" or PI_CONFIG_DIR override). */
 /**
- * Config-directory name, rejected when it comes from the caller's project `.env`.
+ * 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).
  *
  * The name is joined with the home directory to build the config root, and that
  * root plus the agent directory beneath it supply two of the `.env` files
@@ -186,25 +220,188 @@ function sanitizeConfigDirName(value: string | undefined): string | undefined {
  * happens to carry the identical value loses the override, which is the same
  * trade-off `resolveLiveCredentialEnvValue` already makes.
  */
-function trustedConfigDirName(name: "GJC_CONFIG_DIR" | "PI_CONFIG_DIR"): string | undefined {
+function trustedValue(
+	name: string,
+	project: { values: Record<string, string>; dynamic: Set<string> },
+): string | undefined {
 	const value = process.env[name];
 	if (!value) return undefined;
-	if (parseEnvFile(path.join(process.cwd(), ".env"))[name] === value) return undefined;
+	const key = canonicalEnvKey(name);
+	const projectValue = project.values[key];
+	if (projectValue !== undefined && (project.dynamic.has(key) || projectValue === value)) return undefined;
 	return value;
 }
 
-export function getConfigDirName(): string {
-	// Both guards apply: the value must come from a trusted source (not the
-	// caller's project `.env`), and it must still be a single name that stays
-	// beneath home once joined.
+function resolveConfigDirName(project: { values: Record<string, string>; dynamic: Set<string> }): string {
 	return (
-		sanitizeConfigDirName(trustedConfigDirName("GJC_CONFIG_DIR")) ??
-		sanitizeConfigDirName(trustedConfigDirName("PI_CONFIG_DIR")) ??
+		sanitizeConfigDirName(trustedValue("GJC_CONFIG_DIR", project)) ??
+		sanitizeConfigDirName(trustedValue("PI_CONFIG_DIR", project)) ??
 		CONFIG_DIR_NAME
 	);
 }
 
-/** Get the config agent directory name relative to home (e.g. ".gjc/agent" or PI_CONFIG_DIR + "/agent"). */
+/**
+ * A home directory is usable only when it is absolute and resolves to somewhere
+ * strictly below a filesystem root. A relative value would anchor user state
+ * beneath whatever the current directory happens to be, and a root would place
+ * it at `/.gjc`.
+ *
+ * The root test normalizes first, because a root has many spellings: `/.`, `//`,
+ * `/foo/..` and `C:\x\..` are all roots that a raw string comparison against
+ * `path.parse(home).root` misses, and `path.join(home, ".gjc")` would happily
+ * produce `/.gjc` from every one of them.
+ *
+ * The **original spelling** is returned, never the normalized form. Provenance
+ * compares the declared dotenv value against this result, and both sides must
+ * stay in the same spelling: canonicalizing only this side would make
+ * `HOME=/tmp/base/../attacker` compare unequal to its own declaration and let a
+ * project-planted home through as if it were operator-supplied.
+ */
+function usableHome(home: string | undefined): string | undefined {
+	if (!home || !path.isAbsolute(home)) return undefined;
+	const normalized = path.resolve(home);
+	return normalized === path.parse(normalized).root ? undefined : home;
+}
+
+/**
+ * The account home for the running uid, read through the operating system's own
+ * account database.
+ *
+ * On Linux this must go through NSS rather than parsing `/etc/passwd`: LDAP and
+ * SSSD accounts have no local passwd entry, and a direct file read would miss
+ * them and fall through to an environment-derived value. `getent passwd` is the
+ * NSS front end, so it resolves local and directory-backed accounts alike.
+ *
+ * Only an **environment-independent** result is memoized, and only on success.
+ * The cache is keyed by the effective account identity, not by process lifetime:
+ * a setuid or container identity transition must never reuse another uid's home.
+ * The NSS answer cannot change during one identity's process lifetime, so
+ * per-identity caching is safe.
+ * The `os.userInfo()` fallback is different: Bun derives `homedir` from `$HOME`,
+ * so caching it would freeze one side of the independence comparison in
+ * {@link resolveTrustedHome}. A planted home that was live at first resolution
+ * would stay cached, and once the runtime home moved it would no longer *equal*
+ * the runtime home -- passing the echo check and being promoted to independent
+ * evidence. Provenance is carried with the value so that can never happen.
+ */
+type AccountHome = { home: string; envDerived: boolean };
+type AccountIdentity = { key: string; uid: number };
+
+const accountHomeCache = new Map<string, AccountHome>();
+
+function accountIdentity(info: os.UserInfo<string>): AccountIdentity {
+	const uid = process.platform === "win32" ? info.uid : (process.geteuid?.() ?? info.uid);
+	return {
+		key: `${process.platform}:uid=${uid}:user=${info.username}`,
+		uid,
+	};
+}
+
+/** The uid's home field from the NSS account database, or undefined. */
+function nssAccountHome(uid: number): string | undefined {
+	try {
+		// Spawned with an empty environment so nothing the caller controls (HOME,
+		// NSS module configuration, locale) can steer the answer.
+		const result = Bun.spawnSync({
+			cmd: ["getent", "passwd", String(uid)],
+			env: { PATH: "/usr/bin:/bin:/usr/sbin:/sbin", LC_ALL: "C" },
+			stdout: "pipe",
+			stderr: "ignore",
+		});
+		if (result.exitCode !== 0) return undefined;
+		// `getent` echoes passwd-format records; the home directory is field 6.
+		const line = new TextDecoder().decode(result.stdout).split("\n")[0];
+		return usableHome(line?.split(":")[5]);
+	} catch {
+		return undefined;
+	}
+}
+
+function accountHomeFromSystem(): AccountHome | undefined {
+	try {
+		const info = os.userInfo();
+		const identity = accountIdentity(info);
+		const cached = accountHomeCache.get(identity.key);
+		if (cached !== undefined) return cached;
+		if (process.platform === "linux") {
+			const nss = nssAccountHome(identity.uid);
+			if (nss !== undefined) {
+				// NSS is environment-independent and stable: safe to memoize.
+				const result = { home: nss, envDerived: false };
+				accountHomeCache.set(identity.key, result);
+				return result;
+			}
+		}
+		// `os.userInfo().homedir` is the portable path for macOS and Windows, and on
+		// Linux is reached only when NSS is unavailable. Bun derives it from `$HOME`,
+		// so it is re-read every time and never cached, and it is flagged so the
+		// caller can refuse to treat it as independent evidence.
+		const fallback = usableHome(info.homedir);
+		if (fallback !== undefined) return { home: fallback, envDerived: true };
+	} catch {
+		// Do not retain or consult a prior identity's result when the current
+		// identity cannot be observed. An unavailable uid is not evidence for any
+		// other uid and must fail closed instead of inheriting stale state.
+		return undefined;
+	}
+	return undefined;
+}
+
+/**
+ * Resolve the authoritative home for user-scope state.
+ *
+ * Two properties must hold together, and pinning either one alone breaks the
+ * other (issue #4761):
+ *
+ * 1. **Provenance.** Bun overlays a checkout's `.env` into `process.env` before
+ *    any module runs, so a repository can plant HOME/USERPROFILE and redirect
+ *    user state — including the `.env` files `$credentialEnv` treats as trusted.
+ *    When the platform-authoritative variable is indistinguishable from the
+ *    value the project dotenv declares, the OS account database wins instead.
+ * 2. **Call-time resolution.** The trusted home is *derived*, never snapshotted
+ *    at module load. A resolution frozen at import silently loses every
+ *    user-scope location whenever the runtime home is established or changed
+ *    after this module initializes — which is exactly how user-scope skill and
+ *    MCP discovery regressed.
+ *
+ * `os.homedir()` is the runtime candidate: on POSIX it reflects HOME, on Windows
+ * USERPROFILE, and it falls back to the account database on its own. Reading it
+ * 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 {
+	const authoritativeHomeKey = process.platform === "win32" ? "USERPROFILE" : "HOME";
+	const declaredHomeKey = canonicalEnvKey(authoritativeHomeKey);
+	const declaredHome = project.values[declaredHomeKey];
+	// A relative or filesystem-root runtime home would anchor user state beneath
+	// the current directory (or at `/`), so it is not a usable candidate no matter
+	// how it was supplied. Validate it exactly as the account home is validated.
+	const runtimeHome = usableHome(os.homedir());
+	// Only the platform-authoritative variable can select the home. In particular,
+	// do not let the opposite platform variable (or a project dotenv value
+	// overlaid into it) redirect user state when this is absent.
+	const ambiguousHome =
+		declaredHome !== undefined && (project.dynamic.has(declaredHomeKey) || declaredHome === runtimeHome);
+	// The account lookup is consulted lazily. It can spawn the NSS front end, and
+	// this resolver runs on every directory access, so an unambiguous runtime home
+	// -- the ordinary CLI path -- must never pay for it.
+	if (!ambiguousHome && runtimeHome !== undefined) return runtimeHome;
+
+	const accountHome = accountHomeFromSystem();
+	if (ambiguousHome) {
+		// The account home is independent evidence only when it is not itself derived
+		// from the environment. An `os.userInfo()` fallback echoes `$HOME`, so a
+		// project-declared home would otherwise come back as its own justification.
+		// Fail closed: with no independent evidence the resolver yields a filesystem
+		// root, which `#homeAvailable` rejects, rather than honoring the declared
+		// home. Issue #4773 owns widening that fallback; do not weaken it here.
+		if (accountHome === undefined || accountHome.envDerived) return path.parse(process.cwd()).root;
+		return accountHome.home;
+	}
+	// No usable runtime home: fall back to whatever the account database reports.
+	if (accountHome !== undefined) return accountHome.home;
+	throw new Error("Unable to determine a trustworthy account home directory");
+}
 export function getConfigAgentDirName(): string {
 	return `${getConfigDirName()}/agent`;
 }
@@ -220,55 +417,100 @@ type XdgCategory = "data" | "state" | "cache";
  * variables are set, paths are redirected under $XDG_*_HOME/gjc/. A new
  * instance is created whenever the agent directory changes, which naturally
  * invalidates all cached paths.
+ *
+ * The trusted home is re-derived on each access (see {@link resolveTrustedHome})
+ * and every cached path is rebuilt when it changes, so a home established or
+ * mocked after module load is honored without weakening the provenance rule.
  */
 class DirResolver {
-	readonly configRoot: string;
-	readonly agentDir: string;
+	configRoot: string;
+	agentDir: string;
+	readonly #projectEnv: { values: Record<string, string>; dynamic: Set<string> };
+	#configDirName: string;
+	readonly #agentDirOverride: boolean;
+	#trustedHome: string;
+	/**
+	 * Whether this resolver's agent directory may follow `$XDG_*_HOME`, decided
+	 * once at construction and never re-derived from the path afterwards.
+	 */
+	#xdgEligible: boolean;
 
 	// Per-category base dirs. Without XDG, all three equal configRoot / agentDir.
 	// With XDG on Linux, they point to $XDG_*_HOME/gjc/.
-	readonly #rootDirs: Record<XdgCategory, string>;
-	readonly #agentDirs: Record<XdgCategory, string>;
+	#rootDirs: Record<XdgCategory, string>;
+	#agentDirs: Record<XdgCategory, string>;
 
 	readonly #rootCache = new Map<string, string>();
 	readonly #agentCache = new Map<string, string>();
 
-	constructor(agentDirOverride?: string) {
-		this.configRoot = path.join(os.homedir(), getConfigDirName());
+	constructor(agentDirOverride?: string, snapshot = projectEnvSnapshot()) {
+		this.#projectEnv = snapshot;
+		this.#configDirName = resolveConfigDirName(snapshot);
+		this.#trustedHome = resolveTrustedHome(snapshot);
+		this.configRoot = path.join(this.#trustedHome, this.#configDirName);
 
 		const defaultAgent = path.join(this.configRoot, "agent");
+		this.#agentDirOverride = Boolean(agentDirOverride);
 		this.agentDir = agentDirOverride ? path.resolve(agentDirOverride) : defaultAgent;
+		// An agent directory equal to the home-derived default *is* the default
+		// profile, XDG categories included, however it arrived.
+		//
+		// Deciding this from override state instead was tried and reverted: it is
+		// unobservably wrong. `setAgentDir()` exports `GJC_CODING_AGENT_DIR`, so a
+		// child process inherits the same value the parent set programmatically and
+		// cannot tell the two apart. Treating the inherited form as "not default"
+		// put parent and child on different storage lanes for one logical profile --
+		// the parent reading `$XDG_STATE_HOME/gjc/python-gateway` while the child
+		// read `<agentDir>/python-gateway`. Splitting a live store in half is worse
+		// than the narrower complaint it was meant to answer.
 		const isDefault = this.agentDir === defaultAgent;
+		// That decision is then *sticky*. Recomputing it later from path shape is
+		// what let a pinned agent directory silently change storage lane when a home
+		// refresh made it coincide with the new default: `getAgentDir()` looked
+		// unchanged while `agent.db` moved into `$XDG_DATA_HOME/gjc`.
+		this.#xdgEligible = isDefault;
+
+		this.#rootDirs = { data: this.configRoot, state: this.configRoot, cache: this.configRoot };
+		this.#agentDirs = { data: this.agentDir, state: this.agentDir, cache: this.agentDir };
+		this.refreshCategoryDirs(snapshot, isDefault);
+	}
 
-		// XDG is a Linux convention. On other platforms, or for non-default
-		// profiles, all categories resolve to the legacy paths.
+	/**
+	 * `isDefault` decides whether the agent directory may follow `$XDG_*_HOME`.
+	 *
+	 * It is always supplied by the caller and never defaulted: the only correct
+	 * value is the construction-time decision held in `#xdgEligible`, and
+	 * re-deriving it from path shape is exactly the bug that let a directory
+	 * 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 {
 		let xdgData: string | undefined;
 		let xdgState: string | undefined;
 		let xdgCache: string | undefined;
 		if ((process.platform === "linux" || process.platform === "darwin") && isDefault) {
 			const resolveIf = (envVar: string) => {
-				const value = process.env[envVar];
-				if (value) {
-					try {
-						const joined = path.join(value, APP_NAME);
-						if (fs.existsSync(joined)) {
-							return joined;
-						}
-					} catch {}
+				const value = trustedValue(envVar, snapshot);
+				if (!value) return undefined;
+				try {
+					const joined = path.join(value, APP_NAME);
+					return fs.existsSync(joined) ? joined : undefined;
+				} catch {
+					return undefined;
 				}
-				return undefined;
 			};
 			xdgData = resolveIf("XDG_DATA_HOME");
 			xdgState = resolveIf("XDG_STATE_HOME");
 			xdgCache = resolveIf("XDG_CACHE_HOME");
 		}
-
 		this.#rootDirs = {
 			data: xdgData ?? this.configRoot,
 			state: xdgState ?? this.configRoot,
 			cache: xdgCache ?? this.configRoot,
 		};
-		// XDG flattens the agent/ prefix: ~/.gjc/agent/sessions → $XDG_DATA_HOME/gjc/sessions
 		this.#agentDirs = {
 			data: xdgData ?? this.agentDir,
 			state: xdgState ?? this.agentDir,
@@ -276,8 +518,47 @@ class DirResolver {
 		};
 	}
 
+	/**
+	 * Re-derive the trusted home and the caller-supplied config-dir override
+	 * without replacing the trust snapshot.
+	 *
+	 * Both inputs are call-time: the home comes from {@link resolveTrustedHome}
+	 * (provenance-checked, never an import-time snapshot) and the config-dir name
+	 * from the trusted-value rule. When either changes, the config root, the
+	 * default agent dir, the XDG category dirs and both path caches are rebuilt
+	 * so reads and writes cannot straddle two different homes.
+	 */
+	refreshConfigDirOverride(): void {
+		const nextConfigDirName = resolveConfigDirName(this.#projectEnv);
+		const nextHome = resolveTrustedHome(this.#projectEnv);
+		if (nextConfigDirName === this.#configDirName && nextHome === this.#trustedHome) return;
+		const nextConfigRoot = path.join(nextHome, nextConfigDirName);
+		const nextAgentDir = this.#agentDirOverride ? this.agentDir : path.join(nextConfigRoot, "agent");
+		this.#trustedHome = nextHome;
+		this.#configDirName = nextConfigDirName;
+		this.configRoot = nextConfigRoot;
+		this.agentDir = nextAgentDir;
+		// Reuse the construction-time decision rather than re-deriving it, so an
+		// agent directory never changes storage lane just because a home refresh made
+		// its path coincide with (or diverge from) the new default.
+		this.refreshCategoryDirs(this.#projectEnv, this.#xdgEligible);
+		this.#rootCache.clear();
+		this.#agentCache.clear();
+	}
+
+	/** Whether the resolved home is a real directory rather than a filesystem root. */
+	get #homeAvailable(): boolean {
+		return this.#trustedHome !== path.parse(this.#trustedHome).root;
+	}
+
+	isProjectEnvDeclaration(name: string): boolean {
+		return Object.hasOwn(this.#projectEnv.values, canonicalEnvKey(name));
+	}
+
 	/** Config-root subdirectory, with optional XDG override. */
 	rootSubdir(subdir: string, xdg?: XdgCategory): string {
+		this.refreshConfigDirOverride();
+		if (!this.#homeAvailable) throw new Error("User state is unavailable: no trustworthy home directory");
 		const cached = this.#rootCache.get(subdir);
 		if (cached) return cached;
 		const base = xdg ? this.#rootDirs[xdg] : this.configRoot;
@@ -288,6 +569,8 @@ class DirResolver {
 
 	/** Agent subdirectory, with optional XDG override. */
 	agentSubdir(userAgentDir: string | undefined, subdir: string, xdg?: XdgCategory): string {
+		this.refreshConfigDirOverride();
+		if (!this.#homeAvailable) throw new Error("User state is unavailable: no trustworthy home directory");
 		if (!userAgentDir || userAgentDir === this.agentDir) {
 			const cached = this.#agentCache.get(subdir);
 			if (cached) return cached;
@@ -298,51 +581,28 @@ class DirResolver {
 		}
 		return path.join(userAgentDir, subdir);
 	}
-}
 
-/**
- * Agent-directory override, rejected when it comes from the caller's project
- * `.env`.
- *
- * This directory selects the agent's own `.env`, which is one of the trusted
- * sources `$credentialEnv` consults. Bun loads `cwd/.env` into `process.env`
- * before any module runs, so a repository could otherwise point this at a
- * directory it ships and have its own `.env` treated as trusted — recovering
- * every redirect the credential boundary is meant to reject.
- *
- * `env.ts` imports this module, so the check cannot go through `$credentialEnv`;
- * it applies the same conservative ambiguity rule directly: a value that matches
- * what the project `.env` sets is not honoured. An operator whose environment
- * happens to carry the identical value loses the override, which is the same
- * trade-off `resolveLiveCredentialEnvValue` already makes.
- */
-function trustedAgentDirOverrideFor(name: "GJC_CODING_AGENT_DIR" | "PI_CODING_AGENT_DIR"): string | undefined {
-	const value = process.env[name];
-	if (!value) return undefined;
-	if (parseEnvFile(path.join(process.cwd(), ".env"))[name] === value) return undefined;
-	return value;
-}
-
-/**
- * Both spellings are honoured, mirroring `getConfigDirName`.
- *
- * `PI_CODING_AGENT_DIR` is the legacy alias this module's own header documents,
- * and parts of the product already resolve it (`gc-runtime.ts:370`,
- * `deep-interview-runtime.ts:384`). Reading only the `GJC_` spelling here split
- * the agent directory in two: `gjc gc` operated on the aliased directory while
- * everything reaching `getAgentDir()` stayed on the default.
- */
-function trustedAgentDirOverride(): string | undefined {
-	return trustedAgentDirOverrideFor("GJC_CODING_AGENT_DIR") ?? trustedAgentDirOverrideFor("PI_CODING_AGENT_DIR");
+	get configDirName(): string {
+		return this.#configDirName;
+	}
+	get trustedHome(): string {
+		this.refreshConfigDirOverride();
+		return this.#trustedHome;
+	}
+	assertHomeAvailable(): void {
+		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> } {
+		return this.#projectEnv;
+	}
 }
 
-let dirs = new DirResolver(trustedAgentDirOverride());
-
-// Anchor home for the resolver. Captured at module load to stay stable across
-// test mocks of `os.homedir()`. `getPluginsDir(home)` compares against this so
-// production callers (`home === RESOLVER_HOME`) hit the XDG-aware resolver while
-// tests passing a temp HOME short-circuit to a deterministic path.
-const RESOLVER_HOME = os.homedir();
+const INITIAL_PROJECT_SNAPSHOT = projectEnvSnapshot();
+const trustedAgentOverride =
+	trustedValue("GJC_CODING_AGENT_DIR", INITIAL_PROJECT_SNAPSHOT) ??
+	trustedValue("PI_CODING_AGENT_DIR", INITIAL_PROJECT_SNAPSHOT);
+let dirs = new DirResolver(trustedAgentOverride, INITIAL_PROJECT_SNAPSHOT);
 
 // =============================================================================
 // Root directories
@@ -350,19 +610,54 @@ const RESOLVER_HOME = os.homedir();
 
 /** Get the config root directory (~/.gjc). */
 export function getConfigRootDir(): string {
+	dirs.refreshConfigDirOverride();
+	dirs.assertHomeAvailable();
 	return dirs.configRoot;
 }
 
-/** Set the coding agent directory. Creates a fresh resolver, invalidating all cached paths. */
+/**
+ * The authoritative home for user-scope state.
+ *
+ * Provenance-checked and resolved at call time: a home established or changed
+ * after this module loaded is honored, while a home the project dotenv could
+ * have planted is rejected in favor of the OS account database. See
+ * {@link resolveTrustedHome}.
+ */
+export function getTrustedHomeDir(): string {
+	dirs.assertHomeAvailable();
+	return dirs.trustedHome;
+}
+
+/** Trusted config root, resolved at call time; preserves the configured nested config-dir name. */
+export function getTrustedConfigRootDir(): string {
+	dirs.refreshConfigDirOverride();
+	dirs.assertHomeAvailable();
+	return dirs.configRoot;
+}
+
+/**
+ * Set the coding agent directory. Creates a fresh resolver, invalidating all
+ * cached paths.
+ *
+ * This also exports `GJC_CODING_AGENT_DIR`, so child processes inherit the same
+ * selection and resolve the same storage lane.
+ */
 export function setAgentDir(dir: string): void {
-	dirs = new DirResolver(dir);
+	dirs = new DirResolver(dir, dirs.trustSnapshot);
 	process.env.GJC_CODING_AGENT_DIR = dir;
 }
 
 /** Get the agent config directory (~/.gjc/agent). */
 export function getAgentDir(): string {
+	dirs.refreshConfigDirOverride();
+	dirs.assertHomeAvailable();
 	return dirs.agentDir;
 }
+
+export function getConfigDirName(): string {
+	dirs.refreshConfigDirOverride();
+	return dirs.configDirName;
+}
 /**
  * Join a file under the provenance-checked agent directory, never the XDG
  * state category. Automatic crash relay must not follow `XDG_STATE_HOME`:
@@ -375,7 +670,7 @@ export function getTrustedAgentFile(filename: string): string {
 
 /** Whether the current checkout declares an environment key in its `.env`. */
 export function isProjectEnvDeclaration(name: string): boolean {
-	return Object.hasOwn(parseEnvFile(path.join(process.cwd(), ".env")), name);
+	return dirs.isProjectEnvDeclaration(name);
 }
 
 /** Get the project-local config directory (.gjc). */
@@ -406,15 +701,24 @@ export function getLogPath(date = new Date()): string {
  * Get the plugins directory (~/.gjc/plugins or its XDG equivalent).
  *
  * No-arg form (production callers) goes through the XDG-aware DirResolver so
- * reads and writes always agree. The optional `home` parameter is for test
- * isolation: when it differs from `os.homedir()` it short-circuits the resolver
- * and returns `<home>/<configDir>/plugins` so tests with a temp HOME get a
- * deterministic path. Passing `os.homedir()` explicitly is identical to the
- * no-arg form — XDG semantics are preserved.
+ * reads and writes always agree. The optional `home` parameter names an explicit
+ * home: when it differs from the authoritative home resolved right now it
+ * short-circuits the resolver and returns `<home>/<configDir>/plugins`, giving
+ * callers that carry their own home (and tests with a temp HOME) a deterministic
+ * path. Passing the authoritative home explicitly is identical to the no-arg
+ * form — XDG semantics are preserved.
  */
 export function getPluginsDir(home?: string): string {
-	if (home !== undefined && home !== RESOLVER_HOME) {
-		return path.join(home, getConfigDirName(), "plugins");
+	if (home !== undefined) {
+		const explicitPath = () => path.join(home, resolveConfigDirName(dirs.trustSnapshot), "plugins");
+		try {
+			if (home !== dirs.trustedHome) return explicitPath();
+		} catch {
+			// An explicit home is the caller's documented escape hatch. If the
+			// authoritative home is unavailable, do not let its fail-closed resolver
+			// prevent a caller-owned plugin path from being returned.
+			return explicitPath();
+		}
 	}
 	return dirs.rootSubdir("plugins", "data");
 }
@@ -518,26 +822,6 @@ export function getStatsDbPath(): string {
 	return dirs.rootSubdir("stats.db", "data");
 }
 
-/** Get the autoresearch state directory (~/.gjc/autoresearch). */
-export function getAutoresearchDir(): string {
-	return dirs.rootSubdir("autoresearch", "state");
-}
-
-/** Get the per-project autoresearch state directory (~/.gjc/autoresearch/<encoded-project>). */
-export function getAutoresearchProjectDir(encodedProject: string): string {
-	return path.join(getAutoresearchDir(), encodedProject);
-}
-
-/** Get the per-project autoresearch SQLite database path (~/.gjc/autoresearch/<encoded-project>.db). */
-export function getAutoresearchDbPath(encodedProject: string): string {
-	return path.join(getAutoresearchDir(), `${encodedProject}.db`);
-}
-
-/** Get the per-run artifact directory (~/.gjc/autoresearch/<encoded-project>/runs/<runId>). */
-export function getAutoresearchRunDir(encodedProject: string, runId: number): string {
-	return path.join(getAutoresearchProjectDir(encodedProject), "runs", String(runId).padStart(4, "0"));
-}
-
 // =============================================================================
 // Agent subdirectories (~/.gjc/agent/*)
 // =============================================================================
@@ -670,10 +954,17 @@ export function getProjectPluginOverridesPath(cwd: string = getProjectDir()): st
 // MCP config paths
 // =============================================================================
 
-/** Get the primary MCP config file path (first candidate). */
-export function getMCPConfigPath(scope: "user" | "project", cwd: string = getProjectDir()): string {
+/**
+ * Get the primary MCP config file path (first candidate).
+ *
+ * User scope lives in the agent directory, so a profile override
+ * (`--agent-dir`, `GJC_CODING_AGENT_DIR`, `setAgentDir()`) moves it. Pass
+ * `agentDir` to resolve the scope of a session whose agent directory differs
+ * from the process-wide one.
+ */
+export function getMCPConfigPath(scope: "user" | "project", cwd: string = getProjectDir(), agentDir?: string): string {
 	if (scope === "user") {
-		return path.join(getAgentDir(), "mcp.json");
+		return path.join(agentDir ?? getAgentDir(), "mcp.json");
 	}
 	return path.join(getProjectAgentDir(cwd), "mcp.json");
 }

package/src/env-file.ts

@@ -110,7 +110,7 @@ export function parseShellEnvFile(filePath: string): Record<string, string> {
  * `filterCredentialInheritedEnv`) decide provenance by comparing
  * `process.env` against this parse, so the accepted syntax must be a superset
  * of what Bun's own dotenv loader honors in `cwd/.env`: `export KEY=value`,
- * whitespace around `=`, and `#` comments after unquoted values (quotes keep
+ * whitespace around `=` or `:`, and `#` comments after unquoted values (quotes keep
  * their `#`). Values that Bun would expand (`$VAR`, `${VAR}`, backticks,
  * command substitution) are kept as their literal text: the trust rule only
  * needs the parser to see the key at all, and an operator environment value
@@ -134,7 +134,7 @@ export function parseEnvFileContent(content: string): Record<string, string> {
 		// Skip comments and blank lines
 		if (!trimmed || trimmed.startsWith("#")) continue;
 
-		const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(trimmed);
+		const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*(?:=|:)\s*(.*)$/.exec(trimmed);
 		if (!match) continue;
 
 		const key = match[1];

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 } from "./dirs";
+import { canonicalEnvKey, getAgentDir, getConfigRootDir, getTrustedHomeDir } from "./dirs";
 import { isSafeEnvName, isSafeEnvValue } from "./spawn-env";
 
 export { filterProcessEnv, isSafeEnvName, isSafeEnvValue } from "./spawn-env";
@@ -11,9 +11,38 @@ import { parseEnvFile, parseEnvFileContent, parseShellEnvFile } from "./env-file
 // Re-exported so the public surface of this module is unchanged.
 export { isValidEnvName, parseEnvFile, parseShellEnvFile } from "./env-file";
 
+function loadProjectEnv(): { values: Record<string, string>; dynamic: Set<string> } {
+	const cwd = process.cwd();
+	const nodeEnv = process.env.NODE_ENV || Bun.env.NODE_ENV;
+	// Match Bun's dotenv precedence. Validate before interpolation so a hostile
+	// NODE_ENV cannot introduce separators or `..` path segments.
+	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) {
+		const parsed = parseEnvFile(path.join(cwd, file));
+		for (const [rawKey, value] of Object.entries(parsed)) {
+			// Windows environment names are case-insensitive, so the guard lookups
+			// below must see the same key Bun loaded into `process.env`.
+			const key = canonicalEnvKey(rawKey);
+			values[key] = value;
+			// Track dynamic provenance only for the winning declaration.
+			if (/[$`]/.test(value)) dynamic.add(key);
+			else dynamic.delete(key);
+		}
+	}
+	return { values, dynamic };
+}
+
 function resolveFileEnvValue(file: Record<string, string>, name: string): string | undefined {
 	if (!isSafeEnvName(name)) return undefined;
-	const value = file[name];
+	const value = file[canonicalEnvKey(name)];
 	if (value === undefined || !isSafeEnvValue(value)) return undefined;
 	const trimmed = value.trim();
 	return trimmed.length > 0 ? trimmed : undefined;
@@ -25,7 +54,12 @@ type TrustedAgentEnvRead =
 	| { status: "ok"; values: Record<string, string> };
 
 function readTrustedAgentEnv(): TrustedAgentEnvRead {
-	const filePath = path.join(getAgentDir(), ".env");
+	let filePath: string;
+	try {
+		filePath = path.join(getAgentDir(), ".env");
+	} catch {
+		return { status: "unavailable", values: {} };
+	}
 	let fileDescriptor: number | undefined;
 	try {
 		const linkStats = fs.lstatSync(filePath);
@@ -51,30 +85,66 @@ function filterCredentialInheritedEnv(env: Record<string, string | undefined>):
 		if (!isSafeEnvName(key) || value === undefined || !isSafeEnvValue(value)) continue;
 
 		// Bun may have already loaded cwd/.env before JS runs. It does not expose the
-		// source of each entry, so an exact match with projectEnv is ambiguous. Use
-		// the safer credential rule: ambiguous project matches are excluded from the
-		// credential-only inherited snapshot, while remaining available through $env.
+		// source of each entry, so a matching project declaration is ambiguous. A
+		// dynamic dotenv declaration is also ambiguous even when expansion changes
+		// its runtime value. Exclude those from the credential-only snapshot while
+		// keeping them available through $env.
 		const projectValue = resolveFileEnvValue(projectEnv, key);
-		if (projectValue !== undefined && projectValue === value) continue;
+		if (projectValue !== undefined && (projectSnapshot.dynamic.has(canonicalEnvKey(key)) || projectValue === value))
+			continue;
 
 		result[key] = value;
 	}
 	return result;
 }
 
-// Eagerly parse the user's $HOME/.env and the current project's .env (from cwd)
-const homeShellEnv = {
-	...parseShellEnvFile(path.join(os.homedir(), ".zshenv")),
-	...parseShellEnvFile(path.join(os.homedir(), ".zprofile")),
-	...parseShellEnvFile(path.join(os.homedir(), ".zshrc")),
-	...parseShellEnvFile(path.join(os.homedir(), ".bash_profile")),
-	...parseShellEnvFile(path.join(os.homedir(), ".bashrc")),
-};
-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"));
+// Parse the current project's .env first. Bun may have overlaid HOME from it
+// before this module runs, so a declared HOME must never select user credential
+// files for the credential-only snapshot.
+const projectSnapshot = loadProjectEnv();
+const projectEnv = projectSnapshot.values;
+const authoritativeHomeKey = process.platform === "win32" ? "USERPROFILE" : "HOME";
+const declaredHomeKey = canonicalEnvKey(authoritativeHomeKey);
+const declaredHome = projectEnv[declaredHomeKey];
+const runtimeHome = process.env[authoritativeHomeKey];
+const rejectProjectHome =
+	declaredHome !== undefined &&
+	runtimeHome !== undefined &&
+	(projectSnapshot.dynamic.has(declaredHomeKey) || declaredHome === runtimeHome);
+let trustedEnvHome: string | undefined;
+try {
+	trustedEnvHome = rejectProjectHome ? getTrustedHomeDir() : os.homedir();
+} catch {
+	// No trustworthy account home means no user credential files are trusted.
+	trustedEnvHome = undefined;
+}
+
+// Eagerly parse the trusted user's env files and the project .env (from cwd)
+const homeShellEnv = trustedEnvHome
+	? {
+			...parseShellEnvFile(path.join(trustedEnvHome, ".zshenv")),
+			...parseShellEnvFile(path.join(trustedEnvHome, ".zprofile")),
+			...parseShellEnvFile(path.join(trustedEnvHome, ".zshrc")),
+			...parseShellEnvFile(path.join(trustedEnvHome, ".bash_profile")),
+			...parseShellEnvFile(path.join(trustedEnvHome, ".bashrc")),
+		}
+	: {};
+const homeEnv =
+	trustedEnvHome && path.resolve(trustedEnvHome) !== path.resolve(process.cwd())
+		? parseEnvFile(path.join(trustedEnvHome, ".env"))
+		: {};
+let piEnv: Record<string, string> = {};
+let agentEnv: Record<string, string> = {};
+try {
+	piEnv = parseEnvFile(path.join(getConfigRootDir(), ".env"));
+	agentEnv = parseEnvFile(path.join(getAgentDir(), ".env"));
+} catch {
+	// Keep credential resolution fail-closed when trusted user state is unavailable.
+}
 const initialTrustedAgentEnv = readTrustedAgentEnv();
+const projectLoadedEnv: Record<string, string | undefined> = Object.fromEntries(
+	Object.keys(projectEnv).map(key => [key, Bun.env[key]]),
+);
 
 const inheritedEnv = filterCredentialInheritedEnv(Bun.env);
 const rotatingAgentEnvNames = new Set(Object.keys(agentEnv));
@@ -100,11 +170,12 @@ function resolveLiveCredentialEnvValue(name: string): string | undefined {
 	const trimmed = value.trim();
 	if (trimmed.length === 0) return undefined;
 
-	const projectValue = resolveFileEnvValue(projectEnv, name);
 	if (
-		projectValue !== undefined &&
-		projectValue === trimmed &&
-		resolveFileEnvValue(inheritedEnv, name) === undefined
+		Object.hasOwn(projectEnv, canonicalEnvKey(name)) &&
+		resolveFileEnvValue(inheritedEnv, name) === undefined &&
+		(projectSnapshot.dynamic.has(canonicalEnvKey(name)) ||
+			trimmed === resolveFileEnvValue(projectEnv, name) ||
+			trimmed === projectLoadedEnv[canonicalEnvKey(name)])
 	) {
 		return undefined;
 	}

package/src/header-value.ts

@@ -0,0 +1,15 @@
+/**
+ * Sanitize a value destined for an HTTP header.
+ *
+ * OS-derived components (kernel release, hostname, os.version) can contain
+ * non-ASCII characters — e.g. Android kernel releases such as
+ * `4.4.302-Minimal™-EAS-QTI_Haptic-R26` — which `Headers`/`fetch` reject
+ * before the request is ever sent. Strip everything outside printable
+ * ASCII so header construction can never throw on runtime-derived values.
+ */
+
+const NON_PRINTABLE_ASCII = /[^\x20-\x7e]/g;
+
+export function sanitizeHeaderComponent(value: string): string {
+	return value.replace(NON_PRINTABLE_ASCII, "");
+}

package/src/index.ts

@@ -12,6 +12,7 @@ export * from "./format";
 export * from "./frontmatter";
 export * from "./fs-error";
 export * from "./glob";
+export * from "./header-value";
 export * from "./hook-fetch";
 export * from "./json";
 export * as logger from "./logger";

package/src/postmortem.ts

@@ -177,6 +177,14 @@ function installProcessStdoutWriteClassifier(): void {
 		encoding?: BufferEncoding | StdoutWriteCallback,
 		callback?: StdoutWriteCallback,
 	): boolean => {
+		// Bun 1.4 stopped surfacing a broken stdout pipe as a synchronous throw
+		// from `write()`; it now rejects asynchronously (via the write's own
+		// callback and an `unhandledRejection`) with an error object that lacks
+		// the `fd`/`syscall` fields the fallback attribution path relies on.
+		// Always attach an internal callback — even when the caller passed none —
+		// so `markDirectProcessStdoutWriteError` still runs before that async
+		// rejection reaches `handleFatalError`. The synchronous `try/catch` below
+		// stays as a fallback for Bun/Node versions that still throw synchronously.
 		try {
 			if (typeof encoding === "function") return originalWrite(chunk, markCallback(encoding));
 			if (callback) {
@@ -184,8 +192,16 @@ function installProcessStdoutWriteClassifier(): void {
 					? originalWrite(chunk, encoding, markCallback(callback))
 					: originalWrite(chunk, markCallback(callback));
 			}
-			if (encoding === undefined) return originalWrite(chunk);
-			return typeof chunk === "string" ? originalWrite(chunk, encoding) : originalWrite(chunk);
+			return typeof chunk === "string"
+				? originalWrite(
+						chunk,
+						encoding,
+						markCallback(() => {}),
+					)
+				: originalWrite(
+						chunk,
+						markCallback(() => {}),
+					);
 		} catch (error) {
 			stdoutEpipeClassifier.markDirectProcessStdoutWriteError(error);
 			throw error;

package/src/sanitize-text.ts

@@ -28,6 +28,18 @@ export function sanitizeText(text: string): string {
 	return sanitizeWellFormedText(text);
 }
 
+/**
+ * Sanitize untrusted text that must occupy exactly one rendered row.
+ *
+ * {@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.
+ */
+export function sanitizeDisplayLine(text: string): string {
+	return sanitizeText(text.replace(/[\r\n]+/gu, " "));
+}
+
 function sanitizeWellFormedText(text: string): string {
 	CONTROL_RE.lastIndex = 0;
 	if (CONTROL_RE.exec(text) === null) return text;