@sayknow-cli/coding-agent 0.4.2 → 0.4.4

package/dist/types/sdk/bus/lifecycle-orchestrator.d.ts

@@ -0,0 +1,141 @@
+import type { LifecycleErrorReason, ResumeCandidate, SessionCreateFrame, SessionLifecycleRequest } from "./index";
+/** Durable idempotency state for a single lifecycle request. */
+export type LedgerState = "in_progress" | "success" | "failure" | "terminal_uncertain";
+/** One persisted idempotency entry, keyed by `chatId:updateId`. */
+export interface LedgerEntry {
+    requestHash: string;
+    state: LedgerState;
+    requestId: string;
+    verb: SessionLifecycleRequest["type"];
+    intendedSessionId?: string;
+    startupPromptRef?: string;
+    createdAt: number;
+    updatedAt: number;
+    targetSummary: Record<string, unknown>;
+    sessionId?: string;
+    tmuxSession?: string;
+    sessionStateFile?: string;
+    endpointUrl?: string;
+    /** Close effect outcome: whether the tmux process is confirmed gone. */
+    processGone?: boolean;
+    reason?: LifecycleErrorReason;
+    resumeMode?: ResumeEffectResult["mode"];
+}
+/** The full on-disk ledger document. */
+export interface LedgerDoc {
+    version: 1;
+    entries: Record<string, LedgerEntry>;
+}
+/** Persistence boundary: atomic + fsynced read/write of the ledger document. */
+export interface LedgerStore {
+    read(): Promise<LedgerDoc>;
+    /** Write atomically (temp + fsync + rename) under a per-ledger lock. */
+    write(doc: LedgerDoc): Promise<void>;
+}
+/** Redacted audit-v2 event. */
+export interface AuditEvent {
+    schemaVersion: 2;
+    ts: string;
+    event: "accepted" | "rejected" | "duplicate_reack" | "rate_limited" | "spawn_started" | "recovered_in_progress" | "success" | "failure" | "terminal_uncertain";
+    chatRef: string;
+    updateId: number;
+    requestRef: string;
+    verb: SessionLifecycleRequest["type"];
+    targetKind: CanonicalTargetKind;
+    targetRef: string;
+    reason?: LifecycleErrorReason;
+}
+export interface CreateEffectResult {
+    sessionId: string;
+    tmuxSession: string;
+    sessionStateFile?: string;
+    endpointUrl: string;
+    topicThreadId: string;
+}
+export interface ResumeEffectResult extends CreateEffectResult {
+    mode: "reattached" | "cold_restarted";
+}
+/** Injected effects + policy. Pure orchestration calls into these. */
+export interface OrchestratorDeps {
+    /** The single paired chat id. Anything else is rejected before parsing. */
+    pairedChatId: string;
+    /** In-memory, derived 32-byte audit-v2 HMAC key. */
+    auditRedactionKey: Uint8Array;
+    now: () => number;
+    store: LedgerStore;
+    audit: (event: AuditEvent) => Promise<void> | void;
+    /** Resolves the returned tmux provider once per request for psmux preflight. */
+    isPsmuxProvider: () => boolean;
+    /** Per-chat create rate limiter: returns true when allowed. */
+    allowCreate: (chatId: string, nowMs: number) => boolean;
+    /** Persist the once-consumed 0600 startup-prompt file after durably recording its ref. */
+    writeStartupPrompt: (requestId: string, prompt: string | undefined, persistRef: (ref: string) => Promise<void>) => Promise<string | undefined>;
+    /** Spawn a session for a create/cold-restart. */
+    spawnCreate: (frame: SessionCreateFrame, ids: {
+        lifecycleRequestId: string;
+        intendedSessionId: string;
+        startupPromptRef?: string;
+    }) => Promise<CreateEffectResult>;
+    closeSession: (target: {
+        sessionId: string;
+        tmuxSession?: string;
+        sessionStateFile?: string;
+    }) => Promise<{
+        processGone: boolean;
+    }>;
+    resumeSession: (target: {
+        sessionIdOrPrefix: string;
+        path?: string;
+    }) => Promise<ResumeEffectResult | {
+        ambiguous: ResumeCandidate[];
+    } | {
+        notFound: true;
+    }>;
+}
+export type CanonicalTargetKind = "existing_path" | "worktree" | "plain_dir" | "session_close" | "session_resume";
+export declare function canonicalTarget(frame: SessionLifecycleRequest): string;
+export declare function canonicalRequest(frame: SessionLifecycleRequest): string;
+export declare function requestHash(frame: SessionLifecycleRequest): string;
+export declare function auditRedactionRef(key: Uint8Array, domain: string, value: string): string;
+export declare function summarizeTarget(frame: SessionLifecycleRequest): Record<string, unknown>;
+export declare function ledgerKey(chatId: string, updateId: number): string;
+/** How a freshly-arrived request relates to the durable ledger. */
+export type DuplicateClass = {
+    kind: "new";
+} | {
+    kind: "reack_success";
+    entry: LedgerEntry;
+} | {
+    kind: "reack_failure";
+    entry: LedgerEntry;
+} | {
+    kind: "in_progress";
+    entry: LedgerEntry;
+} | {
+    kind: "terminal_uncertain";
+    entry: LedgerEntry;
+} | {
+    kind: "conflict";
+    entry: LedgerEntry;
+};
+/** Classify a request against an existing ledger entry (pure). */
+export declare function classifyDuplicate(existing: LedgerEntry | undefined, hash: string): DuplicateClass;
+/** The structured outcome the daemon translates into a wire response frame. */
+export type LifecycleOutcome = {
+    status: "ok";
+    entry: LedgerEntry;
+    mode?: "reattached" | "cold_restarted";
+} | {
+    status: "error";
+    reason: LifecycleErrorReason;
+    message: string;
+    candidates?: ResumeCandidate[];
+} | {
+    status: "pending";
+    entry: LedgerEntry;
+};
+/**
+ * Handle one authenticated lifecycle request. Enforces paired-chat gating,
+ * idempotency, and rate limiting BEFORE any side effect, then dispatches.
+ */
+export declare function handleLifecycleRequest(frame: SessionLifecycleRequest, deps: OrchestratorDeps): Promise<LifecycleOutcome>;

package/dist/types/sdk/bus/managed-daemon.d.ts

@@ -0,0 +1,48 @@
+import type { Settings } from "../../config/settings";
+import { RateLimitPool } from "./rate-limit-pool";
+import { type ThreadedSend } from "./threaded-render";
+export interface ManagedNotificationDaemonFs {
+    readdir(path: string): Promise<string[]>;
+}
+export interface ManagedSessionSocket {
+    sessionId: string;
+    token: string;
+    ws: WebSocket;
+    pending: Map<string, {
+        sessionId: string;
+        actionId: string;
+    }>;
+    capable: boolean;
+    lastPongAt: number;
+    awaitingNonce: string | undefined;
+    pingTimer: ReturnType<typeof setInterval> | undefined;
+}
+export interface ManagedNotificationDaemonOptions {
+    settings: Settings;
+    fs: ManagedNotificationDaemonFs;
+    WebSocketImpl?: typeof WebSocket;
+    now?: () => number;
+    setIntervalImpl?: typeof setInterval;
+    clearIntervalImpl?: typeof clearInterval;
+    rateLimitPool?: RateLimitPool<{
+        send: ThreadedSend;
+        topicId?: string;
+    }>;
+}
+export declare abstract class ManagedNotificationDaemon {
+    protected readonly opts: ManagedNotificationDaemonOptions;
+    readonly sessions: Map<string, ManagedSessionSocket>;
+    readonly pool: RateLimitPool<{
+        send: ThreadedSend;
+        topicId?: string;
+    }>;
+    protected constructor(opts: ManagedNotificationDaemonOptions);
+    scanRoots(): Promise<void>;
+    connectSession(sessionId: string, url: string, token: string): ManagedSessionSocket;
+    protected handleSessionMessage(session: ManagedSessionSocket, msg: Record<string, unknown>): Promise<boolean>;
+    protected renderFrame(frame: Record<string, unknown>): ThreadedSend | undefined;
+    protected dropSession(session: ManagedSessionSocket): void;
+    protected abstract readRoots(): Promise<string[]>;
+    private sendHello;
+    private startLiveness;
+}

package/dist/types/sdk/bus/native-runtime-compatibility.d.ts

@@ -0,0 +1,13 @@
+export declare class NativeRuntimeCompatibilityError extends Error {
+    readonly runtimeVersion: string;
+    readonly nativeVersion: string;
+    readonly workflowArbitrationAvailable: boolean;
+    readonly code = "native_runtime_incompatible";
+    readonly retryable = false;
+    constructor(runtimeVersion: string, nativeVersion: string, workflowArbitrationAvailable: boolean);
+}
+export declare function assertNativeRuntimeCompatibility(input: {
+    runtimeVersion: string;
+    nativeVersion: string;
+    notificationServer: unknown;
+}): void;

package/dist/types/sdk/bus/notification-orchestration.d.ts

@@ -0,0 +1,170 @@
+import type { RawSettings, SettingsAtomicPatch, SettingsAtomicReceipt } from "../../config/settings";
+import { type NotificationSettingsReader, type TelegramActivationMarker, type TelegramActivationMarkers, type TelegramActivationReason, type TelegramActivationState, telegramActivationIdentity } from "./config";
+import { type EnsureTelegramDaemonDetailedResult, type TelegramDaemonFs } from "./telegram-daemon";
+export type { TelegramActivationMarker, TelegramActivationMarkers, TelegramActivationReason, TelegramActivationState };
+export { telegramActivationIdentity };
+/** The identity relationship between a proposed Telegram configuration and a live daemon owner. */
+export type ProposedTelegramIdentityStatus = "absent" | "same" | "foreign" | "unknown";
+/**
+ * Non-secret metadata about a daemon owner. Token fingerprints and the owner's
+ * chat ID intentionally never cross this boundary. `chatDisplay`, when present,
+ * is supplied by the caller from an already-approved proposed-chat display.
+ */
+export interface TelegramDaemonOwnerMetadata {
+    ownerId: string;
+    pid: number;
+    generation?: number;
+    chatDisplay?: string;
+}
+/** Secret-safe proposed-identity preflight outcome. */
+export interface ProposedTelegramIdentity {
+    status: ProposedTelegramIdentityStatus;
+    owner?: TelegramDaemonOwnerMetadata;
+}
+export interface ProposedTelegramIdentityPreflightInput {
+    settings: NotificationSettingsReader;
+    botToken: string;
+    chatId: string;
+    /** A UI-approved display value for the proposed chat; never inferred from a foreign daemon state. */
+    chatDisplay?: string;
+    deps?: {
+        fs?: TelegramDaemonFs;
+        pidAlive?: (pid: number) => boolean;
+    };
+}
+/**
+ * Compare a proposed identity with the current daemon owner without exposing a
+ * token or token fingerprint. Invalid/unreadable state is deliberately
+ * `unknown`, which callers must treat as cancel-by-default.
+ */
+export declare function proposedTelegramIdentity(input: ProposedTelegramIdentityPreflightInput): Promise<ProposedTelegramIdentity>;
+export interface NotificationConfigurationWriter extends NotificationSettingsReader {
+    commitAtomicBatch(patches: readonly SettingsAtomicPatch[]): Promise<SettingsAtomicReceipt>;
+    commitAtomicBatchWithCurrent?(buildPatches: (current: Readonly<RawSettings>) => Promise<readonly SettingsAtomicPatch[]> | readonly SettingsAtomicPatch[]): Promise<SettingsAtomicReceipt>;
+}
+export declare function createTelegramActivationMarker(input: {
+    botToken: string;
+    chatId: string;
+    state: TelegramActivationState;
+    reason?: TelegramActivationReason;
+    now?: Date;
+}): TelegramActivationMarker;
+export declare function observedTelegramActivationMarker(settings: NotificationSettingsReader, botToken: string, chatId: string): TelegramActivationMarker | undefined;
+/** Persist one durable marker without discarding markers for other identities. */
+export declare function persistTelegramActivationMarker(settings: NotificationConfigurationWriter, marker: TelegramActivationMarker): Promise<SettingsAtomicReceipt>;
+/** Clear only the exact marker that was safely reconciled. */
+export declare function clearTelegramActivationMarker(settings: NotificationConfigurationWriter, marker: TelegramActivationMarker): Promise<void>;
+export type CompleteNonTelegramAdapter = "discord" | "slack";
+export type SaveTelegramInactiveAvailability = {
+    available: true;
+};
+/**
+ * Telegram-specific activation markers let Save inactive preserve globally
+ * enabled Discord and Slack adapters, so the action is always available.
+ */
+export declare function getSaveTelegramInactiveAvailability(_settings: NotificationSettingsReader): SaveTelegramInactiveAvailability;
+export type SaveTelegramInactiveResult = {
+    status: "saved_inactive";
+    receipt: SettingsAtomicReceipt;
+};
+/**
+ * Atomically persist Telegram credentials with a non-secret inactive marker.
+ * Global notifications are disabled only when Telegram is the sole complete adapter.
+ */
+export declare function saveTelegramInactive(input: {
+    settings: NotificationConfigurationWriter;
+    botToken: string;
+    chatId: string;
+}): Promise<SaveTelegramInactiveResult>;
+export interface TelegramRemovalRuntime {
+    /** Stops the local endpoint, unregisters its root, and stops an unreferenced old daemon. */
+    stopAndUnregister(): Promise<void>;
+}
+/**
+ * Remove Telegram credentials without disturbing other adapters. Runtime
+ * teardown is intentionally first: a failed teardown leaves durable credentials
+ * untouched rather than orphaning an old daemon/root behind a successful delete.
+ */
+export declare function removeTelegramConfiguration(input: {
+    settings: NotificationConfigurationWriter;
+    removal: TelegramRemovalRuntime;
+}): Promise<{
+    receipt: SettingsAtomicReceipt;
+    globallyDisabled: boolean;
+}>;
+/** Detailed outcome of checking or reconnecting the Telegram daemon after a durable commit. */
+export type TelegramDaemonReconnectOutcome = EnsureTelegramDaemonDetailedResult;
+/**
+ * The session controller must not resolve `enterBlockedRuntime` until its
+ * current endpoint has stopped and been removed. This lets callers report a
+ * blocked save only after no further frames can reach the foreign owner.
+ */
+export interface NotificationRuntimeController {
+    /** Resolves only after the current endpoint is stopped and removed. */
+    enterBlockedRuntime(): Promise<unknown>;
+    clearBlockedRuntime(): Promise<unknown>;
+    reconcileCurrentSession(): Promise<unknown>;
+}
+export interface TelegramPostCommitActivation {
+    controller: NotificationRuntimeController;
+    reconnect: () => Promise<TelegramDaemonReconnectOutcome>;
+    /** Durable Telegram-only marker write after the endpoint has stopped. */
+    persistInactive(marker: TelegramActivationMarker): Promise<SettingsAtomicReceipt>;
+    /** Remove the exact activation marker only after a safe reconnect. */
+    clearInactive(marker: TelegramActivationMarker): Promise<void>;
+    marker: TelegramActivationMarker;
+}
+export type PostCommitTelegramActivationResult = {
+    status: "activated";
+    reconnect: Exclude<TelegramDaemonReconnectOutcome, "blocked_identity">;
+} | {
+    status: "blocked_identity";
+    message: string;
+    restore(): Promise<BlockedTelegramRestoreResult>;
+    retainCommitted(): void;
+};
+export type BlockedTelegramRestoreResult = {
+    status: "restored";
+    reconnect: TelegramDaemonReconnectOutcome;
+} | {
+    status: "conflict";
+    paths: readonly string[];
+} | {
+    status: "discarded";
+} | {
+    status: "still_blocked";
+};
+/**
+ * Complete a committed Telegram update in the required order: identity
+ * reconnect first, normal session reconciliation second. A post-commit foreign
+ * owner race stops the endpoint, durably marks only that Telegram identity
+ * inactive, then exposes an ordered CAS restore/retain choice.
+ */
+export declare function reconcileCommittedTelegramConfiguration(input: {
+    receipt: SettingsAtomicReceipt;
+    activation: TelegramPostCommitActivation;
+    inactiveMarkerToClear?: TelegramActivationMarker;
+}): Promise<PostCommitTelegramActivationResult>;
+export type SaveTelegramConfigurationResult = {
+    status: "cancelled";
+    preflight: ProposedTelegramIdentity;
+    guidance: string;
+} | SaveTelegramInactiveResult | {
+    status: "saved";
+    receipt: SettingsAtomicReceipt;
+    preflight: ProposedTelegramIdentity;
+} | PostCommitTelegramActivationResult;
+/**
+ * Guard a Telegram setup commit with proposed-identity preflight. Foreign and
+ * unreadable ownership are cancel-by-default and make no configuration changes.
+ */
+export declare function saveTelegramConfiguration(input: {
+    settings: NotificationConfigurationWriter;
+    botToken: string;
+    chatId: string;
+    chatDisplay?: string;
+    /** Explicitly persist credentials disabled after a foreign/unknown preflight; otherwise cancel remains the default. */
+    saveInactive: boolean;
+    preflight?: (input: Omit<ProposedTelegramIdentityPreflightInput, "settings">) => Promise<ProposedTelegramIdentity>;
+    activation?: TelegramPostCommitActivation;
+}): Promise<SaveTelegramConfigurationResult>;

package/dist/types/sdk/bus/notification-service.d.ts

@@ -0,0 +1,233 @@
+import type { WriteFileOptions } from "node:fs";
+import type { Settings } from "../../config/settings";
+/**
+ * Strip secrets from a human-facing diagnostic string. Redacts the configured
+ * bot token (exact match) and any token-shaped substring so health/test details
+ * can never leak a credential regardless of where the string originated.
+ */
+export declare function sanitizeDiagnostic(text: string, token?: string): string;
+/** Identity evidence required to remove precisely the endpoint that was inspected. */
+export interface NotificationEndpointFileIdentity {
+    dev: bigint;
+    ino: bigint;
+    size: bigint;
+    mtimeNs: bigint;
+    sha256: string;
+}
+export interface NotificationEndpointFile {
+    bytes: Buffer;
+    identity: NotificationEndpointFileIdentity;
+}
+export interface NotificationExactUnlinkResult {
+    ok: boolean;
+    code?: string;
+    detachedPath?: string;
+    /** A live publisher successor retained after an exact-unlink race. */
+    retainedSuccessorPath?: string;
+    /** An internal exchange placeholder whose verified cleanup failed. */
+    retainedPlaceholderPath?: string;
+    /** A cleanup entry whose identity could not be verified after a race. */
+    retainedUnknownPath?: string;
+}
+/** Read one regular file together with the identity required for exact removal. */
+export declare function readNotificationEndpointFile(file: string): Promise<NotificationEndpointFile>;
+/** Bump when the native exact-deletion identity contract changes. */
+export declare const NATIVE_PATH_IDENTITY_CONTRACT_VERSION = 1;
+export declare function exactUnlinkNotificationFile(file: string, identity: NotificationEndpointFileIdentity, quarantineName: string): NotificationExactUnlinkResult;
+/** Minimal filesystem surface the service needs; injectable for tests. */
+export interface NotificationServiceFs {
+    readdir(dir: string): Promise<string[]>;
+    readFile(file: string, encoding: "utf8"): Promise<string>;
+    readEndpointFile(file: string): Promise<NotificationEndpointFile>;
+    exactUnlink(file: string, identity: NotificationEndpointFileIdentity): Promise<NotificationExactUnlinkResult>;
+    unlink(file: string): Promise<void>;
+    writeFile?(file: string, data: string, opts?: WriteFileOptions): Promise<void>;
+    stat?(file: string): Promise<{
+        mtimeMs: number;
+    }>;
+}
+/** Injectable dependencies shared across service operations. */
+export interface NotificationServiceDeps {
+    fs?: NotificationServiceFs;
+    now?: () => number;
+    pidAlive?: (pid: number) => boolean;
+    fetchImpl?: typeof fetch;
+    apiBase?: string;
+}
+export interface AdapterConfigView {
+    botTokenMasked: string;
+    channel: string | undefined;
+    configured: boolean;
+}
+export interface NotificationStatusReport {
+    enabled: boolean;
+    redact: boolean;
+    verbosity: "lean" | "verbose";
+    globallyConfigured: boolean;
+    telegram: AdapterConfigView & {
+        tokenFingerprint: string | undefined;
+    };
+    discord: AdapterConfigView;
+    slack: AdapterConfigView;
+}
+/** Build a secret-safe structured status snapshot from settings. */
+export declare function buildNotificationStatusReport(settings: Settings): NotificationStatusReport;
+/** Render a status report as human-readable lines (no secrets). */
+export declare function formatNotificationStatusReport(report: NotificationStatusReport): string;
+export type HealthLevel = "ok" | "warn" | "error";
+export interface HealthCheck {
+    name: string;
+    level: HealthLevel;
+    detail: string;
+}
+export interface DaemonHealth {
+    present: boolean;
+    ownerId: string | undefined;
+    pid: number | undefined;
+    alive: boolean;
+    heartbeatFresh: boolean;
+    identityMatches: boolean;
+    stopped: boolean;
+    heartbeatAt: number | undefined;
+    heartbeatAgeMs: number | undefined;
+    generation: number | undefined;
+    currentGeneration: number;
+    generationRelation: DaemonGenerationRelation;
+}
+export type DaemonGenerationRelation = "pre_generation" | "older" | "current" | "newer" | "unknown";
+export interface EndpointHealth {
+    total: number;
+    live: number;
+    dead: number;
+    unknown: number;
+    unreadable: number;
+}
+export interface NotificationHealthReport {
+    overall: HealthLevel;
+    configured: boolean;
+    checks: HealthCheck[];
+    daemon: DaemonHealth;
+    endpoints: EndpointHealth;
+    reachability: {
+        probed: boolean;
+        ok: boolean;
+        detail: string;
+    };
+}
+export interface HealthOptions {
+    settings: Settings;
+    stateRoot?: string;
+    deps?: NotificationServiceDeps;
+    /** When true and Telegram is configured, probe the Bot API (getMe) for reachability. */
+    probe?: boolean;
+}
+/** Structural (offline-by-default) health of the notification subsystem. */
+export declare function checkNotificationHealth(opts: HealthOptions): Promise<NotificationHealthReport>;
+/** Render a health report as human-readable lines (no secrets). */
+export declare function formatNotificationHealthReport(report: NotificationHealthReport): string;
+export interface NotificationTestResult {
+    ok: boolean;
+    adapter: "telegram";
+    chatId: string | undefined;
+    detail: string;
+}
+export interface TestOptions {
+    settings: Settings;
+    deps?: NotificationServiceDeps;
+    text?: string;
+}
+/** Send a one-off test notification through the configured Telegram adapter. */
+export declare function sendNotificationTest(opts: TestOptions): Promise<NotificationTestResult>;
+/** Render a test result as a single human-readable line (no secrets). */
+export declare function formatNotificationTestResult(result: NotificationTestResult): string;
+export interface RecoveredEndpoint {
+    sessionId: string;
+    pid: number | undefined;
+    reason: "stale-flag" | "dead-pid";
+}
+export type DaemonRecoveryAction = "none" | "cleared-dead-owner-lock" | "left-active" | "left-contended" | "owner-superseded" | "orphan-lock-left";
+export interface NotificationRecoveryReport {
+    endpointsScanned: number;
+    endpointsRemoved: RecoveredEndpoint[];
+    endpointsKept: number;
+    endpointsUnreadable: number;
+    endpointsDetached?: string[];
+    /** Successor paths retained after an exact-unlink race, distinct from stale quarantines. */
+    endpointsRetainedSuccessors?: string[];
+    /** Internal exchange placeholders retained after verified cleanup failure. */
+    endpointsRetainedPlaceholders?: string[];
+    /** Cleanup entries retained with unverified or mismatching identity. */
+    endpointsRetainedUnknown?: string[];
+    daemon: {
+        action: DaemonRecoveryAction;
+        detail: string;
+        ownerId: string | undefined;
+        pid: number | undefined;
+    };
+}
+export interface RecoveryOptions {
+    settings: Settings;
+    stateRoot?: string;
+    deps?: NotificationServiceDeps;
+}
+export interface DaemonTransitionLock {
+    pid: number;
+    incarnation: string;
+    createdAt: number;
+    /** Unique fencing generation for this particular transition acquisition. */
+    token: string;
+}
+type TransitionMarkerFs = {
+    readFile(file: string, encoding: "utf8"): Promise<string>;
+    writeFile?(file: string, data: string, opts?: WriteFileOptions): Promise<void>;
+    readEndpointFile?(file: string): Promise<NotificationEndpointFile>;
+    exactUnlink?(file: string, identity: NotificationEndpointFileIdentity): Promise<NotificationExactUnlinkResult>;
+};
+/** True only while the exact transition acquisition still occupies the marker path. */
+export declare function daemonTransitionLockIsHeld(input: {
+    fs: Pick<TransitionMarkerFs, "readFile" | "readEndpointFile">;
+    path: string;
+    lock: DaemonTransitionLock;
+}): Promise<boolean>;
+/** Removes only the caller's exact marker through the identity-bound detach primitive. */
+export declare function releaseDaemonTransitionLock(input: {
+    fs: TransitionMarkerFs;
+    path: string;
+    lock: DaemonTransitionLock;
+}): Promise<boolean>;
+/**
+ * Acquire the daemon lifecycle transition lock using durable owner metadata.
+ * The full marker is published in the single O_EXCL write which reserves it;
+ * canonical markers are detached only through their captured filesystem identity.
+ *
+ * Malformed and empty markers deliberately remain blocked regardless of age. They
+ * have no owner provenance, so reclaiming them could detach a generation-6 empty
+ * reservation while its paused legacy writer can still resume. Operators must
+ * manually clean up such legacy debris after confirming no legacy process remains.
+ */
+export declare function acquireDaemonTransitionLock(input: {
+    fs: TransitionMarkerFs;
+    path: string;
+    pid: number;
+    pidAlive: (pid: number) => boolean;
+    pidIncarnation: (pid: number) => string | undefined;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    retries?: number;
+    retryDelayMs?: number;
+    randomToken?: () => string;
+}): Promise<DaemonTransitionLock | undefined>;
+/**
+ * Ownership-protected cleanup. Removes only DEAD-owner artifacts:
+ * per-session endpoint files with positive proof of death (a stale tombstone or
+ * a dead recorded pid), and a daemon lock whose recorded owner is confirmed
+ * dead. A PID-less endpoint is treated as unknown (not dead) and kept. The
+ * daemon lock is removed through {@link removeDeadOwnerLock}, an owner-bound
+ * primitive that re-checks ownership under the daemon steal-mutex so it can
+ * never race a concurrent takeover. Never removes a live owner's lock, never
+ * deletes unreadable files, and never kills a process.
+ */
+export declare function recoverNotifications(opts: RecoveryOptions): Promise<NotificationRecoveryReport>;
+/** Render a recovery report as human-readable lines (no secrets). */
+export declare function formatNotificationRecoveryReport(report: NotificationRecoveryReport): string;
+export {};

package/dist/types/sdk/bus/operator-runtime.d.ts

@@ -0,0 +1,52 @@
+export interface NotificationOperatorTimerDeps {
+    now?: () => number;
+    setTimeoutImpl?: typeof setTimeout;
+    clearTimeoutImpl?: typeof clearTimeout;
+    setIntervalImpl?: typeof setInterval;
+    clearIntervalImpl?: typeof clearInterval;
+}
+export interface NotificationOperatorRuntimeState {
+    running: boolean;
+    stopRequested: boolean;
+    activeAbort: boolean;
+}
+export interface OperatorBackoffOptions {
+    initialMs: number;
+    maxMs: number;
+    factor?: number;
+}
+export declare class OperatorBackoffPolicy {
+    #private;
+    constructor(opts: OperatorBackoffOptions);
+    next(): number;
+    reset(): void;
+    get currentMs(): number;
+}
+export interface OperatorRoute<TContext> {
+    name: string;
+    matches(event: Record<string, unknown>): boolean;
+    handle(context: TContext, event: Record<string, unknown>): Promise<void> | void;
+}
+export declare class OperatorEventRouter<TContext> {
+    readonly routes: OperatorRoute<TContext>[];
+    add(input: OperatorRoute<TContext>): this;
+    dispatch(context: TContext, event: Record<string, unknown>): Promise<boolean>;
+}
+export declare class NotificationOperatorRuntime {
+    #private;
+    constructor(deps?: NotificationOperatorTimerDeps);
+    get state(): NotificationOperatorRuntimeState;
+    start(): void;
+    stop(): void;
+    requestStop(): void;
+    get running(): boolean;
+    get stopRequested(): boolean;
+    createAbortController(): AbortController;
+    clearAbortController(controller: AbortController): void;
+    startInterval(name: string, intervalMs: number, tick: () => void): void;
+    stopInterval(name: string): void;
+    stopAllIntervals(): void;
+    runExclusive(name: string, fn: () => Promise<void>): Promise<void>;
+    sleep(ms: number, signal?: AbortSignal): Promise<void>;
+    now(): number;
+}