/**
 * `harn agents`: on-demand queries against the multi-agent coord layer.
 *
 *   harn agents whoami            current agent's name + instance_id + claims
 *   harn agents list              all active agents (default: fold transients)
 *   harn agents list --all        include raw kind=transient rows
 *   harn agents list --stale      include generations older than the freshness window
 *   harn agents list --json       JSON output (alias for --format json)
 *   harn agents status            end-of-turn status box (name + age + files + peers)
 *   harn agents heal-events       PIDMAP_HEAL telemetry (pid-map self-heal frequency)
 *   harn agents heal-events --since 24h --limit 20
 *   harn agents health            one-screen coord-layer health rollup
 *   harn agents health --since 7d --json
 */
import type { Command } from "commander";
import type { EmitContext, HarneryProgramContext } from "../commander.js";
import { nativeSessionIdentity } from "../core/agents/index.js";
import { type SessionFinalizationRequestV3 } from "../core/agents/session-finalizer-v3.js";
import { type Heartbeat } from "../core/agents/state/heartbeat-writer.js";
import type { EventTypeV3 } from "../core/events/v3/contract.js";
/**
 * Spawn options for agent-coord child processes: pin the coord root the
 * command already resolved (git-superproject-aware via `monorepoRoot()`), so
 * the helper can't re-resolve a DIFFERENT root by walking up from a drifted
 * shell cwd. The concrete failure this prevents: a shell cd'd into an
 * embedded harnery checkout (which carries its own committed `.harnery/`)
 * made agent-coord resolve that nested root and miss the session's real
 * heartbeat — `set-task: no heartbeat at .harnery/active/<id>.json` while
 * `status` (which resolves in-process) worked fine. Mirrors the hooks side's
 * `childEnv()`; every agent-coord spawn must carry this.
 */
export declare function coordHelperOpts(root: string): {
    cwd: string;
    env: NodeJS.ProcessEnv;
};
export { nativeSessionIdentity };
export declare function registerAgentsCommand(program: Command, emitParam: EmitContext, programContext?: HarneryProgramContext, binName?: string): void;
export declare function registerCouncilCommands(parent: Command): void;
type StatusPeerHeartbeat = {
    instance_id: string;
    last_heartbeat: string;
    files_touched?: string[];
    name?: string;
    platform?: string;
};
export declare function collectStatusPeerHealth(root: string, myOwner: string, nowMs?: number, readRows?: (root: string) => StatusPeerHeartbeat[], freshnessSeconds?: number): {
    livePeers: StatusPeerHeartbeat[];
    stale: number;
};
/** Bounded diagnostic event shape projected from the canonical V3 ledger. */
export interface CanonicalEvent {
    event_type: EventTypeV3;
    ts: string;
    instance_id?: string;
    adapter?: string;
    payload?: Record<string, unknown>;
}
export interface AgentDiagnosticEventRead {
    source: "v3";
    authoritative: boolean;
    reason?: string;
    truncated: boolean;
    bytes: number;
    events: CanonicalEvent[];
}
/** Read validated canonical V3 events. */
export declare function readAgentDiagnosticEventsInWindow(root: string, cutoffMs: number): AgentDiagnosticEventRead;
export type EventLedgerHealthV3 = {
    state: "unavailable";
    reason: string;
} | {
    state: "live";
    mode: "candidate" | "active";
    open_spans: {
        total: number;
        generations: Array<{
            instance_id: string;
            generation_id: string;
            adapter: string;
            span_count: number;
            /** False = spans are open with NO open turn: the orphan signature
             * (a turn ended without its tool spans being closed). */
            turn_open: boolean;
        }>;
    };
    pending_finalizations: Array<{
        request_id: string;
        trigger: string;
        generation_id: string;
        age_ms: number;
        allowed_open_span_count: number;
    }>;
    intake_spool: {
        total: number;
        groups: Array<{
            adapter: string;
            session_hash: string;
            count: number;
        }>;
    };
    diagnostics_spool: {
        /** Logical occurrences: loose files plus coalesced summary counts. */
        total: number;
        /** Physical loose diagnostic files. */
        loose_total: number;
        /** Occurrences coalesced into summaries instead of loose files. */
        summarized_total: number;
        /** Physical summary files in `diagnostic-summaries/`. */
        summary_files: number;
        last_24h: number;
        last_1h: number;
        latest_at: string | null;
        by_category: Record<string, {
            total: number;
            last_24h: number;
        }>;
        recent_by_category: Record<string, {
            last_1h: number;
            latest_at: string | null;
        }>;
        /** Times the summary gate failed open (loose write proceeded). */
        mitigation_fail_open: number;
    };
    coordination_authority: {
        safe: boolean;
        global_diagnostics: number;
        isolated_diagnostics: number;
        affected_generations: string[];
        codes: string[];
    };
    span_pressure: Array<{
        instance_id: string;
        generation_id: string;
        span_count: number;
    }>;
    collection_errors: string[];
};
/**
 * Read-only health counters for the V3 event ledger's producer surfaces. Never
 * mutates ledger state (no control repair, no spool drain) and never throws:
 * a non-live route returns `{ state: "unavailable" }`, and each sub-surface
 * that fails to read lands in `collection_errors` instead of aborting the rest.
 */
export declare function collectEventLedgerHealthV3(root: string, nowMs?: number): EventLedgerHealthV3;
/**
 * Tally stop-hook remediation-cap exhaustions in the window from
 * `.harnery/debug/agent-hook.ndjson` (rows with
 * `skipped: "stop-remediation-cap-exhausted"`). Each one is a session whose
 * end-of-turn evidence never landed, so the Stop hook gave up bouncing it and
 * let the turn end unenforced — a compliance gap an operator should see
 * without grepping the debug ledger.
 */
export declare function readStopRemediationExhaustions(root: string, cutoffMs: number): {
    total: number;
    latestAt: string | null;
    sessions: string[];
};
/** Tally agent-hook failures (.harnery/debug/agent-hook.errors.ndjson) in the
 * window by exact error and phase, while separating current-hour failures from
 * historical rows. Each line is {ts, error, phase, ...}. */
export declare function readHookErrors(root: string, cutoffMs: number, nowMs?: number): {
    total: number;
    last1h: number;
    latestAt: string | null;
    byPhase: Record<string, number>;
    byError: Record<string, number>;
    top: Array<{
        phase: string;
        count: number;
        sample: string;
    }>;
    topErrors: Array<{
        error: string;
        count: number;
        phase: string;
    }>;
    recentTopErrors: Array<{
        error: string;
        count: number;
        phase: string;
    }>;
};
/** One rendered line in a trace. */
export interface TraceEntry {
    ts: string;
    event_type: string;
    detail: string;
}
export declare function traceInstanceIdsForEventSource(nativeInstanceIds: readonly string[], source: "v3"): string[];
/** Map a canonical event to a concise trace line, or null to drop it. */
export declare function traceLine(ev: CanonicalEvent, allTools: boolean): TraceEntry | null;
export declare function pendingFinalizationTraceEntries(requests: readonly SessionFinalizationRequestV3[], instanceId: string): TraceEntry[];
export interface ActiveAgentHealthSummary {
    source: "event-ledger-v3";
    total: number;
    by_platform: Record<string, number>;
    by_kind: Record<string, number>;
    by_schema_version: Record<string, number>;
    stale: number;
}
type ActiveHealthHeartbeat = {
    instance_id: string;
    platform?: string;
    kind?: string;
    schema_version?: number;
    last_heartbeat?: string;
};
/**
 * V3 generations, not disposable heartbeat caches, are the active-agent authority.
 */
export declare function collectActiveAgentHealth(root: string, nowMs?: number, readRows?: (root: string) => ActiveHealthHeartbeat[], freshnessSeconds?: number): ActiveAgentHealthSummary;
export type HeartbeatCacheIssue = "no-name" | "invalid-heartbeat" | "stale-age";
/** Classify a parseable heartbeat cache file without conflating age with corruption. */
export declare function classifyHeartbeatCacheIssue(heartbeat: Pick<Heartbeat, "name" | "last_heartbeat">, nowMs: number, staleAgeMs: number): HeartbeatCacheIssue | null;
//# sourceMappingURL=agents.d.ts.map