/**
 * Canonical Signet workspace path resolution.
 *
 * One owner for the "resolve `SIGNET_PATH` → `SIGNET_WORKSPACE` →
 * `$XDG_CONFIG_HOME/signet/workspace.json` → `~/.agents` default" chain that
 * is shared by connector-base, the CLI, and the desktop shell (issue #956).
 *
 * Resolution precedence:
 *   1. `SIGNET_PATH` env var
 *   2. `SIGNET_WORKSPACE` env var (alias, lower precedence)
 *   3. persisted `$XDG_CONFIG_HOME/signet/workspace.json` `{ workspace }`
 *   4. `~/.agents` default
 *
 * Env var precedence is defined once here and applied everywhere, so a synced
 * or cloned agents directory resolves consistently regardless of which surface
 * performs the resolution.
 */
export type WorkspaceSource = "env" | "config" | "default";
export interface WorkspaceResolution {
    readonly path: string;
    readonly source: WorkspaceSource;
    readonly configPath: string;
    readonly configuredPath: string | null;
}
export interface ResolveWorkspacePathOptions {
    readonly env?: NodeJS.ProcessEnv;
    readonly home?: string;
    /**
     * Throw on a malformed persisted workspace.json instead of falling back to
     * the default. Default `false` (graceful), which is required for surfaces
     * that resolve at import time and must never crash on a corrupt config.
     * Explicit install operations pass `true` to fail loud.
     */
    readonly strict?: boolean;
    /**
     * Require an env-derived workspace path to point at an existing directory.
     * When `false` (default) an env override is trusted verbatim. When `true`,
     * a stale env override is treated as unset (with a warning) and resolution
     * falls through to the config/default, which prevents a migrated/legacy
     * managed extension from re-embedding a path that no longer exists
     * (issue #1016).
     */
    readonly requireExistingEnvPath?: boolean;
}
/** Env vars honored as workspace overrides, in precedence order. */
export declare const WORKSPACE_ENV_KEYS: readonly ["SIGNET_PATH", "SIGNET_WORKSPACE"];
export declare function normalizeWorkspacePath(pathValue: string, home?: string): string;
export declare function getWorkspaceConfigPath(env?: NodeJS.ProcessEnv, home?: string): string;
/**
 * Read the persisted `workspace` value from `workspace.json`.
 *
 * Returns `null` when the file is absent or (in non-strict mode) malformed.
 * In strict mode a malformed file throws, preserving the historical contract
 * of explicit install operations.
 */
export declare function readConfiguredWorkspacePath(env?: NodeJS.ProcessEnv, home?: string, options?: {
    readonly strict?: boolean;
}): string | null;
export declare function writeConfiguredWorkspacePath(pathValue: string, env?: NodeJS.ProcessEnv, home?: string): string;
export declare function clearConfiguredWorkspacePath(env?: NodeJS.ProcessEnv): void;
/**
 * Resolve the active Signet workspace path from env, persisted config, and
 * default, returning a structured result describing which source won.
 */
export declare function resolveWorkspacePath(options?: ResolveWorkspacePathOptions): WorkspaceResolution;
//# sourceMappingURL=workspace.d.ts.map