@gajae-code/utils 0.11.11 → 0.12.1

package/dist/types/dirs.d.ts

@@ -1,8 +1,9 @@
 /**
  * Centralized path helpers for gajae-code config directories.
  *
- * Uses PI_CONFIG_DIR (default ".gjc") for the config root and
- * PI_CODING_AGENT_DIR to override the agent directory.
+ * Uses GJC_CONFIG_DIR (legacy alias PI_CONFIG_DIR, default ".gjc") for the
+ * config root and GJC_CODING_AGENT_DIR (legacy alias 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
@@ -44,7 +45,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;
-/** Get the config directory name relative to home (e.g. ".gjc" or PI_CONFIG_DIR override). */
 export declare function getConfigDirName(): string;
 /** Get the config agent directory name relative to home (e.g. ".gjc/agent" or PI_CONFIG_DIR + "/agent"). */
 export declare function getConfigAgentDirName(): string;
@@ -135,6 +135,8 @@ export declare function getModelDbPath(agentDir?: string): string;
 export declare function getSessionsDir(agentDir?: string): string;
 /** Get the content-addressed blob store directory (~/.gjc/agent/blobs). */
 export declare function getBlobsDir(agentDir?: string): string;
+/** Get the resident-text cache root for a profile agent directory. */
+export declare function getResidentCacheRootDir(profileAgentDir: string): string;
 /** Get the custom themes directory (~/.gjc/agent/themes). */
 export declare function getCustomThemesDir(agentDir?: string): string;
 /** Get the tools directory (~/.gjc/agent/tools). */

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

@@ -0,0 +1,21 @@
+/**
+ * Strict shell-identifier shape. Used for dotenv keys we accept into
+ * `Bun.env` — those should be referenceable as `$NAME` from POSIX shells,
+ * so we reject anything outside `[A-Za-z_][A-Za-z0-9_]*`.
+ */
+export declare function isValidEnvName(name: string): boolean;
+/**
+ * Parses simple POSIX shell environment assignments from files such as
+ * ~/.zshrc without executing user shell code. Supports `export KEY=value` and
+ * `KEY=value`, including single/double quoted literal values. Dynamic shell
+ * expressions are intentionally ignored because evaluating startup files would
+ * run arbitrary code during CLI startup.
+ */
+export declare function parseShellEnvFile(filePath: string): Record<string, string>;
+/**
+ * Parses a .env file synchronously and extracts key-value string pairs.
+ * Ignores lines that are empty or start with '#'. Trims whitespace.
+ * Allows values to be quoted with single or double quotes.
+ * Returns an object of key-value pairs.
+ */
+export declare function parseEnvFile(filePath: string): Record<string, string>;

package/dist/types/env.d.ts

@@ -1,25 +1,5 @@
 export { filterProcessEnv, isSafeEnvName, isSafeEnvValue } from "./spawn-env";
-/**
- * Strict shell-identifier shape. Used for dotenv keys we accept into
- * `Bun.env` — those should be referenceable as `$NAME` from POSIX shells,
- * so we reject anything outside `[A-Za-z_][A-Za-z0-9_]*`.
- */
-export declare function isValidEnvName(name: string): boolean;
-/**
- * Parses simple POSIX shell environment assignments from files such as
- * ~/.zshrc without executing user shell code. Supports `export KEY=value` and
- * `KEY=value`, including single/double quoted literal values. Dynamic shell
- * expressions are intentionally ignored because evaluating startup files would
- * run arbitrary code during CLI startup.
- */
-export declare function parseShellEnvFile(filePath: string): Record<string, string>;
-/**
- * Parses a .env file synchronously and extracts key-value string pairs.
- * Ignores lines that are empty or start with '#'. Trims whitespace.
- * Allows values to be quoted with single or double quotes.
- * Returns an object of key-value pairs.
- */
-export declare function parseEnvFile(filePath: string): Record<string, string>;
+export { isValidEnvName, parseEnvFile, parseShellEnvFile } from "./env-file";
 export declare function $inheritedEnv(name: string): string | undefined;
 /**
  * Intentional re-export of Bun.env.

package/dist/types/procmgr.d.ts

@@ -28,6 +28,12 @@ export declare function resolveBasicShell(): string | undefined;
  * 4. Fallback: sh
  */
 export declare function getShellConfig(customShellPath?: string): ShellConfig;
+/**
+ * Clear the memoized shell configuration so the next {@link getShellConfig}
+ * call re-resolves the shell and re-reads the environment (shell selection and
+ * the bash CI/login flags). Primarily for tests that vary those inputs.
+ */
+export declare function resetShellConfigCache(): void;
 /**
  * Check if a process is running.
  */

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/utils",
-	"version": "0.11.11",
+	"version": "0.12.1",
 	"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.11.11",
+		"@gajae-code/natives": "0.12.1",
 		"beautiful-mermaid": "^1.1.3",
 		"handlebars": "^4.7.9",
 		"winston": "^3.19.0",

package/src/dirs.ts

@@ -1,8 +1,9 @@
 /**
  * Centralized path helpers for gajae-code config directories.
  *
- * Uses PI_CONFIG_DIR (default ".gjc") for the config root and
- * PI_CODING_AGENT_DIR to override the agent directory.
+ * Uses GJC_CONFIG_DIR (legacy alias PI_CONFIG_DIR, default ".gjc") for the
+ * config root and GJC_CODING_AGENT_DIR (legacy alias 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
@@ -15,6 +16,7 @@ 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";
 
 /** App name (e.g. "gjc") */
 export const APP_NAME: string = "gjc";
@@ -147,9 +149,57 @@ export function setProjectDir(dir: string): void {
 	process.chdir(projectDir);
 }
 
+/**
+ * Reject a configured config-directory name that would escape the home-relative
+ * root it is documented to stay under.
+ *
+ * The configured value names a directory beneath `<home>` — the discovery docs
+ * state that "even an absolute-looking configured name is joined beneath
+ * `<home>`", which `path.join` delivers for a leading separator but not for
+ * `..` segments. Consumers join this name with `<home>` (and with project
+ * ancestors) to locate user-level `mcp.json`, `SYSTEM.md`, skills, agents and
+ * installed plugins, so a `..` segment would point that discovery at a
+ * directory outside the config root entirely. Fall back to the default name
+ * instead of honoring an escaping value.
+ */
+function sanitizeConfigDirName(value: string | undefined): string | undefined {
+	const trimmed = value?.trim();
+	if (!trimmed) return undefined;
+	if (path.normalize(trimmed).split(/[\\/]/).includes("..")) return 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`.
+ *
+ * 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
+ * `$credentialEnv` treats as trusted. Bun loads `cwd/.env` into `process.env`
+ * before any module runs, so a repository could otherwise point the config root
+ * at a directory it ships and have its own `.env` treated as trusted —
+ * recovering every endpoint and credential redirect the boundary rejects.
+ *
+ * `env.ts` imports this module, so the check cannot go through `$credentialEnv`;
+ * it applies the same conservative ambiguity rule directly, matching how
+ * `GJC_CODING_AGENT_DIR` is treated.
+ */
+function trustedConfigDirName(name: "GJC_CONFIG_DIR" | "PI_CONFIG_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;
+}
+
 export function getConfigDirName(): string {
-	return process.env.GJC_CONFIG_DIR ?? process.env.PI_CONFIG_DIR ?? CONFIG_DIR_NAME;
+	// 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.
+	return (
+		sanitizeConfigDirName(trustedConfigDirName("GJC_CONFIG_DIR")) ??
+		sanitizeConfigDirName(trustedConfigDirName("PI_CONFIG_DIR")) ??
+		CONFIG_DIR_NAME
+	);
 }
 
 /** Get the config agent directory name relative to home (e.g. ".gjc/agent" or PI_CONFIG_DIR + "/agent"). */
@@ -248,7 +298,43 @@ class DirResolver {
 	}
 }
 
-let dirs = new DirResolver(process.env.GJC_CODING_AGENT_DIR);
+/**
+ * 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");
+}
+
+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
@@ -460,6 +546,11 @@ export function getBlobsDir(agentDir?: string): string {
 	return dirs.agentSubdir(agentDir, "blobs", "data");
 }
 
+/** Get the resident-text cache root for a profile agent directory. */
+export function getResidentCacheRootDir(profileAgentDir: string): string {
+	return dirs.agentSubdir(profileAgentDir, "resident-cache", "cache");
+}
+
 /** Get the custom themes directory (~/.gjc/agent/themes). */
 export function getCustomThemesDir(agentDir?: string): string {
 	return dirs.agentSubdir(agentDir, "themes");

package/src/env-file.ts

@@ -0,0 +1,115 @@
+/**
+ * Environment-file parsing primitives.
+ *
+ * Kept in a leaf module so both `env.ts` and `dirs.ts` can use them. `env.ts`
+ * imports `dirs.ts`, so anything `dirs.ts` needs from the env layer has to live
+ * below both of them.
+ */
+import * as fs from "node:fs";
+import { isSafeEnvValue } from "./spawn-env";
+
+const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * Strict shell-identifier shape. Used for dotenv keys we accept into
+ * `Bun.env` — those should be referenceable as `$NAME` from POSIX shells,
+ * so we reject anything outside `[A-Za-z_][A-Za-z0-9_]*`.
+ */
+export function isValidEnvName(name: string): boolean {
+	return ENV_NAME_RE.test(name);
+}
+
+function stripInlineShellComment(value: string): string {
+	let quote: '"' | "'" | undefined;
+	for (let i = 0; i < value.length; i++) {
+		const char = value[i];
+		if (char === "\\") {
+			i++;
+			continue;
+		}
+		if ((char === '"' || char === "'") && (!quote || quote === char)) {
+			quote = quote ? undefined : char;
+			continue;
+		}
+		if (char === "#" && !quote && (i === 0 || /\s/.test(value[i - 1] ?? ""))) {
+			return value.slice(0, i).trimEnd();
+		}
+	}
+	return value.trimEnd();
+}
+
+/**
+ * Parses simple POSIX shell environment assignments from files such as
+ * ~/.zshrc without executing user shell code. Supports `export KEY=value` and
+ * `KEY=value`, including single/double quoted literal values. Dynamic shell
+ * expressions are intentionally ignored because evaluating startup files would
+ * run arbitrary code during CLI startup.
+ */
+export function parseShellEnvFile(filePath: string): Record<string, string> {
+	const result: Record<string, string> = {};
+	try {
+		const content = fs.readFileSync(filePath, "utf-8");
+		for (const line of content.split("\n")) {
+			const trimmed = line.trim();
+			if (!trimmed || trimmed.startsWith("#")) continue;
+
+			const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)$/.exec(trimmed);
+			if (!match) continue;
+
+			const key = match[1];
+			if (!isValidEnvName(key)) continue;
+
+			let value = stripInlineShellComment(match[2] ?? "").trim();
+			if (value.endsWith(";")) value = value.slice(0, -1).trimEnd();
+			if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+				value = value.slice(1, -1);
+			}
+			if (!isSafeEnvValue(value)) continue;
+			if (/[$`]/.test(value)) continue;
+
+			result[key] = value;
+		}
+	} catch {
+		// File doesn't exist or can't be read - return empty result
+	}
+
+	return result;
+}
+
+/**
+ * Parses a .env file synchronously and extracts key-value string pairs.
+ * Ignores lines that are empty or start with '#'. Trims whitespace.
+ * Allows values to be quoted with single or double quotes.
+ * Returns an object of key-value pairs.
+ */
+export function parseEnvFile(filePath: string): Record<string, string> {
+	const result: Record<string, string> = {};
+	try {
+		const content = fs.readFileSync(filePath, "utf-8");
+		for (const line of content.split("\n")) {
+			const trimmed = line.trim();
+			// Skip comments and blank lines
+			if (!trimmed || trimmed.startsWith("#")) continue;
+
+			const eqIndex = trimmed.indexOf("=");
+			if (eqIndex === -1) continue;
+
+			const key = trimmed.slice(0, eqIndex).trim();
+			if (!isValidEnvName(key)) continue;
+
+			let value = trimmed.slice(eqIndex + 1).trim();
+
+			// Remove surrounding quotes (" or ')
+			if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+				value = value.slice(1, -1);
+			}
+			if (!isSafeEnvValue(value)) continue;
+
+			result[key] = value;
+		}
+	} catch {
+		// File doesn't exist or can't be read - return empty result
+	}
+
+	return result;
+}

package/src/env.ts

@@ -1,4 +1,3 @@
-import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { getAgentDir, getConfigRootDir } from "./dirs";
@@ -6,111 +5,10 @@ import { isSafeEnvName, isSafeEnvValue } from "./spawn-env";
 
 export { filterProcessEnv, isSafeEnvName, isSafeEnvValue } from "./spawn-env";
 
-const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+import { parseEnvFile, parseShellEnvFile } from "./env-file";
 
-/**
- * Strict shell-identifier shape. Used for dotenv keys we accept into
- * `Bun.env` — those should be referenceable as `$NAME` from POSIX shells,
- * so we reject anything outside `[A-Za-z_][A-Za-z0-9_]*`.
- */
-export function isValidEnvName(name: string): boolean {
-	return ENV_NAME_RE.test(name);
-}
-
-function stripInlineShellComment(value: string): string {
-	let quote: '"' | "'" | undefined;
-	for (let i = 0; i < value.length; i++) {
-		const char = value[i];
-		if (char === "\\") {
-			i++;
-			continue;
-		}
-		if ((char === '"' || char === "'") && (!quote || quote === char)) {
-			quote = quote ? undefined : char;
-			continue;
-		}
-		if (char === "#" && !quote && (i === 0 || /\s/.test(value[i - 1] ?? ""))) {
-			return value.slice(0, i).trimEnd();
-		}
-	}
-	return value.trimEnd();
-}
-
-/**
- * Parses simple POSIX shell environment assignments from files such as
- * ~/.zshrc without executing user shell code. Supports `export KEY=value` and
- * `KEY=value`, including single/double quoted literal values. Dynamic shell
- * expressions are intentionally ignored because evaluating startup files would
- * run arbitrary code during CLI startup.
- */
-export function parseShellEnvFile(filePath: string): Record<string, string> {
-	const result: Record<string, string> = {};
-	try {
-		const content = fs.readFileSync(filePath, "utf-8");
-		for (const line of content.split("\n")) {
-			const trimmed = line.trim();
-			if (!trimmed || trimmed.startsWith("#")) continue;
-
-			const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)$/.exec(trimmed);
-			if (!match) continue;
-
-			const key = match[1];
-			if (!isValidEnvName(key)) continue;
-
-			let value = stripInlineShellComment(match[2] ?? "").trim();
-			if (value.endsWith(";")) value = value.slice(0, -1).trimEnd();
-			if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
-				value = value.slice(1, -1);
-			}
-			if (!isSafeEnvValue(value)) continue;
-			if (/[$`]/.test(value)) continue;
-
-			result[key] = value;
-		}
-	} catch {
-		// File doesn't exist or can't be read - return empty result
-	}
-
-	return result;
-}
-
-/**
- * Parses a .env file synchronously and extracts key-value string pairs.
- * Ignores lines that are empty or start with '#'. Trims whitespace.
- * Allows values to be quoted with single or double quotes.
- * Returns an object of key-value pairs.
- */
-export function parseEnvFile(filePath: string): Record<string, string> {
-	const result: Record<string, string> = {};
-	try {
-		const content = fs.readFileSync(filePath, "utf-8");
-		for (const line of content.split("\n")) {
-			const trimmed = line.trim();
-			// Skip comments and blank lines
-			if (!trimmed || trimmed.startsWith("#")) continue;
-
-			const eqIndex = trimmed.indexOf("=");
-			if (eqIndex === -1) continue;
-
-			const key = trimmed.slice(0, eqIndex).trim();
-			if (!isValidEnvName(key)) continue;
-
-			let value = trimmed.slice(eqIndex + 1).trim();
-
-			// Remove surrounding quotes (" or ')
-			if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
-				value = value.slice(1, -1);
-			}
-			if (!isSafeEnvValue(value)) continue;
-
-			result[key] = value;
-		}
-	} catch {
-		// File doesn't exist or can't be read - return empty result
-	}
-
-	return result;
-}
+// Re-exported so the public surface of this module is unchanged.
+export { isValidEnvName, parseEnvFile, parseShellEnvFile } from "./env-file";
 
 function resolveFileEnvValue(file: Record<string, string>, name: string): string | undefined {
 	if (!isSafeEnvName(name)) return undefined;

package/src/postmortem.ts

@@ -229,11 +229,21 @@ function redactCrashSecrets(text: string): string {
 	redacted = redacted.replace(/\b(?:Bearer|Basic|Token)\s+[A-Za-z0-9._~+/=-]{8,}/gi, "«redacted-auth»");
 	redacted = redacted.replace(/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g, "«redacted-jwt»");
 	redacted = redacted.replace(/\bsk-[A-Za-z0-9_-]{8,}\b/g, "«redacted-api-key»");
+	// `gh[opsur]_` covers the classic PAT/OAuth/server/user/refresh prefixes;
+	// fine-grained PATs use an entirely different `github_pat_` prefix and would
+	// otherwise survive into a log the module keeps indefinitely.
 	redacted = redacted.replace(/\bgh[opsur]_[A-Za-z0-9]{16,}\b/g, "«redacted-github-token»");
+	redacted = redacted.replace(/\bgithub_pat_[A-Za-z0-9_]{20,}\b/g, "«redacted-github-token»");
 	redacted = redacted.replace(/\bxox[baprs]-[A-Za-z0-9-]{8,}\b/g, "«redacted-slack-token»");
-	redacted = redacted.replace(/\bAKIA[0-9A-Z]{16}\b/g, "«redacted-aws-key»");
+	// AKIA is the long-term access key id; ASIA is the temporary/STS one, which is
+	// the shape that actually shows up in a crashed request. The id alone is not
+	// the credential: an STS payload carries `SecretAccessKey` and `SessionToken`
+	// alongside it, so the labeled-value rule below must name both. `secret_key`
+	// does not match `SecretAccessKey` (the canonical field has `Access` in the
+	// middle), and `access_token` does not match `SessionToken`.
+	redacted = redacted.replace(/\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g, "«redacted-aws-key»");
 	redacted = redacted.replace(
-		/(["']?(?:api[_-]?key|apikey|access[_-]?token|refresh[_-]?token|id[_-]?token|client[_-]?secret|secret[_-]?key|password|passwd|authorization)["']?\s*[=:]\s*["']?)[^\s"',;}\]]{8,}/gi,
+		/(?<![A-Za-z0-9_])(["']?(?:api[_-]?key|apikey|access[_-]?token|refresh[_-]?token|id[_-]?token|session[_-]?token|client[_-]?secret|secret[_-]?key|secret[_-]?access[_-]?key|password|passwd|authorization)["']?\s*[=:]\s*["']?)[^\s"',;}\]]{8,}/gi,
 		"$1«redacted»",
 	);
 	return redacted;

package/src/procmgr.ts

@@ -2,7 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { Process, ProcessStatus } from "@gajae-code/natives";
 import type { Subprocess } from "bun";
-import { $env, filterProcessEnv } from "./env";
+import { $pickCredentialEnv, $pickflag, filterProcessEnv } from "./env";
 import { $which } from "./which";
 
 export interface ShellConfig {
@@ -41,9 +41,13 @@ function isExecutable(path: string): boolean {
 
 /**
  * Build the spawn environment (cached).
+ *
+ * `CI=true` is injected unless the documented `GJC_BASH_NO_CI` (or its legacy
+ * `PI_BASH_NO_CI` / `CLAUDE_BASH_NO_CI` aliases) is set to a canonical truthy
+ * flag value.
  */
 function buildSpawnEnv(shell: string): Record<string, string> {
-	const noCI = $env.PI_BASH_NO_CI || $env.CLAUDE_BASH_NO_CI;
+	const noCI = $pickflag("GJC_BASH_NO_CI", "PI_BASH_NO_CI", "CLAUDE_BASH_NO_CI");
 	const inherited = filterProcessEnv(Bun.env);
 	delete inherited.GJC_SESSION_FILE;
 	delete inherited.GJC_MANAGED_OWNER_TRANSCRIPT_PATH;
@@ -60,18 +64,30 @@ function buildSpawnEnv(shell: string): Record<string, string> {
 
 /**
  * Get shell args, optionally including login shell flag.
- * Supports PI_BASH_NO_LOGIN and ANTHROPIC_MODEL_BASH_NO_LOGIN to skip -l.
+ *
+ * Honors the documented `GJC_BASH_NO_LOGIN` first, with `PI_BASH_NO_LOGIN` and
+ * `CLAUDE_BASH_NO_LOGIN` as legacy aliases. Boolean-like values follow the
+ * canonical flag contract (`1`/`Y`/`TRUE`/`YES`/`ON`, case-insensitive), so an
+ * explicit `GJC_BASH_NO_LOGIN=0` keeps the login shell even when a legacy alias
+ * is set to a truthy value.
  */
 function getShellArgs(): string[] {
-	const noLogin = $env.PI_BASH_NO_LOGIN || $env.CLAUDE_BASH_NO_LOGIN;
+	const noLogin = $pickflag("GJC_BASH_NO_LOGIN", "PI_BASH_NO_LOGIN", "CLAUDE_BASH_NO_LOGIN");
 	return noLogin ? ["-c"] : ["-l", "-c"];
 }
 
 /**
  * Get shell prefix for wrapping commands (profilers, strace, etc.).
+ *
+ * Resolved from trusted sources only. The prefix is interpolated ahead of every
+ * bash command (`${prefix} ${command}`) and executed through the shell, so it is
+ * an arbitrary-command-execution surface. `$env` merges the caller's
+ * `cwd/.env`, which means repository content could otherwise set it; resolution
+ * therefore goes through the non-project resolver (launching shell plus
+ * GJC/user-owned `.env` files), matching how provider credentials are resolved.
  */
 function getShellPrefix(): string | undefined {
-	return $env.PI_SHELL_PREFIX || $env.CLAUDE_CODE_SHELL_PREFIX;
+	return $pickCredentialEnv("PI_SHELL_PREFIX", "CLAUDE_CODE_SHELL_PREFIX");
 }
 
 /**
@@ -187,6 +203,15 @@ export function getShellConfig(customShellPath?: string): ShellConfig {
 	return cachedShellConfig;
 }
 
+/**
+ * Clear the memoized shell configuration so the next {@link getShellConfig}
+ * call re-resolves the shell and re-reads the environment (shell selection and
+ * the bash CI/login flags). Primarily for tests that vary those inputs.
+ */
+export function resetShellConfigCache(): void {
+	cachedShellConfig = null;
+}
+
 /**
  * Check if a process is running.
  */