@sayknow-cli/utils 0.3.16 → 0.4.1

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@sayknow-cli/utils",
-	"version": "0.3.16",
+	"version": "0.4.1",
 	"description": "Shared utilities for pi packages",
 	"homepage": "https://sayknow-cli.com",
 	"author": "jaybeyond",
@@ -21,7 +21,7 @@
 		"streams"
 	],
 	"main": "./src/index.ts",
-	"types": "./dist/types/index.d.ts",
+	"types": "./src/index.ts",
 	"scripts": {
 		"check": "biome check . && bun run check:types",
 		"check:types": "tsc -p tsconfig.json --noEmit",
@@ -31,7 +31,7 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@sayknow-cli/natives": "0.3.16",
+		"@sayknow-cli/natives": "0.4.1",
 		"beautiful-mermaid": "^1.1.3",
 		"handlebars": "^4.7.9",
 		"winston": "^3.19.0",
@@ -44,16 +44,15 @@
 		"bun": ">=1.3.14"
 	},
 	"files": [
-		"src",
-		"dist/types"
+		"src"
 	],
 	"exports": {
 		".": {
-			"types": "./dist/types/index.d.ts",
+			"types": "./src/index.ts",
 			"import": "./src/index.ts"
 		},
 		"./*": {
-			"types": "./dist/types/*.d.ts",
+			"types": "./src/*.ts",
 			"import": "./src/*.ts"
 		},
 		"./*.js": "./src/*.ts"

package/src/dirs.ts

@@ -108,16 +108,22 @@ export function resolveEquivalentPath(inputPath: string): string {
 	}
 }
 
-export function normalizePathForComparison(inputPath: string): string {
-	const resolvedPath = resolveEquivalentPath(inputPath);
-	return process.platform === "win32" ? resolvedPath.toLowerCase() : resolvedPath;
+export function normalizePathForComparison(inputPath: string, platform: NodeJS.Platform = process.platform): string {
+	const pathApi = platform === "win32" ? path.win32 : path;
+	const resolvedPath = platform === process.platform ? resolveEquivalentPath(inputPath) : pathApi.resolve(inputPath);
+	return platform === "win32" ? resolvedPath.toLowerCase() : resolvedPath;
+}
+
+/** Return whether a relative path crosses above its root or is unexpectedly absolute. */
+export function relativePathEscapesRoot(relative: string): boolean {
+	return relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative);
 }
 
 export function pathIsWithin(root: string, candidate: string): boolean {
 	const normalizedRoot = normalizePathForComparison(root);
 	const normalizedCandidate = normalizePathForComparison(candidate);
 	const relative = path.relative(normalizedRoot, normalizedCandidate);
-	return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+	return !relativePathEscapesRoot(relative);
 }
 
 export function relativePathWithinRoot(root: string, candidate: string): string | null {

package/src/postmortem.ts

@@ -55,7 +55,11 @@ function runCleanup(reason: Reason, options: CleanupOptions = {}): Promise<void>
 			cleanupStage = "running";
 			break;
 		case "running":
-			if (reason !== Reason.EXIT && !shouldSuppressCleanupLogging(quiet)) {
+			// Exit-bound waiters (signals, fatals, quit) legitimately join the
+			// in-flight cleanup via `cleanupPromise`; only a genuine manual
+			// recursion (a cleanup callback calling cleanup()) is a bug worth a
+			// diagnostic.
+			if (reason === Reason.MANUAL && !shouldSuppressCleanupLogging(quiet)) {
 				logger.error("Cleanup invoked recursively", { stack: new Error().stack });
 			}
 			return Promise.resolve();
@@ -90,9 +94,65 @@ function runCleanup(reason: Reason, options: CleanupOptions = {}): Promise<void>
 	return promise;
 }
 
-async function runCleanupAndWait(reason: Reason, options: CleanupOptions = {}): Promise<void> {
+/**
+ * Finite cleanup-liveness contract for every exit-bound wait.
+ *
+ * Governed waits: signal handlers (SIGINT/SIGTERM/SIGHUP), fatal handlers
+ * (uncaught exception / unhandled rejection), the quiet stdout-EPIPE exit, and
+ * `quit()`. Each waits at most `resolveCleanupDeadlineMs()` for the shared
+ * in-flight cleanup before exiting with its own unchanged exit code (130/143/
+ * 129, 1 for fatals, BROKEN_PIPE_EXIT_CODE, or quit's `code`).
+ *
+ * Ungoverned: `cleanup()` (Reason.MANUAL without exit) is caller-owned and
+ * unbounded, and Reason.EXIT stays fire-and-forget (exit is imminent).
+ *
+ * On expiry the stage is forced to "complete" so late re-entries no-op, a
+ * single diagnostic goes to stderr and the error log (suppressed during quiet
+ * broken-pipe shutdown), and late callback settlement is ignored — rejections
+ * were already routed through Promise.allSettled, so none can become unhandled.
+ *
+ * The deadline defaults to 5000 ms and can be overridden with
+ * `SKC_CLEANUP_DEADLINE_MS` (finite values >= 0; anything else falls back to
+ * the default).
+ */
+const DEFAULT_CLEANUP_DEADLINE_MS = 5_000;
+
+function resolveCleanupDeadlineMs(): number {
+	const raw = process.env.SKC_CLEANUP_DEADLINE_MS;
+	if (raw === undefined || raw.trim() === "") return DEFAULT_CLEANUP_DEADLINE_MS;
+	const parsed = Number(raw);
+	if (!Number.isFinite(parsed) || parsed < 0) return DEFAULT_CLEANUP_DEADLINE_MS;
+	return parsed;
+}
+
+async function awaitCleanupWithDeadline(reason: Reason, options: CleanupOptions = {}): Promise<void> {
+	const pending = cleanupPromise;
+	if (!pending || cleanupStage === "complete") return;
+	const deadlineMs = resolveCleanupDeadlineMs();
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const timedOut = await Promise.race([
+		pending.then(() => false),
+		new Promise<boolean>(resolve => {
+			// Deliberately referenced: the timer is also the liveness floor that
+			// keeps the process alive until the bounded wait settles, so an
+			// otherwise-empty event loop cannot exit 0 underneath a governed wait.
+			timer = setTimeout(() => resolve(true), deadlineMs);
+		}),
+	]);
+	if (timer) clearTimeout(timer);
+	if (!timedOut) return;
+	// Force the terminal stage so late settlement and re-entries are no-ops.
+	cleanupStage = "complete";
+	if (!shouldSuppressCleanupLogging(options.quiet === true)) {
+		const diagnostic = `[postmortem] cleanup deadline (${deadlineMs}ms) expired for ${reason}; exiting without waiting for remaining callbacks.\n`;
+		safeStderrWrite(diagnostic);
+		logger.error("Cleanup deadline expired", { reason, deadlineMs });
+	}
+}
+
+async function runCleanupBounded(reason: Reason, options: CleanupOptions = {}): Promise<void> {
 	void runCleanup(reason, options);
-	await (cleanupPromise ?? Promise.resolve());
+	await awaitCleanupWithDeadline(reason, options);
 }
 
 function installProcessStdoutWriteClassifier(): void {
@@ -169,7 +229,7 @@ async function exitQuietlyForAttributableStdoutEpipe(reason: Reason): Promise<vo
 	quietShutdownStarted = true;
 	// Set the observable status before cleanup can await or trigger another error.
 	process.exitCode = BROKEN_PIPE_EXIT_CODE;
-	await runCleanupAndWait(reason, { quiet: true });
+	await runCleanupBounded(reason, { quiet: true });
 	// An ordinary fatal that arrived during quiet cleanup takes precedence.
 	if (process.exitCode === BROKEN_PIPE_EXIT_CODE) process.exit(BROKEN_PIPE_EXIT_CODE);
 }
@@ -199,7 +259,7 @@ async function handleFatalError(label: string, reason: unknown, cleanupReason: R
 			stack: err.stack,
 		});
 	}
-	await runCleanupAndWait(cleanupReason);
+	await runCleanupBounded(cleanupReason);
 	process.exit(1);
 }
 
@@ -207,7 +267,7 @@ if (isMainThread) {
 	installProcessStdoutWriteClassifier();
 	process
 		.on("SIGINT", async () => {
-			await runCleanupAndWait(Reason.SIGINT);
+			await runCleanupBounded(Reason.SIGINT);
 			process.exit(130); // 128 + SIGINT (2)
 		})
 		.on("SIGUSR1", () => {
@@ -227,11 +287,11 @@ if (isMainThread) {
 			void runCleanup(Reason.EXIT); // fire and forget (exit imminent)
 		})
 		.on("SIGTERM", async () => {
-			await runCleanupAndWait(Reason.SIGTERM);
+			await runCleanupBounded(Reason.SIGTERM);
 			process.exit(143); // 128 + SIGTERM (15)
 		})
 		.on("SIGHUP", async () => {
-			await runCleanupAndWait(Reason.SIGHUP);
+			await runCleanupBounded(Reason.SIGHUP);
 			process.exit(129); // 128 + SIGHUP (1)
 		});
 } else {
@@ -322,7 +382,7 @@ export async function quit(code: number = 0): Promise<void> {
 	}
 
 	const exitAfterCleanup = async (): Promise<void> => {
-		await completion;
+		await awaitCleanupWithDeadline(Reason.MANUAL);
 		if (process.stdout.writableLength > 0) {
 			const { promise, resolve } = Promise.withResolvers<void>();
 			process.stdout.once("drain", resolve);

package/src/procmgr.ts

@@ -44,8 +44,11 @@ function isExecutable(path: string): boolean {
  */
 function buildSpawnEnv(shell: string): Record<string, string> {
 	const noCI = $env.PI_BASH_NO_CI || $env.CLAUDE_BASH_NO_CI;
+	const inherited = filterProcessEnv(Bun.env);
+	delete inherited.SKC_SESSION_FILE;
+	delete inherited.SKC_MANAGED_OWNER_TRANSCRIPT_PATH;
 	return {
-		...filterProcessEnv(Bun.env),
+		...inherited,
 		SHELL: shell,
 		GIT_EDITOR: "true",
 		GPG_TTY: "not a tty",

package/dist/types/abortable.d.ts

@@ -1,27 +0,0 @@
-export declare class AbortError extends Error {
-    constructor(signal: AbortSignal);
-}
-/**
- * Creates an abortable stream from a given stream and signal.
- *
- * @param stream - The stream to make abortable
- * @param signal - The signal to abort the stream
- * @returns The abortable stream
- */
-export declare function createAbortableStream<T>(stream: ReadableStream<T>, signal?: AbortSignal): ReadableStream<T>;
-/**
- * Runs a promise-returning function (`pr`). If the given AbortSignal is aborted before or during
- * execution, the promise is rejected with a standard error.
- *
- * @param signal - Optional AbortSignal to cancel the operation
- * @param pr - Function returning a promise to run
- * @returns Promise resolving as `pr` would, or rejecting on abort
- */
-export declare function untilAborted<T>(signal: AbortSignal | undefined | null, pr: Promise<T> | (() => Promise<T>)): Promise<T>;
-/**
- * Memoizes a function with no arguments, calling it once and caching the result.
- *
- * @param fn - Function to be called once
- * @returns A function that returns the cached result of `fn`
- */
-export declare function once<T>(fn: () => T): () => T;

package/dist/types/async.d.ts

@@ -1,6 +0,0 @@
-/**
- * Wrap a promise with a timeout and optional abort signal.
- * Rejects with the given message if the timeout fires first.
- * Cleans up all listeners on settlement.
- */
-export declare function withTimeout<T>(promise: Promise<T>, ms: number, message: string, signal?: AbortSignal): Promise<T>;

package/dist/types/broken-pipe.d.ts

@@ -1,27 +0,0 @@
-/**
- * True when an error from a writer that owns its sink reports that the peer
- * closed that sink. This intentionally accepts structural error objects rather
- * than requiring an `Error` instance.
- */
-export declare function isKnownSinkPeerClosedError(error: unknown): boolean;
-/**
- * Backward-compatible local-sink classifier for output writers. Callers must
- * use it only when they own the sink that produced the error.
- */
-export declare function isBrokenPipeError(error: unknown): boolean;
-/**
- * A classifier for process-level stdout `EPIPE` errors. Its direct-write
- * evidence is private to each factory instance, so only the owner that
- * intercepted `process.stdout.write` can mark an error for this classifier.
- */
-export interface ProcessStdoutEpipeClassifier {
-    markDirectProcessStdoutWriteError(error: unknown): void;
-    isAttributableProcessStdoutEpipe(error: unknown): boolean;
-}
-export declare function createProcessStdoutEpipeClassifier(): ProcessStdoutEpipeClassifier;
-/**
- * Exit code for a producer terminated because its output pipe broke:
- * 128 + SIGPIPE (13), matching what shells report for SIGPIPE-killed tools
- * in `foo | head`-style pipelines.
- */
-export declare const BROKEN_PIPE_EXIT_CODE = 141;

package/dist/types/cli.d.ts

@@ -1,126 +0,0 @@
-export interface FlagDescriptor<K extends "string" | "boolean" | "integer" = "string" | "boolean" | "integer"> {
-    kind: K;
-    description?: string;
-    char?: string;
-    default?: unknown;
-    multiple?: boolean;
-    options?: readonly string[];
-    required?: boolean;
-}
-export interface ArgDescriptor {
-    kind: "string";
-    description?: string;
-    required?: boolean;
-    multiple?: boolean;
-    options?: readonly string[];
-}
-interface FlagInput {
-    description?: string;
-    char?: string;
-    default?: unknown;
-    multiple?: boolean;
-    options?: readonly string[];
-    required?: boolean;
-}
-interface ArgInput {
-    description?: string;
-    required?: boolean;
-    multiple?: boolean;
-    options?: readonly string[];
-}
-/** Builders that match the `Flags.*()` / `Args.*()` API from oclif. */
-export declare const Flags: {
-    string<T extends FlagInput>(opts?: T): FlagDescriptor<"string"> & T;
-    boolean<T extends FlagInput>(opts?: T): FlagDescriptor<"boolean"> & T;
-    integer<T extends FlagInput & {
-        default?: number;
-    }>(opts?: T): FlagDescriptor<"integer"> & T;
-};
-export declare const Args: {
-    string<T extends ArgInput>(opts?: T): ArgDescriptor & T;
-};
-/**
- * Thrown when CLI argument/flag parsing or validation fails (unknown flag,
- * bad option value, missing required arg, etc.). `run()` catches this to print
- * the message and render usage instead of crashing as an uncaught exception.
- */
-export declare class CliParseError extends Error {
-    constructor(message: string);
-}
-type FlagValue<D extends FlagDescriptor> = D["kind"] extends "boolean" ? D extends {
-    default: boolean;
-} ? boolean : boolean | undefined : D["kind"] extends "integer" ? D extends {
-    default: number;
-} ? number : number | undefined : D extends {
-    multiple: true;
-} ? string[] | undefined : string | undefined;
-type ArgValue<D extends ArgDescriptor> = D extends {
-    multiple: true;
-} ? string[] | undefined : string | undefined;
-type FlagValues<T extends Record<string, FlagDescriptor>> = {
-    [K in keyof T]: FlagValue<T[K]>;
-};
-type ArgValues<T extends Record<string, ArgDescriptor>> = {
-    [K in keyof T]: ArgValue<T[K]>;
-};
-export interface ParseOutput<F extends Record<string, FlagDescriptor> = Record<string, FlagDescriptor>, A extends Record<string, ArgDescriptor> = Record<string, ArgDescriptor>> {
-    flags: FlagValues<F>;
-    args: ArgValues<A>;
-    argv: string[];
-}
-export interface CommandCtor {
-    new (argv: string[], config: CliConfig): Command;
-    description?: string;
-    hidden?: boolean;
-    strict?: boolean;
-    aliases?: string[];
-    examples?: string[];
-    flags?: Record<string, FlagDescriptor>;
-    args?: Record<string, ArgDescriptor>;
-    delegateHelp?: boolean;
-}
-/** Configuration passed to every command instance and help renderers. */
-export interface CliConfig {
-    bin: string;
-    version: string;
-    /** All registered commands keyed by their canonical name. */
-    commands: Map<string, CommandCtor>;
-}
-/** Minimal Command base matching the oclif surface we use. */
-export declare abstract class Command {
-    argv: string[];
-    config: CliConfig;
-    constructor(argv: string[], config: CliConfig);
-    abstract run(): Promise<void>;
-    /**
-     * Parse argv against the static `flags` and `args` declared on the
-     * concrete command class. Returns a typed `{ flags, args, argv }` object.
-     */
-    parse<C extends CommandCtor>(_Cmd: C): Promise<ParseOutput<NonNullable<C["flags"]> extends Record<string, FlagDescriptor> ? NonNullable<C["flags"]> : Record<string, FlagDescriptor>, NonNullable<C["args"]> extends Record<string, ArgDescriptor> ? NonNullable<C["args"]> : Record<string, ArgDescriptor>>>;
-}
-/** Render full root help: header, default command details, subcommand list. */
-export declare function renderRootHelp(config: CliConfig): void;
-/** Render help for a single command. */
-export declare function renderCommandHelp(bin: string, id: string, Cmd: CommandCtor): void;
-/** A lazily-loaded command: canonical name, loader, and optional aliases. */
-export interface CommandEntry {
-    name: string;
-    load: () => Promise<CommandCtor>;
-    aliases?: string[];
-}
-export interface RunOptions {
-    bin: string;
-    version: string;
-    argv: string[];
-    commands: CommandEntry[];
-    /** Custom help renderer. Receives fully-populated config. */
-    help?: (config: CliConfig) => Promise<void> | void;
-}
-/**
- * Main entry point — replaces `run()` from @oclif/core.
- *
- * Each command is explicitly registered with a lazy loader.
- * No filesystem scanning, no plugin system, no package.json reading.
- */
-export declare function run(opts: RunOptions): Promise<void>;
-export {};

package/dist/types/color.d.ts

@@ -1,82 +0,0 @@
-/**
- * Color manipulation utilities for hex colors.
- *
- * @example
- * ```ts
- * import { hexToHsv, hsvToHex } from "@sayknow-cli/utils";
- *
- * // Work with HSV directly
- *
- * // Or work with HSV directly
- * const hsv = hexToHsv("#4ade80");
- * hsv.h = (hsv.h + 90) % 360;
- * const newHex = hsvToHex(hsv);
- * ```
- */
-export interface HSV {
-    /** Hue in degrees (0-360) */
-    h: number;
-    /** Saturation (0-1) */
-    s: number;
-    /** Value/brightness (0-1) */
-    v: number;
-}
-export interface RGB {
-    /** Red (0-255) */
-    r: number;
-    /** Green (0-255) */
-    g: number;
-    /** Blue (0-255) */
-    b: number;
-}
-/**
- * Parse a hex color string to RGB.
- * Supports #RGB, #RRGGBB formats.
- */
-export declare function hexToRgb(hex: string): RGB;
-/**
- * Convert RGB to hex color string.
- */
-export declare function rgbToHex(rgb: RGB): string;
-/**
- * Convert RGB to HSV.
- */
-export declare function rgbToHsv(rgb: RGB): HSV;
-/**
- * Convert HSV to RGB.
- */
-export declare function hsvToRgb(hsv: HSV): RGB;
-/**
- * Convert hex color to HSV.
- */
-export declare function hexToHsv(hex: string): HSV;
-/**
- * Convert HSV to hex color.
- */
-export declare function hsvToHex(hsv: HSV): string;
-/**
- * Shift the hue of a hex color by a given number of degrees.
- */
-export declare function shiftHue(hex: string, degrees: number): string;
-export interface HSVAdjustment {
-    /** Hue shift in degrees (additive) */
-    h?: number;
-    /** Saturation multiplier */
-    s?: number;
-    /** Value/brightness multiplier */
-    v?: number;
-}
-/**
- * Adjust HSV components of a hex color.
- *
- * @param hex - Hex color string (#RGB or #RRGGBB)
- * @param adj - Adjustments: h is additive degrees, s and v are multipliers
- * @returns New hex color string
- *
- * @example
- * ```ts
- * // Shift hue +60°, reduce saturation to 71%
- * adjustHsv("#00ff88", { h: 60, s: 0.71 }) // "#4a9eff"
- * ```
- */
-export declare function adjustHsv(hex: string, adj: HSVAdjustment): string;

package/dist/types/dirs.d.ts

@@ -1,163 +0,0 @@
-/**
- * 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.
- *
- * On Linux, if XDG_DATA_HOME / XDG_STATE_HOME / XDG_CACHE_HOME environment
- * variables are set, paths are redirected to XDG-compliant locations under
- * $XDG_*_HOME/skc/. This requires running `skc config migrate` first to
- * move data to the new locations. No filesystem existence checks are performed
- * — if the env var is set, skc trusts that the migration has been done.
- */
-/** App name (e.g. "skc") */
-export declare const APP_NAME: string;
-/** Config directory name (e.g. ".skc") */
-export declare const CONFIG_DIR_NAME: string;
-/** Version (e.g. "1.0.0") */
-export declare const VERSION: string;
-/** Minimum Bun version */
-export declare const MIN_BUN_VERSION: string;
-/**
- * Build the diagnostic shown when the Bun runtime executing `skc` is older
- * than {@link MIN_BUN_VERSION}. This is the most common Windows native-install
- * failure (issue #525): `bun install -g sayknow-cli` probes a recent Bun while
- * the `skc` launcher resolves an older Bun still on PATH. The message names the
- * exact detected runtime path and gives a platform-specific upgrade + PATH fix
- * instead of a bare `bun upgrade`.
- *
- * Pure and platform-parameterized so it can be unit-tested cross-platform.
- */
-export declare function formatBunRuntimeError(opts: {
-    currentVersion: string;
-    minVersion: string;
-    execPath?: string;
-    platform?: NodeJS.Platform;
-}): string;
-export declare function resolveEquivalentPath(inputPath: string): string;
-export declare function normalizePathForComparison(inputPath: string): string;
-export declare function pathIsWithin(root: string, candidate: string): boolean;
-export declare function relativePathWithinRoot(root: string, candidate: string): string | null;
-/** Get the project directory. */
-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;
-/** Get the config root directory (~/.skc). */
-export declare function getConfigRootDir(): string;
-/** Set the coding agent directory. Creates a fresh resolver, invalidating all cached paths. */
-export declare function setAgentDir(dir: string): void;
-/** Get the agent config directory (~/.skc/agent). */
-export declare function getAgentDir(): string;
-/** Get the project-local config directory (.skc). */
-export declare function getProjectAgentDir(cwd?: string): string;
-/** Get the reports directory (~/.skc/reports). */
-export declare function getReportsDir(): string;
-/** Get the logs directory (~/.skc/logs). */
-export declare function getLogsDir(): string;
-/** Get the path to a dated log file (~/.skc/logs/skc.YYYY-MM-DD.log). */
-export declare function getLogPath(date?: Date): string;
-/**
- * Get the plugins directory (~/.skc/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.
- */
-export declare function getPluginsDir(home?: string): string;
-/** Where npm installs packages (~/.skc/plugins/node_modules). */
-export declare function getPluginsNodeModules(): string;
-/** Plugin manifest (~/.skc/plugins/package.json). */
-export declare function getPluginsPackageJson(): string;
-/** Plugin lock file (~/.skc/plugins/skc-plugins.lock.json). */
-export declare function getPluginsLockfile(): string;
-/** Get the remote mount directory (~/.skc/remote). */
-export declare function getRemoteDir(): string;
-/** Get the agent-managed worktrees directory (~/.skc/wt). */
-export declare function getWorktreesDir(): string;
-/** Get the SSH control socket directory (~/.skc/ssh-control). */
-export declare function getSshControlDir(): string;
-/** Get the remote host info directory (~/.skc/remote-host). */
-export declare function getRemoteHostDir(): string;
-/** Get the managed Python venv directory (~/.skc/python-env). */
-export declare function getPythonEnvDir(): string;
-/** Get the shared Python gateway state directory (~/.skc/agent/python-gateway; XDG default: $XDG_STATE_HOME/skc/python-gateway). */
-export declare function getPythonGatewayDir(): string;
-/** Get the puppeteer sandbox directory (~/.skc/puppeteer). */
-export declare function getPuppeteerDir(): string;
-/**
- * Stable 7-character hex digest of an absolute filesystem path.
- *
- * Used to pack the project identity into a single short fs-safe segment
- * (e.g. PR-checkout and task-isolation worktree dirs under `~/.skc/wt/`).
- * Bun.hash is non-cryptographic — collision space is ~2^28, which is fine
- * for naming a handful of repos on a single machine. Same input on the
- * same Bun runtime yields the same output.
- */
-export declare function hashPath(absPath: string): string;
-/** Get the path to a single worktree directory (~/.skc/wt/<segment>). */
-export declare function getWorktreeDir(segment: string): string;
-/** Get the GPU cache path (~/.skc/gpu_cache.json). */
-export declare function getGpuCachePath(): string;
-/**
- * Get the GitHub view cache database path (~/.skc/cache/github-cache.db).
- * Honors the `SKC_GITHUB_CACHE_DB` env var when set so tests can isolate the
- * cache file without touching the rest of the config root.
- */
-export declare function getGithubCacheDbPath(): string;
-/** Get the natives directory (~/.skc/natives). */
-export declare function getNativesDir(): string;
-/** Get the stats database path (~/.skc/stats.db). */
-export declare function getStatsDbPath(): string;
-/** Get the autoresearch state directory (~/.skc/autoresearch). */
-export declare function getAutoresearchDir(): string;
-/** Get the per-project autoresearch state directory (~/.skc/autoresearch/<encoded-project>). */
-export declare function getAutoresearchProjectDir(encodedProject: string): string;
-/** Get the per-project autoresearch SQLite database path (~/.skc/autoresearch/<encoded-project>.db). */
-export declare function getAutoresearchDbPath(encodedProject: string): string;
-/** Get the per-run artifact directory (~/.skc/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). */
-export declare function getHistoryDbPath(agentDir?: string): string;
-/** Get the path to models.db (model cache database). */
-export declare function getModelDbPath(agentDir?: string): string;
-/** Get the sessions directory (~/.skc/agent/sessions). */
-export declare function getSessionsDir(agentDir?: string): string;
-/** Get the content-addressed blob store directory (~/.skc/agent/blobs). */
-export declare function getBlobsDir(agentDir?: string): string;
-/** Get the custom themes directory (~/.skc/agent/themes). */
-export declare function getCustomThemesDir(agentDir?: string): string;
-/** Get the tools directory (~/.skc/agent/tools). */
-export declare function getToolsDir(agentDir?: string): string;
-/** Get the slash commands directory (~/.skc/agent/commands). */
-export declare function getCommandsDir(agentDir?: string): string;
-/** Get the prompts directory (~/.skc/agent/prompts). */
-export declare function getPromptsDir(agentDir?: string): string;
-/** Get the user-level Python modules directory (~/.skc/agent/modules). */
-export declare function getAgentModulesDir(agentDir?: string): string;
-/** Get the memories directory (~/.skc/agent/memories). */
-export declare function getMemoriesDir(agentDir?: string): string;
-/** Get the terminal sessions directory (~/.skc/agent/terminal-sessions). */
-export declare function getTerminalSessionsDir(agentDir?: string): string;
-/** Get the crash log path (~/.skc/agent/skc-crash.log). */
-export declare function getCrashLogPath(agentDir?: string): string;
-/** Get the debug log path (~/.skc/agent/skc-debug.log). */
-export declare function getDebugLogPath(agentDir?: string): string;
-/** Get the project-level Python modules directory (.skc/modules). */
-export declare function getProjectModulesDir(cwd?: string): string;
-/** Get the project-level prompts directory (.skc/prompts). */
-export declare function getProjectPromptsDir(cwd?: string): string;
-/** Get the project-level plugin overrides path (.skc/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 SSH config file path. */
-export declare function getSSHConfigPath(scope: "user" | "project", cwd?: string): string;