/**
 * Centralized path helpers for gajae-code config directories.
 *
 * 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
 * $XDG_*_HOME/gjc/. This requires running `gjc config migrate` first to
 * move data to the new locations. No filesystem existence checks are performed
 * — if the env var is set, gjc trusts that the migration has been done.
 */
import { canonicalEnvKey } from "./env-file";
export { canonicalEnvKey };
/** App name (e.g. "gjc") */
export declare const APP_NAME: string;
/** Config directory name (e.g. ".gjc") */
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 `gjc` is older
 * than {@link MIN_BUN_VERSION}. This is the most common Windows native-install
 * failure (issue #525): `bun install -g gajae-code` probes a recent Bun while
 * the `gjc` 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;
/**
 * On macOS, strip /private prefix only when both paths resolve to the same location.
 * This preserves aliases like /private/tmp -> /tmp without rewriting unrelated paths.
 */
export declare function standardizeMacOSPath(p: string): string;
export declare function resolveEquivalentPath(inputPath: string): string;
export declare function normalizePathForComparison(inputPath: string, platform?: NodeJS.Platform): string;
/** Return whether a relative path crosses above its root or is unexpectedly absolute. */
export declare function relativePathEscapesRoot(relative: string): boolean;
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;
export declare function getConfigAgentDirName(): string;
/** Get the config root directory (~/.gjc). */
export declare function getConfigRootDir(): string;
/**
 * The authoritative home for user-scope state.
 *
 * Provenance-checked and resolved at call time: a home established or changed
 * after this module loaded is honored, while a home the project dotenv could
 * have planted is rejected in favor of the OS account database. See
 * {@link resolveTrustedHome}.
 */
export declare function getTrustedHomeDir(): string;
/** Trusted config root, resolved at call time; preserves the configured nested config-dir name. */
export declare function getTrustedConfigRootDir(): string;
/**
 * Set the coding agent directory. Creates a fresh resolver, invalidating all
 * cached paths.
 *
 * This also exports `GJC_CODING_AGENT_DIR`, so child processes inherit the same
 * selection and resolve the same storage lane.
 */
export declare function setAgentDir(dir: string): void;
/**
 * Rebuild the resolver from the current trusted environment. Callers that
 * temporarily used {@link setAgentDir} must first restore the original
 * GJC_CODING_AGENT_DIR / PI_CODING_AGENT_DIR values, then call this function;
 * an originally absent override remains absent and keeps following HOME.
 */
export declare function resetAgentDirFromEnvironment(): void;
/** Get the agent config directory (~/.gjc/agent). */
export declare function getAgentDir(): string;
/** Resolver-owned profile classification, stable across HOME refreshes. */
export declare function getAgentProfileAuthority(): "default" | "custom";
export declare function getConfigDirName(): string;
/**
 * Join a file under the provenance-checked agent directory, never the XDG
 * state category. Automatic crash relay must not follow `XDG_STATE_HOME`:
 * a checkout `.env` can set that variable and create `$XDG_STATE_HOME/gjc`,
 * which the ordinary state resolver would then treat as the crash store.
 */
export declare function getTrustedAgentFile(filename: string): string;
/** Whether the current checkout declares an environment key in its `.env`. */
export declare function isProjectEnvDeclaration(name: string): boolean;
/** Get the project-local config directory (.gjc). */
export declare function getProjectAgentDir(cwd?: string): string;
/** Get the reports directory (~/.gjc/reports). */
export declare function getReportsDir(): string;
/** Get the logs directory (~/.gjc/logs). */
export declare function getLogsDir(): string;
/** Get the path to a dated log file (~/.gjc/logs/gjc.YYYY-MM-DD.log). */
export declare function getLogPath(date?: Date): string;
/**
 * The logs directory the process actually reads and writes.
 *
 * A trusted `GJC_LOG_DIR` redirects the sink — the test preload pins it to a
 * per-process temp directory so `bun test` stops appending fixture
 * `level:error` records to the operator's shared log (issue #5618) — and
 * everything else falls back to {@link getLogsDir}.
 *
 * The override is provenance-checked through the same {@link trustedValue} rule
 * as the config and agent directories: Bun loads `cwd/.env` into `process.env`
 * before any module runs, so a repository could otherwise redirect where the
 * operator's production logs are written. A dynamic (`$`/backtick) declaration
 * is rejected there too, which fails closed onto the canonical path.
 *
 * This is deliberately *not* folded into {@link getLogsDir}: that function's
 * config-root semantics are pinned by tests, and the preload sets `GJC_LOG_DIR`
 * for every test process, so folding the override in would move it under every
 * test. Writers and readers must both come through here instead — the split
 * between the two is what let the transport and the log readers disagree.
 */
export declare function getEffectiveLogsDir(): string;
/** Get the dated log file under {@link getEffectiveLogsDir}. */
export declare function getEffectiveLogPath(date?: Date): string;
/**
 * Get the plugins directory (~/.gjc/plugins or its XDG equivalent).
 *
 * No-arg form (production callers) goes through the XDG-aware DirResolver so
 * reads and writes always agree. The optional `home` parameter names an explicit
 * home: when it differs from the authoritative home resolved right now it
 * short-circuits the resolver and returns `<home>/<configDir>/plugins`, giving
 * callers that carry their own home (and tests with a temp HOME) a deterministic
 * path. Passing the authoritative home explicitly is identical to the no-arg
 * form — XDG semantics are preserved.
 */
export declare function getPluginsDir(home?: string): string;
/** Get the default-profile plugin directory without ambient profile authority. */
export declare function getDefaultPluginsDir(): string;
/** Where npm installs packages (~/.gjc/plugins/node_modules). */
export declare function getPluginsNodeModules(): string;
/** Plugin manifest (~/.gjc/plugins/package.json). */
export declare function getPluginsPackageJson(): string;
/** Plugin lock file (~/.gjc/plugins/gjc-plugins.lock.json). */
export declare function getPluginsLockfile(): string;
/** Get the remote mount directory (~/.gjc/remote). */
export declare function getRemoteDir(): string;
/** Get the agent-managed worktrees directory (~/.gjc/wt). */
export declare function getWorktreesDir(): string;
/** Get the SSH control socket directory (~/.gjc/ssh-control). */
export declare function getSshControlDir(): string;
/** Get the remote host info directory (~/.gjc/remote-host). */
export declare function getRemoteHostDir(): string;
/** Get the managed Python venv directory (~/.gjc/python-env). */
export declare function getPythonEnvDir(): string;
/** Get the shared Python gateway state directory (~/.gjc/agent/python-gateway; XDG default: $XDG_STATE_HOME/gjc/python-gateway). */
export declare function getPythonGatewayDir(): string;
/** Get the puppeteer sandbox directory (~/.gjc/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 `~/.gjc/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 (~/.gjc/wt/<segment>). */
export declare function getWorktreeDir(segment: string): string;
/** Get the GPU cache path (~/.gjc/gpu_cache.json). */
export declare function getGpuCachePath(): string;
/**
 * Get the GitHub view cache database path (~/.gjc/cache/github-cache.db).
 * Honors the `GJC_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 durable tool-choice capability cache path. */
export declare function getToolChoiceCapabilityCachePath(): string;
/** Get the natives directory (~/.gjc/natives). */
export declare function getNativesDir(): string;
/** Get the stats database path (~/.gjc/stats.db). */
export declare function getStatsDbPath(): 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 (~/.gjc/agent/sessions). */
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 managed cold-history sidecar cache root for a profile agent directory. */
export declare function getSidecarCacheRootDir(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). */
export declare function getToolsDir(agentDir?: string): string;
/** Get the slash commands directory (~/.gjc/agent/commands). */
export declare function getCommandsDir(agentDir?: string): string;
/** Get the prompts directory (~/.gjc/agent/prompts). */
export declare function getPromptsDir(agentDir?: string): string;
/** Get the user-level Python modules directory (~/.gjc/agent/modules). */
export declare function getAgentModulesDir(agentDir?: string): string;
/** Get the memories directory (~/.gjc/agent/memories). */
export declare function getMemoriesDir(agentDir?: string): string;
/** Get the terminal sessions directory (~/.gjc/agent/terminal-sessions). */
export declare function getTerminalSessionsDir(agentDir?: string): string;
/** Get the crash log path (~/.gjc/agent/gjc-crash.log). */
export declare function getCrashLogPath(agentDir?: string): string;
/** Get the crash event journal path (~/.gjc/agent/gjc-crash-events.jsonl). */
export declare function getCrashEventsPath(agentDir?: string): string;
/** Get the compacted crash signature index path (~/.gjc/agent/gjc-crash-index.json). */
export declare function getCrashIndexPath(agentDir?: string): string;
/** Get the handled error log path (~/.gjc/agent/gjc-error.log). */
export declare function getHandledErrorLogPath(agentDir?: string): string;
/** Get the handled error event journal path (~/.gjc/agent/gjc-error-events.jsonl). */
export declare function getHandledErrorEventsPath(agentDir?: string): string;
/** Get the compacted handled error signature index path (~/.gjc/agent/gjc-error-index.json). */
export declare function getHandledErrorIndexPath(agentDir?: string): string;
/** Get the debug log path (~/.gjc/agent/gjc-debug.log). */
export declare function getDebugLogPath(agentDir?: string): string;
/** Get the project-level Python modules directory (.gjc/modules). */
export declare function getProjectModulesDir(cwd?: string): string;
/** Get the project-level prompts directory (.gjc/prompts). */
export declare function getProjectPromptsDir(cwd?: string): string;
/** Get the project-level plugin overrides path (.gjc/plugin-overrides.json). */
export declare function getProjectPluginOverridesPath(cwd?: string): string;
/**
 * Get the primary MCP config file path (first candidate).
 *
 * User scope lives in the agent directory, so a profile override
 * (`--agent-dir`, `GJC_CODING_AGENT_DIR`, `setAgentDir()`) moves it. Pass
 * `agentDir` to resolve the scope of a session whose agent directory differs
 * from the process-wide one.
 */
export declare function getMCPConfigPath(scope: "user" | "project", cwd?: string, agentDir?: string): string;
/** Get the SSH config file path. */
export declare function getSSHConfigPath(scope: "user" | "project", cwd?: string, agentDir?: string): string;