@sayknow-cli/utils 0.4.7 → 0.5.0

package/dist/types/dirs.d.ts

@@ -1,8 +1,9 @@
 /**
  * Centralized path helpers for sayknow-cli config directories.
  *
- * Uses PI_CONFIG_DIR (default ".skc") for the config root and
- * PI_CODING_AGENT_DIR to override the agent directory.
+ * Uses SKC_CONFIG_DIR (legacy alias PI_CONFIG_DIR, default ".skc") for the
+ * config root and SKC_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. ".skc" or PI_CONFIG_DIR override). */
 export declare function getConfigDirName(): string;
 /** Get the config agent directory name relative to home (e.g. ".skc/agent" or PI_CONFIG_DIR + "/agent"). */
 export declare function getConfigAgentDirName(): string;

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.
@@ -66,3 +46,7 @@ export declare function isBunTestRuntime(): boolean;
  */
 export declare function isCompiledBinary(): boolean;
 export declare function $flag(name: string, def?: boolean): boolean;
+/** Resolve the first flag among keys that has a set value (SKC-first, PI fallback). Matches $flag semantics per key. */
+export declare function $pickflag(...keys: string[]): boolean;
+/** Resolve the first positive integer among keys, else defaultValue (SKC-first). Set-but-invalid keys are skipped. */
+export declare function $pickenvpos(keys: string[], defaultValue: number): number;

package/dist/types/postmortem.d.ts

@@ -8,6 +8,31 @@ export declare enum Reason {
     UNHANDLED_REJECTION = "unhandled_rejection",// Unhandled promise rejection
     MANUAL = "manual"
 }
+/** Cap for the durable crash log; it is reset past this so a crash loop cannot fill the disk. */
+export declare const CRASH_LOG_MAX_BYTES: number;
+/**
+ * Per-record budget so a single oversized error body cannot bypass the file
+ * cap: every persisted record is truncated to this many bytes (UTF-8 safe,
+ * with a marker) before the append/reset decision.
+ */
+export declare const CRASH_RECORD_MAX_BYTES: number;
+/**
+ * Append a fatal-crash record to the dedicated, rotation-immune crash log
+ * (`~/.skc/agent/skc-crash.log`).
+ *
+ * The daily logger file is gzip-archived at date rollover by every skc process
+ * independently; that shared-archive race can truncate a day's log to an empty
+ * `.gz`, destroying the `logger.error` crash record written here. This
+ * append-only file is never rotated, so a crash stays diagnosable regardless.
+ *
+ * Fully defensive: it never throws (a failing crash writer must not mask the
+ * original fatal) and uses synchronous IO so the record lands before
+ * `process.exit`. Returns the path written, or `undefined` on failure.
+ */
+export declare function recordFatalCrash(label: string, reason: unknown, options?: {
+    path?: string;
+    now?: Date;
+}): string | undefined;
 /**
  * Register a process cleanup callback, to be run on shutdown, signal, or fatal error.
  *

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/dist/types/stream.d.ts

@@ -17,7 +17,11 @@ export declare function readJsonl<T>(stream: ReadableStream<Uint8Array>, signal?
  * ```
  */
 export type SseEventObserver = (event: ServerSentEvent) => void;
-export declare function readSseJson<T>(stream: ReadableStream<Uint8Array>, signal?: AbortSignal, onEvent?: SseEventObserver): AsyncGenerator<T>;
+export interface SseReadOptions {
+    maxEventBytes?: number;
+    maxTotalBytes?: number;
+}
+export declare function readSseJson<T>(stream: ReadableStream<Uint8Array>, signal?: AbortSignal, onEvent?: SseEventObserver, options?: SseReadOptions): AsyncGenerator<T>;
 /**
  * A single Server-Sent Event dispatched on a blank-line boundary.
  *
@@ -53,7 +57,7 @@ export interface ServerSentEvent {
  * }
  * ```
  */
-export declare function readSseEvents(stream: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<ServerSentEvent>;
+export declare function readSseEvents(stream: ReadableStream<Uint8Array>, signal?: AbortSignal, options?: SseReadOptions): AsyncGenerator<ServerSentEvent>;
 /**
  * Parse a complete JSONL string, skipping malformed lines instead of throwing.
  *

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@sayknow-cli/utils",
-	"version": "0.4.7",
+	"version": "0.5.0",
 	"description": "Shared utilities for pi packages",
 	"homepage": "https://sayknow-cli.com",
 	"author": "jaybeyond",
@@ -31,7 +31,7 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@sayknow-cli/natives": "0.4.7",
+		"@sayknow-cli/natives": "0.5.0",
 		"beautiful-mermaid": "^1.1.3",
 		"handlebars": "^4.7.9",
 		"winston": "^3.19.0",

package/src/cli.ts

@@ -211,8 +211,11 @@ export abstract class Command {
 				if (raw === undefined || typeof raw === "boolean") {
 					flags[name] = desc.default ?? undefined;
 				} else {
-					const n = Number.parseInt(raw as string, 10);
-					if (Number.isNaN(n)) {
+					if (typeof raw !== "string" || !/^-?\d+$/.test(raw)) {
+						throw new CliParseError(`Expected integer for --${name}, got "${String(raw)}"`);
+					}
+					const n = Number(raw);
+					if (!Number.isSafeInteger(n)) {
 						throw new CliParseError(`Expected integer for --${name}, got "${raw}"`);
 					}
 					flags[name] = n;
@@ -267,6 +270,12 @@ export abstract class Command {
 			}
 		}
 
+		if (strict && posIdx < positionals.length) {
+			const unexpected = positionals.slice(posIdx);
+			const rendered = unexpected.map(value => JSON.stringify(value)).join(", ");
+			throw new CliParseError(`Unexpected argument${unexpected.length === 1 ? "" : "s"}: ${rendered}`);
+		}
+
 		return { flags, args, argv: positionals } as never;
 	}
 }

package/src/dirs.ts

@@ -1,8 +1,9 @@
 /**
  * Centralized path helpers for sayknow-cli config directories.
  *
- * Uses PI_CONFIG_DIR (default ".skc") for the config root and
- * PI_CODING_AGENT_DIR to override the agent directory.
+ * Uses SKC_CONFIG_DIR (legacy alias PI_CONFIG_DIR, default ".skc") for the
+ * config root and SKC_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. "skc") */
 export const APP_NAME: string = "skc";
@@ -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. ".skc" 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
+ * `SKC_CODING_AGENT_DIR` is treated.
+ */
+function trustedConfigDirName(name: "SKC_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.SKC_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("SKC_CONFIG_DIR")) ??
+		sanitizeConfigDirName(trustedConfigDirName("PI_CONFIG_DIR")) ??
+		CONFIG_DIR_NAME
+	);
 }
 
 /** Get the config agent directory name relative to home (e.g. ".skc/agent" or PI_CONFIG_DIR + "/agent"). */
@@ -248,7 +298,43 @@ class DirResolver {
 	}
 }
 
-let dirs = new DirResolver(process.env.SKC_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: "SKC_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 `SKC_` spelling here split
+ * the agent directory in two: `skc gc` operated on the aliased directory while
+ * everything reaching `getAgentDir()` stayed on the default.
+ */
+function trustedAgentDirOverride(): string | undefined {
+	return trustedAgentDirOverrideFor("SKC_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

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;
@@ -279,3 +177,23 @@ export function $flag(name: string, def: boolean = false): boolean {
 	// would silently read as false while only `FOO=TRUE`/`FOO=1` worked.
 	return TRUTHY[value.toUpperCase()] === true;
 }
+
+/** Resolve the first flag among keys that has a set value (SKC-first, PI fallback). Matches $flag semantics per key. */
+export function $pickflag(...keys: string[]): boolean {
+	for (const key of keys) {
+		const value = $env[key]?.trim();
+		if (value) return TRUTHY[value.toUpperCase()] === true;
+	}
+	return false;
+}
+
+/** Resolve the first positive integer among keys, else defaultValue (SKC-first). Set-but-invalid keys are skipped. */
+export function $pickenvpos(keys: string[], defaultValue: number): number {
+	for (const key of keys) {
+		const raw = $env[key]?.trim();
+		if (!raw) continue;
+		const parsed = Number.parseInt(raw, 10);
+		if (!Number.isNaN(parsed) && parsed > 0) return parsed;
+	}
+	return defaultValue;
+}

package/src/format.ts

@@ -9,7 +9,9 @@ const DAY = 24 * HOUR;
  */
 export function formatDuration(ms: number): string {
 	if (ms < SEC) return `${ms}ms`;
-	if (ms < MIN) return `${(ms / SEC).toFixed(1)}s`;
+	// Truncate below 60.0s instead of rounding up into the next unit (the minute
+	// branch below), mirroring roundBelow/formatByteUnit: e.g. 59_999ms -> "59.9s".
+	if (ms < MIN) return `${(roundBelow(ms / 100, 600) / 10).toFixed(1)}s`;
 	if (ms < HOUR) {
 		const mins = Math.floor(ms / MIN);
 		const secs = Math.floor((ms % MIN) / SEC);
@@ -59,13 +61,21 @@ export function formatBytes(bytes: number): string {
 	if (bytes < 1024) return `${bytes}B`;
 	if (bytes < 1024 * 1024) return `${formatByteUnit(bytes, 1024)}KB`;
 	if (bytes < 1024 * 1024 * 1024) return `${formatByteUnit(bytes, 1024 * 1024)}MB`;
-	return `${formatByteUnit(bytes, 1024 * 1024 * 1024)}GB`;
+	// The GB branch is terminal (no larger unit), so it must not clamp below the
+	// next-unit boundary the way KB/MB do; clamping here reports every value >=
+	// 1 TiB as "1023.9GB" (e.g. 2 TiB -> "1023.9GB" instead of "2048.0GB").
+	return `${formatByteUnit(bytes, 1024 * 1024 * 1024, false)}GB`;
 }
 
-/** Format bytes to 1 decimal without rounding up into the next byte unit. */
-function formatByteUnit(bytes: number, unit: number): string {
-	const tenths = Math.min(Math.round((bytes / unit) * 10), 1024 * 10 - 1);
-	return (tenths / 10).toFixed(1);
+/**
+ * Format bytes to 1 decimal. Intermediate units (KB/MB) clamp just below the
+ * next-unit boundary so a value like 1023.95 KB never rounds up to "1024.0KB";
+ * the terminal GB unit passes `clampToNextUnit: false` because it has no next
+ * unit to protect against.
+ */
+function formatByteUnit(bytes: number, unit: number, clampToNextUnit = true): string {
+	const tenths = Math.round((bytes / unit) * 10);
+	return ((clampToNextUnit ? Math.min(tenths, 1024 * 10 - 1) : tenths) / 10).toFixed(1);
 }
 
 /**

package/src/frontmatter.ts

@@ -124,18 +124,30 @@ export function parseFrontmatter(
 	const loc = location ?? source;
 	const frontmatter: Record<string, unknown> = { ...fallback };
 
-	const normalized = normalize ? stripHtmlComments(content.replace(/\r\n?/g, "\n")) : content;
-	if (!normalized.startsWith("---")) {
+	// Normalize away a leading UTF-8 BOM and CRLF line endings before matching so
+	// a BOM-prefixed but otherwise valid document is still recognized as
+	// frontmatter (BOM-prefixed Markdown is common on Windows-authored files).
+	const normalized = normalize ? stripHtmlComments(content.replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n")) : content;
+	// A frontmatter block opens with a line that is exactly `---` (trailing
+	// spaces/tabs allowed). A bare `----` banner or a `--- text` heading is not
+	// an opener, so a document without frontmatter keeps its body intact rather
+	// than having content silently consumed by the fixed-offset slicing below.
+	const open = normalized.match(/^---[ \t]*(?:\n|$)/);
+	if (!open) {
 		return { frontmatter, body: normalized };
 	}
 
-	const endIndex = normalized.indexOf("\n---", 3);
-	if (endIndex === -1) {
+	// The block closes at the next line that is exactly `---`. Searching from the
+	// end of the opening `---` (offset 3, not the whole opener) keeps an empty
+	// block (`---\n---`) matching as empty frontmatter.
+	const afterOpen = normalized.slice(3);
+	const close = afterOpen.match(/\n---[ \t]*(?:\n|$)/);
+	if (!close || close.index === undefined) {
 		return { frontmatter, body: normalized };
 	}
 
-	const metadata = normalized.slice(4, endIndex);
-	const body = normalized.slice(endIndex + 4).trim();
+	const metadata = afterOpen.slice(open[0].length - 3, close.index);
+	const body = afterOpen.slice(close.index + close[0].length).trim();
 
 	try {
 		// Replace tabs with spaces for YAML compatibility, use failsafe mode for robustness

package/src/logger.ts

@@ -410,7 +410,10 @@ function printModuleLoadSummary(loads: Span[], depth: number, lines: string[]):
 	}
 	const wall = unionEnd > unionStart ? unionEnd - unionStart : 0;
 	lines.push(`${childIndent}(modules): ${loads.length} loaded, wall ${fmtMs(wall)}, sum ${fmtMs(totalSelf)}`);
-	const showAll = process.env.PI_TIMING === "full";
+	// Resolve SKC-first with PI fallback inline (no ./env import) so this
+	// foundational logger stays off the env module's dependency graph, which the
+	// tab-worker native-free runtime contract (issue-2598-repro) walks.
+	const showAll = (process.env.SKC_TIMING?.trim() || process.env.PI_TIMING?.trim()) === "full";
 	const sorted = [...loads].sort((a, b) => durationOf(b) - durationOf(a));
 	const visible = showAll ? sorted : sorted.slice(0, MODULE_LOAD_VERBOSE_TOP);
 	for (const span of visible) {

package/src/postmortem.ts

@@ -5,9 +5,12 @@
  * 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 * as fs from "node:fs";
 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 { getCrashLogPath } from "./dirs";
 import * as logger from "./logger";
 import { safeStderrWrite } from "./safe-stderr";
 
@@ -204,6 +207,104 @@ function formatFatalError(label: string, err: Error): string {
 	const formattedStack = stackLines.length > 0 ? `\n${stackLines.join("\n")}` : "";
 	return `\n[${label}] ${name}: ${message}${formattedStack}\n`;
 }
+/** Cap for the durable crash log; it is reset past this so a crash loop cannot fill the disk. */
+export const CRASH_LOG_MAX_BYTES = 512 * 1024;
+/**
+ * Per-record budget so a single oversized error body cannot bypass the file
+ * cap: every persisted record is truncated to this many bytes (UTF-8 safe,
+ * with a marker) before the append/reset decision.
+ */
+export const CRASH_RECORD_MAX_BYTES = 64 * 1024;
+const CRASH_RECORD_TRUNCATION_MARKER = "\n… [crash record truncated]\n\n";
+
+/**
+ * Best-effort scrub of credential material from a crash record before it is
+ * persisted indefinitely. Covers bearer/basic-style headers, key=value or
+ * JSON key forms of common credential names, and well-known vendor token
+ * shapes. Normal messages and stack frames are untouched; matches are
+ * replaced in place so surrounding diagnostic context survives.
+ */
+function redactCrashSecrets(text: string): string {
+	let redacted = text;
+	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»");
+	redacted = redacted.replace(/\bgh[opsur]_[A-Za-z0-9]{16,}\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»");
+	redacted = redacted.replace(
+		/(["']?(?:api[_-]?key|apikey|access[_-]?token|refresh[_-]?token|id[_-]?token|client[_-]?secret|secret[_-]?key|password|passwd|authorization)["']?\s*[=:]\s*["']?)[^\s"',;}\]]{8,}/gi,
+		"$1«redacted»",
+	);
+	return redacted;
+}
+
+/**
+ * Bound one record to CRASH_RECORD_MAX_BYTES without splitting a UTF-8
+ * sequence. Keeps the header (timestamp/label/message) at the front, where
+ * the diagnostic value is highest.
+ */
+function boundCrashRecord(report: string): string {
+	if (Buffer.byteLength(report, "utf8") <= CRASH_RECORD_MAX_BYTES) return report;
+	const bytes = Buffer.from(report, "utf8");
+	const budget = CRASH_RECORD_MAX_BYTES - Buffer.byteLength(CRASH_RECORD_TRUNCATION_MARKER, "utf8");
+	let end = budget;
+	// Drop trailing continuation bytes of a truncated multi-byte sequence.
+	while (end > 0 && (bytes[end - 1] & 0xc0) === 0x80) end--;
+	// Drop the now-incomplete lead byte, if any.
+	if (end > 0 && bytes[end - 1] >= 0xc0) end--;
+	return bytes.subarray(0, end).toString("utf8") + CRASH_RECORD_TRUNCATION_MARKER;
+}
+
+/**
+ * Append a fatal-crash record to the dedicated, rotation-immune crash log
+ * (`~/.skc/agent/skc-crash.log`).
+ *
+ * The daily logger file is gzip-archived at date rollover by every skc process
+ * independently; that shared-archive race can truncate a day's log to an empty
+ * `.gz`, destroying the `logger.error` crash record written here. This
+ * append-only file is never rotated, so a crash stays diagnosable regardless.
+ *
+ * Fully defensive: it never throws (a failing crash writer must not mask the
+ * original fatal) and uses synchronous IO so the record lands before
+ * `process.exit`. Returns the path written, or `undefined` on failure.
+ */
+export function recordFatalCrash(
+	label: string,
+	reason: unknown,
+	options: { path?: string; now?: Date } = {},
+): string | undefined {
+	try {
+		const err = errorForDiagnostic(reason);
+		const target = options.path ?? getCrashLogPath();
+		const now = options.now ?? new Date();
+		const report = boundCrashRecord(
+			`${now.toISOString()} pid=${process.pid} [${label}] ` +
+				`${err.name || "Error"}: ${redactCrashSecrets(err.message || "(no message)")}\n` +
+				`${redactCrashSecrets(err.stack ?? "")}\n\n`,
+		);
+		fs.mkdirSync(path.dirname(target), { recursive: true });
+		let existingSize = 0;
+		try {
+			existingSize = fs.statSync(target).size;
+		} catch {}
+		// Reset (rather than append) when the file would exceed the cap so the
+		// newest crash is always retained without unbounded growth. Every record
+		// is individually bounded above, so no single crash can bypass the cap.
+		if (existingSize + Buffer.byteLength(report, "utf8") > CRASH_LOG_MAX_BYTES) {
+			fs.writeFileSync(target, report, { mode: 0o600 });
+		} else {
+			fs.appendFileSync(target, report, { mode: 0o600 });
+		}
+		// A pre-existing file may carry looser permissions; enforce owner-only.
+		try {
+			fs.chmodSync(target, 0o600);
+		} catch {}
+		return target;
+	} catch {
+		return undefined;
+	}
+}
 
 /**
  * True for terminal/pipe/disk write failures (EIO, EPIPE, EBADF, …) on the write side.
@@ -252,7 +353,12 @@ async function handleFatalError(label: string, reason: unknown, cleanupReason: R
 	ordinaryFatalStarted = true;
 	process.exitCode = 1;
 	const err = errorForDiagnostic(reason);
+	// Persist first: the rotation-immune record must land before any
+	// best-effort stderr output, so a slow or failing stderr cannot cost the
+	// crash record. Cleanup (which may itself hang or fail) runs afterwards.
+	const crashLogPath = recordFatalCrash(label, err);
 	safeStderrWrite(formatFatalError(label, err));
+	if (crashLogPath) safeStderrWrite(`[${label}] crash recorded at ${crashLogPath}\n`);
 	if (!quietShutdownStarted) {
 		logger.error(label === "Uncaught Exception" ? "Uncaught exception" : "Unhandled rejection", {
 			err,

package/src/procmgr.ts

@@ -2,7 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { Process, ProcessStatus } from "@sayknow-cli/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 `SKC_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("SKC_BASH_NO_CI", "PI_BASH_NO_CI", "CLAUDE_BASH_NO_CI");
 	const inherited = filterProcessEnv(Bun.env);
 	delete inherited.SKC_SESSION_FILE;
 	delete inherited.SKC_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 `SKC_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 `SKC_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("SKC_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
+ * SKC/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.
  */

package/src/stream.ts

@@ -125,16 +125,22 @@ class ConcatSink {
 		this.#length = 0;
 	}
 
-	*appendAndFlushLines(chunk: Uint8Array) {
+	*appendAndFlushLines(chunk: Uint8Array, maxLineBytes?: () => number) {
 		let pos = 0;
 		while (pos < chunk.length) {
 			const nl = chunk.indexOf(LF, pos);
 			if (nl === -1) {
+				if (maxLineBytes && this.#length + chunk.length - pos > maxLineBytes()) {
+					throw new Error("SSE event exceeds size limit");
+				}
 				this.append(chunk.subarray(pos));
 				return;
 			}
 			const suffix = chunk.subarray(pos, nl);
 			pos = nl + 1;
+			if (maxLineBytes && this.#length + suffix.length + 1 > maxLineBytes()) {
+				throw new Error("SSE event exceeds size limit");
+			}
 			if (this.isEmpty) {
 				yield suffix;
 			} else {
@@ -201,6 +207,11 @@ class ConcatSink {
  */
 export type SseEventObserver = (event: ServerSentEvent) => void;
 
+export interface SseReadOptions {
+	maxEventBytes?: number;
+	maxTotalBytes?: number;
+}
+
 function notifySseEventObserver(observer: SseEventObserver | undefined, event: ServerSentEvent): void {
 	if (!observer) return;
 	try {
@@ -214,8 +225,9 @@ export async function* readSseJson<T>(
 	stream: ReadableStream<Uint8Array>,
 	signal?: AbortSignal,
 	onEvent?: SseEventObserver,
+	options?: SseReadOptions,
 ): AsyncGenerator<T> {
-	for await (const sse of readSseEvents(stream, signal)) {
+	for await (const sse of readSseEvents(stream, signal, options)) {
 		notifySseEventObserver(onEvent, sse);
 		const data = sse.data;
 		if (data === "" || data === "[DONE]") {
@@ -336,14 +348,26 @@ function pushSseLine(line: Uint8Array, state: SseEventState): ServerSentEvent |
 export async function* readSseEvents(
 	stream: ReadableStream<Uint8Array>,
 	signal?: AbortSignal,
+	options?: SseReadOptions,
 ): AsyncGenerator<ServerSentEvent> {
 	const lineBuffer = new ConcatSink();
 	const state: SseEventState = { event: null, data: null, raw: [] };
 	const source = createAbortableStream(stream, signal);
+	let eventBytes = 0;
+	let totalBytes = 0;
 	try {
 		for await (const chunk of source) {
-			for (const line of lineBuffer.appendAndFlushLines(chunk)) {
+			totalBytes += chunk.length;
+			if (options?.maxTotalBytes !== undefined && totalBytes > options.maxTotalBytes) {
+				throw new Error("SSE stream exceeds size limit");
+			}
+			for (const line of lineBuffer.appendAndFlushLines(
+				chunk,
+				() => (options?.maxEventBytes ?? Infinity) - eventBytes,
+			)) {
+				eventBytes += line.length + 1;
 				const event = pushSseLine(line, state);
+				if (line.length === 0 || (line.length === 1 && line[0] === 0x0d)) eventBytes = 0;
 				if (event) yield event;
 			}
 		}