@gajae-code/coding-agent 0.13.3 → 0.14.0

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

@@ -6,9 +6,9 @@ import { HEARTBEAT_TTL_MS } from "./daemon-paths";
 import { type DaemonTransitionLock, type NotificationEndpointFile, type NotificationEndpointFileIdentity, type NotificationExactUnlinkResult } from "./notification-service";
 import { type DaemonProcessReference } from "./telegram-daemon-control";
 import { type TelegramSetupPreflight } from "./telegram-setup";
-export { DAEMON_GENERATION, NOTIFICATION_PROTOCOL_VERSION, SERVING_EPOCH } from "./telegram-daemon-contract";
-import { type ControlServerLike, type LifecycleControlServerFactory } from "./lifecycle-control-runtime";
-import type { OrchestratorDeps } from "./lifecycle-orchestrator";
+export { DAEMON_GENERATION, NOTIFICATION_EVENT_SCHEMA_VERSION, NOTIFICATION_PROTOCOL_VERSION, SDK_LIFECYCLE_ROUTER_PROTOCOL_VERSION, SERVING_EPOCH, TELEGRAM_TRANSPORT_GENERATION, } from "./telegram-daemon-contract";
+import { type AgentDirSessionLifecycleService } from "../lifecycle/client";
+import { type NotificationSubscription, type SessionRouterProviderDeps } from "../router/session-router";
 import { NotificationOperatorRuntime } from "./operator-runtime";
 import { type AliasTable, type CallbackRoute } from "./telegram-reference";
 import { type TopicEndpointBinding, type TopicRegistryCasAuthority, type TopicRegistryState } from "./topic-registry";
@@ -29,7 +29,6 @@ export interface DaemonState {
     chatId: string;
     startedAt: number;
     heartbeatAt: number;
-    roots: string[];
     /**
      * Present only for the Windows source-launch handoff. `pid` starts as this
      * short-lived launcher PID and may be rebound exactly once to the daemon PID.
@@ -82,8 +81,8 @@ export interface TelegramDaemonFs {
     lstat?(path: string, opts: {
         bigint: true;
     }): Promise<ExactFileStat>;
-    readEndpointFile?(path: string): Promise<NotificationEndpointFile>;
-    exactUnlink?(path: string, identity: NotificationEndpointFileIdentity, quarantineName?: string): Promise<NotificationExactUnlinkResult>;
+    readEndpointFile?(file: string): Promise<NotificationEndpointFile>;
+    exactUnlink?(file: string, identity: NotificationEndpointFileIdentity): Promise<NotificationExactUnlinkResult>;
 }
 export interface SpawnResult {
     pid?: number;
@@ -147,26 +146,7 @@ export declare function reloadReservationLockOptions(input: {
 };
 export declare const BTW_QUESTION_MAX_UNICODE_SCALARS = 4096;
 export declare const BTW_QUESTION_MAX_UTF8_BYTES = 16384;
-export declare function endpointAuthorityDigest(url: string, token: string, connectionIdentity?: string): string;
 export { type DaemonPaths, daemonPaths } from "./daemon-paths";
-export declare function deriveLifecycleAuditRedactionKey(botToken: string): Uint8Array;
-/**
- * Attach session-lifecycle control (create/close/resume) to the running daemon.
- *
- * Wires an already-started, authenticated control server to the lifecycle
- * orchestrator with real daemon-side effects (tmux launcher / force-close /
- * resume), a durable fsynced idempotency ledger + audit JSONL under the agent
- * notifications dir, and strict paired-chat gating. The control server itself
- * (NotificationControlServer) is owned/started by the daemon process; this
- * function only connects it to policy. Returns the orchestrator deps for tests.
- */
-export declare function startDaemonLifecycleControl(input: {
-    controlServer: ControlServerLike;
-    pairedChatId: string;
-    agentDir: string;
-    auditRedactionKey: Uint8Array;
-    env?: NodeJS.ProcessEnv;
-}): OrchestratorDeps;
 export declare class TopicRegistryDurabilityUnavailableError extends Error {
     readonly code = "durability_unavailable";
     constructor(cause: unknown);
@@ -326,119 +306,8 @@ export declare function renewOwnerHeartbeatSidecar(input: {
      */
     attachedEndpoints?: number;
 }): Promise<OwnerHeartbeatSidecarRenewal>;
-export interface NotificationRootRegistration {
-    root?: string;
-    managed?: boolean;
-    token?: string;
-}
-export declare function readNotificationRootRegistration(input: {
-    settings: Settings;
-    sessionId: string;
-    fs?: TelegramDaemonFs;
-}): Promise<NotificationRootRegistration>;
-export interface RegisterNotificationRootResult {
-    root: string;
-    /** Per-registration ownership token fencing a stale same-session cleanup from deleting a live replacement registration. */
-    token: string;
-}
-export declare function registerNotificationRoot(input: {
-    settings: Settings;
-    cwd: string;
-    sessionId: string;
-    fs?: TelegramDaemonFs;
-}): Promise<RegisterNotificationRootResult>;
-export interface UnregisterNotificationRootResult {
-    root: string;
-    remainingRoots: number;
-    /** Opaque fingerprint of the exact registry written by this successful unregister. */
-    registryFingerprint?: string;
-}
-/** Remove one session's Telegram scan root without disturbing other live session roots. */
-export declare function unregisterNotificationRoot(input: {
-    settings: Settings;
-    cwd: string;
-    sessionId: string;
-    fs?: TelegramDaemonFs;
-    /** Ownership token minted by this runtime's own registration; a stale cleanup presenting an older token never deletes a replacement registration. */
-    registrationToken?: string;
-}): Promise<UnregisterNotificationRootResult>;
-/** Run an action while the roots registry lock excludes any registration or unregister. */
-export declare function withNotificationRootRegistryFence(input: {
-    settings: Settings;
-    registryFingerprint: string;
-    action: () => Promise<void>;
-    fs?: TelegramDaemonFs;
-}): Promise<boolean>;
-/**
- * Leak artifact prefixes left when native exact-unlink cleanup is retained
- * (#2956). Nothing previously reaped these; they accumulate in the notifications
- * directory across ownership transitions.
- */
-export declare const NOTIFICATION_LEAK_ARTIFACT_PREFIXES: readonly [".gjc-delete-daemon-transition-", ".gjc-exact-unlink-placeholder-", ".gjc-delete-notification-endpoint-", ".gjc-delete-notification-staging-temp-"];
-/** Grace window before a leak artifact is reaped (covers in-flight unlinks). */
-export declare const NOTIFICATION_LEAK_ARTIFACT_GRACE_MS: number;
 /** True when a path is permanently gone (not a transient I/O blip). */
 export declare function isPermanentMissingPathError(error: unknown): boolean;
-/** A publication staging claim recovered from an abandoned temp's name. */
-export interface NotificationStagingTempClaim {
-    /** Published sibling this temp was staged for. */
-    destination: string;
-    /** PID of the process that staged it. */
-    pid: number;
-    /** Wall-clock ms the publisher recorded when it staged the temp. */
-    stagedAtMs: number;
-}
-/**
- * Recover the publication claim encoded in a staging temp's name, or
- * `undefined` when `name` is not a staging temp or its PID/timestamp fields are
- * not usable integers. An unparseable claim is never reaped.
- */
-export declare function parseNotificationStagingTemp(name: string): NotificationStagingTempClaim | undefined;
-export declare function isNotificationLeakArtifactName(name: string): boolean;
-/**
- * Drop permanently missing scan roots from the durable registry under the roots
- * lock. Session map entries that pointed only at those roots are removed too.
- */
-export declare function pruneMissingNotificationRoots(input: {
-    settings: Settings;
-    fs?: TelegramDaemonFs;
-    /** When set, only these roots are considered; otherwise every registered root is probed. */
-    candidates?: readonly string[];
-}): Promise<{
-    pruned: string[];
-    remaining: number;
-}>;
-/**
- * Reap retained exact-unlink / ownership-transition quarantine files older than
- * the grace window from the notifications directory, plus publication staging
- * temps whose publisher is provably dead.
- */
-export declare function reapStaleNotificationArtifacts(input: {
-    settings: Settings;
-    fs?: TelegramDaemonFs;
-    now?: () => number;
-    graceMs?: number;
-    /** Liveness seam used to prove a staging temp's publisher is dead. */
-    pidAlive?: (pid: number) => boolean;
-}): Promise<{
-    removed: string[];
-    skipped: number;
-}>;
-/**
- * Startup / ownership self-heal: prune dead roots and reap leak artifacts so
- * `gjc daemon reload` recovers a degraded install without manual surgery (#2956).
- */
-export declare function healTelegramDaemonNotificationState(input: {
-    settings: Settings;
-    fs?: TelegramDaemonFs;
-    now?: () => number;
-    graceMs?: number;
-    /** Liveness seam used to prove a staging temp's publisher is dead. */
-    pidAlive?: (pid: number) => boolean;
-}): Promise<{
-    prunedRoots: string[];
-    removedArtifacts: string[];
-}>;
 export declare function hasSafeDaemonStateShape(state: unknown): state is DaemonState;
 type ParentDaemonStateBase = Omit<DaemonState, "incarnation" | "acquisitionId" | "ownershipPhase" | "generation" | "launcherPid"> & {
     incarnation?: undefined;
@@ -504,7 +373,6 @@ export declare function isCurrentCompatibleOwner(input: {
 }): boolean;
 export declare function acquireDaemonOwnership(input: {
     settings: Settings;
-    roots?: string[];
     tokenFingerprint: string;
     chatId: string;
     fs?: TelegramDaemonFs;
@@ -648,8 +516,6 @@ export declare function markDaemonOwnerStopped(input: {
 }): Promise<boolean>;
 /** Read the persisted daemon ownership state (or undefined when absent). */
 export declare function readDaemonState(settings: Pick<Settings, "getAgentDir">, fs?: TelegramDaemonFs): Promise<DaemonState | undefined>;
-/** Read the persisted notification roots list. */
-export declare function readDaemonRoots(settings: Pick<Settings, "getAgentDir">, fs?: TelegramDaemonFs): Promise<string[]>;
 /** Injectable readers for {@link resolveTelegramSetupPreflight}, defaulting to the real OS/state probes. */
 export interface ResolveTelegramSetupPreflightDeps {
     readDaemonState?: (settings: Settings) => Promise<DaemonState | undefined>;
@@ -668,7 +534,6 @@ export interface ResolveTelegramSetupPreflightDeps {
 export declare function resolveTelegramSetupPreflight(settings: Settings, deps?: ResolveTelegramSetupPreflightDeps): Promise<TelegramSetupPreflight>;
 export interface TelegramSpawnOwnerInput {
     settings: Settings;
-    roots?: string[];
     tokenFingerprint: string;
     chatId: string;
     /** Ephemeral outbound-only validation destination for this owner launch. */
@@ -714,12 +579,7 @@ export declare function buildTelegramDaemonSpawnArgs(input: {
     args: string[];
     runtime: DaemonRuntimeInfo;
 };
-/**
- * Acquire ownership for the given Telegram identity and, if acquired, spawn a
- * fresh detached daemon process. Does NOT register notification roots; callers
- * that own a session (autostart) register roots separately, while reload reuses
- * already-persisted roots.
- */
+/** Acquire ownership for the configured Telegram daemon and spawn a detached owner. */
 export declare function spawnTelegramDaemonOwner(input: TelegramSpawnOwnerInput, deps?: TelegramDaemonDeps): Promise<TelegramSpawnOwnerResult>;
 /**
  * Owner-bound reclamation of a confirmed-dead daemon owner, mirroring the
@@ -733,37 +593,23 @@ export type DeadOwnerRecoveryResult = {
     reason: "cleared";
 } | {
     recovered: false;
-    reason: "not-confirmed-dead" | "unsafe-lock" | "transition-contended" | "owner-superseded" | "unsafe-endpoint" | "endpoint-changed" | "endpoint-directory-unreadable" | "lock-changed";
+    reason: "not-confirmed-dead" | "unsafe-lock" | "transition-contended" | "lock-changed";
 };
-/** Preflight cleanup for a confirmed-dead owner, with identity-bound removal. */
+/** Preflight cleanup for a confirmed-dead owner. */
 export declare function reclaimDeadDaemonOwner(input: {
     settings: Settings;
-    endpointDir?: string;
     fs?: TelegramDaemonFs;
     now?: () => number;
     pidAlive?: (pid: number) => boolean;
     pidIncarnation?: (pid: number) => string | undefined;
 }): Promise<DeadOwnerRecoveryResult>;
-/**
- * Ensure a configured daemon owns this session root, preserving ownership safety
- * while exposing whether a #2028 generation handoff was required.
- */
+/** Ensure the configured Telegram owner is running. */
 export declare function ensureTelegramDaemonRunningDetailed(input: {
     settings: Settings;
-    cwd: string;
-    sessionId: string;
-    registerRoot?: boolean;
-    /** Receives each registration this ensure operation minted so the caller can fence its own later cleanup. */
-    onRegistered?: (registration: RegisterNotificationRootResult) => void;
 }, deps?: TelegramDaemonDeps): Promise<EnsureTelegramDaemonDetailedResult>;
-/**
- * Legacy compatibility mapping for callers that only distinguish ownership from
- * attachment. New orchestration should use {@link ensureTelegramDaemonRunningDetailed}.
- */
+/** Map owner startup to the public daemon result. */
 export declare function ensureTelegramDaemonRunning(input: {
     settings: Settings;
-    cwd: string;
-    sessionId: string;
 }, deps?: TelegramDaemonDeps): Promise<EnsureDaemonResult>;
 export interface BotApi {
     call(method: string, body: unknown, opts?: {
@@ -775,7 +621,7 @@ export interface TelegramTransportOptions {
     botToken: string;
     apiBase?: string;
     fetchImpl?: typeof fetch;
-    setTimeoutImpl?: typeof setTimeout;
+    setTimeoutImpl?: (callback: () => void, ms?: number) => Timer | NodeJS.Timeout;
 }
 /** Telegram Bot API transport: HTTP JSON/multipart details stay out of daemon orchestration. */
 export declare class TelegramBotTransport implements BotApi {
@@ -826,12 +672,15 @@ export declare class TelegramUpdatePoller {
     pollOnceResult(signal?: AbortSignal): Promise<TelegramPollResult>;
 }
 /** Mutable dispatch state shared by session frames and inbound Telegram updates. */
+export type InboundReactionAction = "none" | "queued" | "consumed" | "retract";
+/** Exact daemon reaction correction for a session-side inbound acknowledgement. */
+export declare function inboundReactionAction(state: unknown, hasTarget: boolean): InboundReactionAction;
 export declare class TelegramEventDispatchState {
     readonly busy: Set<string>;
     readonly inboundReactions: Map<number, {
         messageId: number;
         socketLease?: {
-            session: SessionSocket;
+            session: AttachmentSession;
             token: number;
             logicalSessionId: string;
         };
@@ -863,9 +712,8 @@ export interface TelegramDaemonOptions {
     apiBase?: string;
     fetchImpl?: typeof fetch;
     fs?: TelegramDaemonFs;
-    WebSocketImpl?: typeof WebSocket;
     now?: () => number;
-    setTimeoutImpl?: typeof setTimeout;
+    setTimeoutImpl?: (callback: () => void, ms?: number) => Timer | NodeJS.Timeout;
     clearTimeoutImpl?: typeof clearTimeout;
     setIntervalImpl?: typeof setInterval;
     clearIntervalImpl?: typeof clearInterval;
@@ -875,30 +723,14 @@ export interface TelegramDaemonOptions {
     idleTimeoutMs?: number;
     /** TTL for durable topic-adoption intents (default 10 minutes). Observed, not a fixed contract. */
     adoptionIntentTtlMs?: number;
-    scanIntervalMs?: number;
     pid?: number;
-    /** Liveness probe for skipping dead-PID endpoint records in {@link TelegramNotificationDaemon.scanRoots}. */
-    pidAlive?: (pid: number) => boolean;
     pidIncarnation?: (pid: number) => string | undefined;
     botApi?: BotApi;
     control?: DaemonControlHooks;
-    /**
-     * Factory for the session-lifecycle control server. Defaults to the real
-     * native NotificationControlServer; tests inject a fake to verify the
-     * owner-bound start/stop lifecycle without a socket. When `undefined` AND no
-     * default applies (e.g. lifecycle control disabled), no control server starts.
-     */
-    createLifecycleControlServer?: LifecycleControlServerFactory | null;
-    /**
-     * Test seam for observing the exact production lifecycle dependency input.
-     * Production defaults to {@link buildOrchestratorDeps}.
-     */
-    createLifecycleOrchestratorDeps?: (input: {
-        pairedChatId: string;
-        agentNotificationsDir: string;
-        sessionsRoot: string;
-        auditRedactionKey: Uint8Array;
-    }) => OrchestratorDeps;
+    /** SDK-owned lifecycle service seam; production constructs it from agentDir. */
+    createLifecycleService?: (agentDir: string) => AgentDirSessionLifecycleService;
+    /** Narrow Router transport seams; provider callbacks are owned by Telegram. */
+    routerDeps?: SessionRouterProviderDeps;
     /** Rich text promotion (enabled by default; see rich-render.ts). */
     rich?: {
         enabled: boolean;
@@ -914,13 +746,20 @@ export interface TelegramDaemonOptions {
     /** Controls which Telegram sends play an audible notification. Defaults to all. */
     sound?: "all" | "important" | "none";
     /**
-     * Per-session Telegram forum-topic naming. `nameTemplate` supports the
-     * `{repo}`, `{branch}`, and `{title}` placeholders; unset preserves the
-     * built-in `{repo}/{branch} - {title}` composition and its fallbacks.
+     * Telegram forum-topic naming. `nameTemplate` supports the `{repo}`,
+     * `{branch}`, and `{title}` placeholders; unset uses the GJC session title
+     * and falls back to a short session id while the title is unavailable.
      */
     topics?: {
         nameTemplate?: string;
     };
+    /**
+     * Require every connected session to explicitly advertise Telegram topic
+     * eligibility in its identity header. Production daemon owners MUST enable
+     * this; the default is permissive only for direct embedded legacy clients and
+     * tests, and is never a provenance input supplied by notification factories.
+     */
+    requireTelegramTopicEligibility?: boolean;
     /**
      * Optional compare-and-set store for installations that share topic state
      * across hosts. When configured, every publication is fenced by it.
@@ -928,44 +767,55 @@ export interface TelegramDaemonOptions {
     topicRegistryAuthority?: TopicRegistryCasAuthority;
     /** Stable host-local identity. Required whenever a shared authority is configured. */
     installationHostId?: string;
+    /**
+     * Orphan-owner reconciliation seam. Production wires the bounded orphan reap
+     * (marker-registry-authorized process-group termination of superseded daemon
+     * owners) so the daemon fences stale pollers before it becomes poll-capable
+     * and re-runs reconciliation periodically. Injectable for deterministic tests.
+     */
+    orphanReap?: () => Promise<void>;
+    /** Periodic reconciliation cadence; defaults to ORPHAN_REAP_INTERVAL_MS. */
+    orphanReapIntervalMs?: number;
 }
-interface SessionSocket {
-    /** Immutable key of the transport endpoint that owns this socket. */
+interface AttachmentSession {
+    /** Provider presentation metadata bound to one provider-local subscription. */
     sessionId: string;
-    /** Current logical session carried by valid threaded frames on this transport. */
     logicalSessionId: string;
-    /** Endpoint metadata proved this logical id belongs to this discovery record. */
+    /**
+     * True only when the connected host explicitly owns a Telegram forum topic;
+     * only such producer-admitted sessions may own forum topics.
+     */
+    telegramTopicsEnabled: boolean;
     logicalSessionIdTrusted: boolean;
-    token: string;
-    endpointKey: string;
-    endpointDigest: string;
-    hostGeneration: number;
-    ws: WebSocket;
-    /** Timestamp (via opts.now) at which this socket began connecting. */
-    connectingSince: number;
+    readonly subscription: NotificationSubscription;
+    readonly transport: {
+        readyState: number;
+        send(data: string): Promise<void>;
+        close(): void;
+    };
+    /** Opaque local identity used only to fence presentation state. */
+    attachmentKey: string;
+    /** Immutable SDK lifecycle generation from Router; never changed by replay payloads. */
+    lifecycleGeneration: number;
+    /** Telegram event/replay generation used only for cursor and publication ids. */
+    replayGeneration: number;
     pending: Map<string, {
         sessionId: string;
         actionId: string;
     }>;
-    /** True once the server advertised the `client_ping_pong` capability. */
     capable: boolean;
     ephemeralCapable: boolean;
-    /** Tool activity contract advertised by the connected host. */
     toolActivityCapability?: "v1" | "v2";
-    /** Timestamp (via opts.now) of the last received pong; seeds the TTL window. */
     lastPongAt: number;
-    /** Nonce of the most recent in-flight ping, if any. */
     awaitingNonce: string | undefined;
-    /** Per-session liveness interval handle (only set for capable sessions). */
-    pingTimer: ReturnType<typeof setInterval> | undefined;
-    /** Correlation id for the startup replay barrier. */
+    pingTimer: NodeJS.Timeout | undefined;
     replayId: string;
-    /** Sequence cursor sent by the current startup replay request. */
-    replaySinceSeq: number;
-    /** Queues live frames until startup replay is applied. */
     replayPending: boolean;
-    replayQueue: Record<string, unknown>[];
-    /** Trusted recovery may not route until its durable endpoint lease is committed. */
+    replayQueue: Array<{
+        frame: Record<string, unknown>;
+        publicationId?: string;
+    }>;
+    activePublicationId?: string;
     recoveryLease?: {
         state: "pending" | "authorized" | "rejected";
         logicalSessionId: string;
@@ -996,9 +846,8 @@ export declare class TelegramNotificationDaemon {
     private readonly replayToolActivityEpochs;
     private toolShutdownBarrier;
     private toolActivityAmbiguous;
-    readonly sessions: Map<string, SessionSocket>;
+    readonly sessions: Map<string, AttachmentSession>;
     private readonly runtime;
-    private readonly sessionRouter;
     private readonly pollConflictBackoff;
     private readonly loopBackoff;
     private running;
@@ -1010,11 +859,7 @@ export declare class TelegramNotificationDaemon {
     private readonly topics;
     /** Stable host-local identity; never persisted in shared topic authority. */
     private installationHostId;
-    /** Serializes registry snapshots so an older atomic write cannot overwrite newer rename state. */
-    /** Legacy sockets have no durable token, so explicit teardown is their revocation fence. */
-    private readonly droppedSessions;
     private topicsPersistQueue;
-    /** Serializes recovery compare/write/publish claims so competing endpoint migrations cannot durably diverge. */
     private recoveryBindingClaimQueue;
     /** Durable compensation fences retry under supervision until persistence succeeds. */
     private readonly compensationFenceRetries;
@@ -1035,16 +880,12 @@ export declare class TelegramNotificationDaemon {
     private readonly draftStream;
     /** Identity-bearing sessions by repo/branch surface, used to avoid transient duplicate topics. */
     private readonly topicOwnerByIdentity;
-    /** Ephemeral legacy topic owners retained across a same-socket config rekey. */
-    private readonly legacyTopicOwners;
     /** Preserved initiator topics must not route through a rekeyed transport. */
     private readonly preservedInitiatorTopics;
     /** Non-identity frames held until identity creates the correct thread. */
     private readonly pendingThreadedFrames;
     /** Durable endpoint leases for sessions that already sent an authorized session_closed. */
     private readonly closedEndpointKeys;
-    /** Exactly one authorized transport may route each recovered logical session. */
-    private readonly logicalSessionOwners;
     private nextSocketLeaseToken;
     /** True once the daemon has nudged the user to enable Threaded Mode. */
     private threadedFallbackNoticeSent;
@@ -1060,22 +901,6 @@ export declare class TelegramNotificationDaemon {
     private get busy();
     /** Inbound update id → originating Telegram message, for delivery reactions. */
     private get inboundReactions();
-    /**
-     * The owner-bound session-lifecycle control server (create/close/resume).
-     * Started in {@link run} after ownership is confirmed (so exactly one owner
-     * ever runs one), stopped in run()'s finally on any exit path.
-     */
-    private controlServer;
-    /** True while lifecycle control is active, so the loop keeps polling at idle. */
-    private lifecycleControlActive;
-    /** Control token (in-memory) the loopback client presents; never persisted/logged. */
-    private controlToken;
-    /** Loopback WS client to the daemon's own control endpoint (Option A real wire path). */
-    private controlClient;
-    /** Pending lifecycle responses awaiting a control-endpoint reply, by requestId. */
-    private readonly pendingLifecycle;
-    /** Monotonic counter for unique lifecycle request ids. */
-    private lifecycleSeq;
     /** Attempt tombstones live for the daemon lifetime so a commit key can never send twice. */
     private readonly selectedAckCache;
     private cacheSelectedAck;
@@ -1087,42 +912,44 @@ export declare class TelegramNotificationDaemon {
      * ~25s getUpdates timeout. Safe to call from a signal handler.
      */
     requestStop(_reason?: "reload" | "stop" | "signal"): void;
-    /**
-     * Start the owner-bound lifecycle control server and wire it to the
-     * orchestrator. Called from {@link run} ONLY after ownership is confirmed, so
-     * exactly one owner ever starts exactly one control server (no second poller
-     * / 409). A control-server failure degrades gracefully: the daemon keeps
-     * serving notifications without lifecycle control. Returns true when started.
-     */
-    private startLifecycleControl;
-    /** Stop the lifecycle control server (idempotent); called from run()'s finally. */
-    private stopLifecycleControl;
-    /**
-     * Connect the loopback control client and resolve responses by requestId.
-     * Resolves true once the socket is OPEN (bounded), false on error/timeout, so
-     * the caller only marks lifecycle control active when commands can be sent.
-     */
-    private connectControlClient;
-    /** Send a lifecycle frame over the loopback client and await the response. */
-    private submitLifecycleFrame;
-    private nextLifecycleRequestId;
-    /** Build an authenticated lifecycle frame from a parsed command + identity. */
-    private buildLifecycleFrame;
-    /**
-     * Handle a paired-chat /session_* command: validate (shared validator),
-     * route to the control endpoint, and reply with the outcome. Returns true
-     * when the message was a lifecycle command (so the caller stops processing).
-     */
+    /** Handle a paired-chat /session_* command through the SDK lifecycle service. */
     private handleLifecycleCommand;
     private refreshBotIdentity;
-    /** Map a lifecycle response/error to a user-facing message (G010 surfacing). */
-    private formatLifecycleResponse;
     private callBotApi;
     private validationTopicDestination;
     private readonly callBotApiClassified;
-    private botApiWithOutcomeCollector;
     constructor(opts: TelegramDaemonOptions);
-    private createSessionRouter;
+    /** @internal Test-only access to durable publication receipt transitions. */
+    publicationReceiptHarnessForTest(): {
+        claimPublication: (publicationId: string) => Promise<void>;
+        markPublicationAttempted: (publicationId: string) => Promise<void>;
+        markPublicationDelivered: (publicationId: string) => Promise<void>;
+        markPublicationRejected: (publicationId: string, definitiveProviderRejection?: boolean) => Promise<void>;
+        loadPresentationState: () => Promise<void>;
+        publicationShouldSuppress: (publicationId: string) => boolean;
+        publicationSettlement: (publicationId: string) => PromiseWithResolvers<void>;
+        settlePublication: (publicationId: string) => void;
+        drainPersistence: () => Promise<void>;
+    };
+    /** @internal Test-only access to attachment routing lifecycle transitions. */
+    attachmentRoutingHarnessForTest(): {
+        attach: (subscription: NotificationSubscription) => void;
+        remove: (subscription: NotificationSubscription, reason: "removed" | "replaced" | "replaced_same_generation") => Promise<void>;
+        ownsLogicalSession: (sessionId: string) => boolean;
+        cleanupReceipts: () => {
+            sessionId: string;
+            subscriptionId: string;
+            state: "pending" | "failed" | "completed";
+            reason?: string;
+        }[];
+    };
+    /** @internal Test-only access to the durable archive retry drain. */
+    archiveReconciliationHarnessForTest(): {
+        reconcilePendingTopicDeletes: () => Promise<void>;
+        archiveAuthorizedTopics: () => Promise<void>;
+    };
+    /** @internal Test-only access to explicit durable archive reconciliation. */
+    private archiveAuthorizedTopicsForTest;
     loadAliases(): Promise<void>;
     persistAliases(): Promise<void>;
     loadSeenUpdateIds(): Promise<void>;
@@ -1131,29 +958,12 @@ export declare class TelegramNotificationDaemon {
     private rememberSeenUpdateId;
     private reserveSeenUpdateId;
     private releaseSeenUpdateId;
-    scanRoots(): Promise<void>;
-    connectSession(sessionId: string, url: string, token: string): SessionSocket;
-    /**
-     * Start ack-based liveness for a session whose server advertised the
-     * `client_ping_pong` capability. Each interval drops the session when no pong
-     * has arrived within the TTL (the half-open case the socket never signals via
-     * `close`), otherwise sends a fresh application-level ping. The timer is bound
-     * to this exact session object.
-     */
-    private startLiveness;
-    /**
-     * Idempotent, identity-guarded session teardown. Clears the liveness timer,
-     * removes the map entry only when it still points at this exact session object
-     * (so a delayed old close cannot delete a replacement), and best-effort closes
-     * the socket. `scanRoots()` then reconnects the session.
-     */
+    /** Idempotent, identity-guarded attachment teardown. */
     private enqueueToolTerminalization;
-    private scheduleVisibleToolTerminalization;
     private beginToolActivityShutdown;
-    private dropSession;
     private deleteMessageRoutes;
     revokeCallbackAliases(socketLease: {
-        session: SessionSocket;
+        session: AttachmentSession;
         token: number;
         logicalSessionId: string;
     }): void;
@@ -1165,7 +975,7 @@ export declare class TelegramNotificationDaemon {
      * usable template applies so the caller uses the built-in composition. The
      * template is honored only if it is non-blank AND every placeholder it
      * references (`{repo}`, `{branch}`, `{title}`) has a value for this session,
-     * which preserves the default title/repo/branch fallbacks and prevents
+     * which preserves the default session-title fallback and prevents
      * half-filled names with dangling separators. Unknown placeholders are left
      * verbatim.
      */
@@ -1195,7 +1005,6 @@ export declare class TelegramNotificationDaemon {
     private topicLeaseIsCurrent;
     /** Best-effort re-assertion for a durable user-owned topic name. */
     private reconcileUserTopicName;
-    private rememberPendingThreadedFrame;
     private flushPendingThreadedFrames;
     /**
      * Resolve (creating once via `createForumTopic`) the forum topic for a
@@ -1204,8 +1013,6 @@ export declare class TelegramNotificationDaemon {
      * one-time nudge) or drop fail-closed for a non-private chat.
      */
     private ensureTopic;
-    private topicPastOrphanGrace;
-    private observeOrphanedTopic;
     /** Best-effort delete of a session topic once its local notification endpoint shuts down. */
     /** Join all close, compensation, orphan, and restart callers for one session. */
     private archiveTopic;
@@ -1219,8 +1026,10 @@ export declare class TelegramNotificationDaemon {
     loadAdoptionIntents(): Promise<void>;
     private startAdoptionSweepTimer;
     private stopAdoptionSweepTimer;
-    /** Retry crash-interrupted topic archives only when the durable backoff permits it. */
+    /** Retry crash-interrupted or ambiguous topic archives only when the durable backoff permits it. */
     private reconcilePendingTopicDeletes;
+    private startArchiveRetryTimer;
+    private stopArchiveRetryTimer;
     /** Download one Telegram file with the Bot API's 20 MiB ceiling and one end-to-end deadline. */
     private downloadTelegramFile;
     /**
@@ -1254,7 +1063,6 @@ export declare class TelegramNotificationDaemon {
      */
     private flushChain;
     private flushPool;
-    /** Drain the shared rate-limit pool and deliver each granted send to its topic. */
     private submitPool;
     private flushPoolInner;
     /**
@@ -1295,35 +1103,36 @@ export declare class TelegramNotificationDaemon {
      */
     private attachedEndpointCount;
     private renewOwnershipHeartbeat;
+    private renewActiveTopicLeases;
     /**
      * Ownership must be renewed independently of Telegram's 25-second long poll:
      * the ownership TTL is shorter than a single poll request.
      */
     private startOwnershipHeartbeatTimer;
     private stopOwnershipHeartbeatTimer;
+    private startTopicReconcileTimer;
+    private stopTopicReconcileTimer;
     /**
-     * Run a root scan, guarding against overlapping scans from the timer + loop.
-     *
-     * A reconciliation pass is retried every scan interval, so a failed one must
-     * never tear the owner down. Both callers are fatal boundaries: the timer
-     * fires and forgets, and the run loop awaits without a handler. A rejection
-     * escaping either one (a shared topic authority whose lock or compare-and-set
-     * is momentarily unavailable is the observed case) reaches the process-level
-     * handler, which exits the daemon: every session topic is then left as an
-     * unarchived shell that answers nothing, and the sessions that were still
-     * live lose notifications too. Report the failure and let the next scan
-     * retry instead.
+     * Periodic orphan-owner reconciliation. The daemon re-runs the bounded orphan
+     * reap on a fixed cadence so a stale poller that survived the startup sweep
+     * (or appeared after it) is eventually fenced. Failures are logged, never
+     * fatal: reconciliation is convergence work, not a run precondition.
      */
-    private runScan;
-    private startScanTimer;
-    private stopScanTimer;
+    private startOrphanReapTimer;
+    private stopOrphanReapTimer;
     /** Send a single `typing` chat action into a busy session's topic (best-effort). */
     private sendTyping;
     /** Set a native reaction on an inbound thread message (best-effort). */
     private setReaction;
+    /**
+     * Retract a native reaction by sending the empty reaction list the Bot API
+     * requires; an empty `emoji` string is not a valid reaction and is silently
+     * rejected, leaving the stale queued marker visible.
+     */
+    private retractReaction;
     private startTypingTimer;
     private stopTypingTimer;
-    handleSessionMessage(session: SessionSocket, msg: any): Promise<void>;
+    handleSessionMessage(session: AttachmentSession, msg: any, publicationId?: string): Promise<void>;
     private answerCallbackQueryBestEffort;
     private sendStaleGuidance;
     /**