/**
 * AIWG CLI Structured Logger
 *
 * Two public surfaces:
 *
 *   debug(scope, msg, ...args)   — cheap, env-gated, stderr-only diagnostic log.
 *                                   Unchanged from Phase 4 (#921). Use this for
 *                                   ad-hoc troubleshooting prints that no-op
 *                                   unless AIWG_DEBUG is set.
 *
 *   getLogger(scope)             — structured Logger (this file's main surface).
 *                                   Every record carries full provenance
 *                                   metadata (ts, invocation_id, command, user,
 *                                   cwd, aiwg_version, git_sha, channel, node,
 *                                   platform, tty, ci) and is written to both
 *                                   stderr (pretty) and ~/.aiwg/logs/aiwg-YYYY-
 *                                   MM-DD.jsonl (structured).
 *
 * Phase 4.5 of the CLI Stabilization Epic (#925) extends the Phase 4 debug()
 * helper into a full structured-logging stack.
 *
 * To enable debug-level output:
 *   AIWG_DEBUG=1 aiwg use all                    # enable everything (debug)
 *   AIWG_LOG_LEVEL=debug aiwg use all            # same
 *   AIWG_LOG_LEVEL=info aiwg use all             # info and above
 *   aiwg use all -v                              # info (verbose)
 *   aiwg use all -vv                             # debug
 *   aiwg use all --quiet                         # error only
 *   AIWG_LOG_FILE=/tmp/aiwg.jsonl aiwg use all   # override JSONL path
 *   AIWG_LOG_DISABLE=1 aiwg --version            # skip all logging
 *
 * Scope syntax (passed to both the debug() filter AND the Logger):
 *   'cli:*'                 — any cli:* scope
 *   'cli:use:*,net:*'       — multiple globs
 *   'cli:*,-cli:use:deploy' — include/exclude
 */
export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
interface Provenance {
    pid: number;
    ppid: number;
    user: string;
    host: string;
    cwd: string;
    aiwg_version: string;
    git_sha?: string;
    channel: string;
    node_version: string;
    platform: string;
    arch: string;
    os_release: string;
    tty: boolean;
    ci: boolean;
    invocation_id: string;
}
/**
 * Override the invocation ID discovered by the logger. Called from the
 * top-level entry (bin/aiwg.mjs) once the ID has been minted or inherited
 * from `AIWG_INVOCATION_ID`. Safe to call before the logger is used.
 */
export declare function setInvocationId(id: string): void;
export declare function getInvocationId(): string;
/**
 * Override the log level from code (typically from bin/aiwg.mjs after
 * parsing -v / -vv / --quiet flags). Must be called before the first
 * Logger method to affect records.
 */
export declare function setLogLevel(level: LogLevel): void;
/**
 * Prune daily log files older than `retentionDays`. Run once at startup
 * (bounded work: one directory listing). Silent on failure.
 */
export declare function pruneOldLogs(): void;
export interface Span {
    /** Close the span and emit a duration record. */
    end(msg?: string, fields?: Record<string, unknown>): void;
    /** Record a debug/info event within the span. */
    info(msg: string, fields?: Record<string, unknown>): void;
    debug(msg: string, fields?: Record<string, unknown>): void;
    warn(msg: string, fields?: Record<string, unknown>): void;
    error(msg: string, fields?: Record<string, unknown>): void;
}
export interface Logger {
    /** Log at debug level. */
    debug(msg: string, fields?: Record<string, unknown>): void;
    /** Log at info level. */
    info(msg: string, fields?: Record<string, unknown>): void;
    /** Log at warn level. */
    warn(msg: string, fields?: Record<string, unknown>): void;
    /** Log at error level. */
    error(msg: string, fields?: Record<string, unknown>): void;
    /** Spawn a child logger with a nested scope and merged extra fields. */
    child(opts: {
        scope?: string;
        fields?: Record<string, unknown>;
    }): Logger;
    /** Start a named span. Call span.end() to emit duration_ms. */
    span(name: string, fields?: Record<string, unknown>): Span;
}
export declare function getLogger(scope?: string, extraFields?: Record<string, unknown>): Logger;
/**
 * Emit a debug log record to stderr. No-op when AIWG_DEBUG is unset or
 * the scope does not match.
 *
 * Backward-compatible with the Phase 4 API. New code should prefer
 * getLogger(scope).debug() which also writes to the JSONL sink.
 */
export declare function debug(scope: string, ...args: unknown[]): void;
export declare function isDebugEnabled(scope: string): boolean;
/**
 * Return the effective logger configuration — used by `aiwg version --verbose`
 * and `aiwg diagnose` to surface where logs go and what level is in effect.
 */
export declare function getLoggerInfo(): {
    level: LogLevel;
    disabled: boolean;
    logFile: string | null;
    retentionDays: number;
    provenance: Provenance;
};
export {};
//# sourceMappingURL=log.d.ts.map