export interface OwnerIdentity {
  pid: number;
  startedAt: string;
  sessionKey: string;
  pidStartTime?: string;
  token: string;
}

export interface WatchStartOptions {
  root: string;
  me: string;
  sessionKey: string;
  bridgeDir: string;
  attached: boolean;
  tui: boolean;
  available: boolean;
  isTrusted: (from: string) => boolean;
  isContinuationTrusted?: (from: string) => boolean;
  emit: (payload: {
    envelopes: Array<Record<string, unknown>>;
    activeId: string | null;
    triggerTurn: boolean;
    urgentTrusted: boolean;
    promotionReason?: 'urgent' | 'continuation' | 'deferred' | 'resume' | null;
  }) => Promise<void>;
  onMigration?: (migration: Record<string, unknown>) => Promise<void>;
  onSecondary?: (owner: OwnerIdentity | null) => Promise<void>;
  onFatal?: (error: unknown) => Promise<void>;
  heartbeat?: (options: { root: string; me: string; status?: string }) => void | Promise<void>;
}

export interface WatchLifecycle {
  start(options: WatchStartOptions): Promise<{ status: string; owner: boolean; identity?: OwnerIdentity; key?: string; error?: unknown }>;
  stop(options: { root: string; me: string; sessionKey: string; clearActiveId?: boolean }): Promise<{ owner: boolean; stopped: boolean; identity?: OwnerIdentity }>;
  ownerMutation<T>(
    options: { root: string; me: string; sessionKey: string; attached?: boolean },
    operation: () => T | Promise<T>,
  ): Promise<{ owner: false } | { owner: true; value: T }>;
  owns(options: { root: string; me: string; sessionKey: string }): Promise<boolean>;
  inspect(root: string, me: string): { key: string; root: string; me: string; sessionKey: string; identity: OwnerIdentity } | null;
  size(): number;
}

export function watcherKey(root: string, me: string): string;
export function createWatchLifecycle(options?: Record<string, unknown>): WatchLifecycle;