@gajae-code/coding-agent 0.10.2 → 0.11.0

package/dist/types/sdk/bus/session-control.d.ts

@@ -0,0 +1,83 @@
+import { type NotificationConfig } from "./config";
+/** Minimal session-manager surface shared by extension, TUI, and headless hosts. */
+export interface NotificationSessionContext {
+    sessionManager: {
+        getCwd(): string;
+        getSessionId(): string;
+    };
+}
+/** A snapshot of the current session, resolved from the session manager per operation. */
+export interface BoundNotificationSession<Context extends NotificationSessionContext = NotificationSessionContext> {
+    readonly context: Context;
+    readonly cwd: string;
+    readonly sessionId: string;
+    unbind(): void;
+}
+export type NotificationEndpointStartResult = "started" | "already" | "disabled" | "failed";
+export type TelegramDaemonPreflightResult = "ready" | "blocked_identity";
+/**
+ * The endpoint implementation is deliberately injected. The controller owns
+ * policy and session-local state while the extension continues to own its
+ * concrete NotificationServer resources.
+ */
+export interface NotificationSessionRuntime<Context extends NotificationSessionContext = NotificationSessionContext> {
+    isRunning(binding: BoundNotificationSession<Context>): boolean;
+    start(binding: BoundNotificationSession<Context>): Promise<NotificationEndpointStartResult>;
+    stop(binding: BoundNotificationSession<Context>): Promise<boolean>;
+    /**
+     * Proves the complete Telegram owner identity before a generic endpoint can
+     * emit a frame. `blocked_identity` is fail-closed and starts nothing.
+     */
+    ensureTelegramDaemon?(binding: BoundNotificationSession<Context>): Promise<TelegramDaemonPreflightResult>;
+}
+export interface NotificationSessionStatus {
+    eligible: boolean;
+    locallyEnabled: boolean;
+    effectiveEnabled: boolean;
+    running: boolean;
+    environment: "off" | "explicit" | "token" | "default";
+}
+export interface NotificationSessionReconcileResult {
+    outcome: NotificationEndpointStartResult | "stopped";
+    status: NotificationSessionStatus;
+}
+export interface NotificationSessionControllerOptions {
+    /** Gate A result, resolved once by the SDK from the canonical host predicate. */
+    eligible: boolean;
+    /** Reads the global-only, schema-default-resolved notification configuration. */
+    getConfig(): NotificationConfig;
+    /** Kept as a reference so test and embedding hosts can supply their own environment. */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Shared owner of notification session policy.
+ *
+ * Gate A is captured at creation. Gate B is evaluated for each session
+ * operation with `isSessionNotificationsEnabled`. Gate C verifies complete
+ * Telegram ownership before a generic endpoint is allowed to start.
+ */
+export declare class NotificationSessionController {
+    #private;
+    constructor(options: NotificationSessionControllerOptions);
+    /** Attach the concrete generic endpoint implementation used by this host. */
+    attachRuntime<Context extends NotificationSessionContext>(runtime: NotificationSessionRuntime<Context>): () => void;
+    /**
+     * Bind a fresh session snapshot. Callers should not cache it: cwd and session
+     * id may change on `/new`, fork, or resume.
+     */
+    bind<Context extends NotificationSessionContext>(context: Context): BoundNotificationSession<Context>;
+    /** Preserve session-local safety state and pending-operation ownership across a session rekey. */
+    rekeySession(previousSessionId: string, nextSessionId: string): void;
+    query<Context extends NotificationSessionContext>(context: Context): NotificationSessionStatus;
+    /** Stop the current endpoint during host shutdown without changing local preference. */
+    stopCurrentSession<Context extends NotificationSessionContext>(context: Context): Promise<boolean>;
+    /**
+     * Hold this session's endpoint inactive after a foreign-daemon identity race.
+     * The block remains until an explicit same-identity reconnect or CAS restore clears it.
+     */
+    enterBlockedRuntime<Context extends NotificationSessionContext>(context: Context): Promise<boolean>;
+    /** Clear a block only after the caller has verified a safe same-identity reconnect or restore. */
+    clearBlockedRuntime<Context extends NotificationSessionContext>(context: Context): Promise<void>;
+    setLocalEnabled<Context extends NotificationSessionContext>(context: Context, enabled: boolean): Promise<NotificationSessionReconcileResult>;
+    reconcileCurrentSession<Context extends NotificationSessionContext>(context: Context): Promise<NotificationSessionReconcileResult>;
+}

package/dist/types/sdk/bus/slack-conversation.d.ts

@@ -0,0 +1,56 @@
+import { type ConversationRecord } from "./conversation-store";
+export interface SlackInboundDispatchReceipt {
+    key: string;
+    eventId: string;
+    interactionId: string;
+    retryKey: string;
+    eventContext?: string;
+    kind: "action" | "command";
+    actionId?: string;
+    /** The endpoint generation and SDK effect captured before Socket Mode ACK. */
+    endpointGeneration: number;
+    /** Identifier of the protected journal payload; mappings never retain message bodies. */
+    effectId: string;
+    idempotencyKey: string;
+}
+export type SlackConversationState = "absent" | "posting_root" | "active" | "closed_marker" | "resumed_root" | "error";
+/** Durable Slack mapping. It contains identifiers and receipt metadata only; protected journal effects own message bodies. */
+export interface SlackConversation extends ConversationRecord {
+    state: SlackConversationState;
+    teamId: string;
+    channelId: string;
+    rootTs?: string;
+    sessionId?: string;
+    endpointGeneration?: number;
+    clientMsgId?: string;
+    /** Exclusive, expiring authority for provider reconciliation/publication of the root intent. */
+    rootPublicationOwner?: string;
+    rootPublicationLeaseExpiresAt?: number;
+    /** Monotonic fencing token; stale root publishers may not commit after takeover. */
+    rootPublicationFence?: number;
+    /** Exclusive, expiring authority for provider reconciliation/publication of the outbound action intent. */
+    outboundActionOwner?: string;
+    outboundActionLeaseExpiresAt?: number;
+    /** Monotonic fencing token; stale action publishers may not commit after takeover. */
+    outboundActionFence?: number;
+    /** Action authority only; action bodies and endpoint credentials are never persisted. */
+    pendingActionId?: string;
+    /** Durable, unpublished action intent. The action body is supplied only by the caller. */
+    outboundActionId?: string;
+    outboundActionClientMsgId?: string;
+    lastError?: string;
+    updatedAt: number;
+    seenEventIds: string[];
+    seenContextIds: string[];
+    seenRetryKeys: string[];
+    seenInteractionIds: string[];
+    /** Durable inbound effect identifiers. The protected journal owns replay payloads. */
+    inboundDispatches?: SlackInboundDispatchReceipt[];
+}
+export declare function slackConversationKey(input: {
+    teamId: string;
+    channelId: string;
+    rootTs: string;
+}): string;
+export declare function normalizeSlackConversation(record: SlackConversation): SlackConversation;
+export declare function acceptsSlackInbound(record: SlackConversation, rootTs: string, endpointGeneration: number): boolean;

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

@@ -0,0 +1,60 @@
+import { type SdkSessionEndpoint } from "../client/discovery";
+import { ConversationStore } from "./conversation-store";
+import { type SlackConversation } from "./slack-conversation";
+export declare class SlackEndpointBindingError extends Error {
+    constructor(message?: string);
+}
+import type { SlackProvider, SlackSocketEnvelope } from "./slack-provider";
+export interface SlackEndpoint extends SdkSessionEndpoint {
+    generation: number;
+}
+export interface SlackSdkClient {
+    send(frame: Record<string, unknown>): void;
+}
+export interface SlackNotificationDaemonOptions {
+    agentDir: string;
+    repo: string;
+    teamId: string;
+    channelId: string;
+    provider: SlackProvider;
+    botUserId?: string;
+    /** Fail-closed authorization for the paired Slack principal. */
+    authorizeActor?: (actorId: string) => boolean | Promise<boolean>;
+    store?: ConversationStore<SlackConversation>;
+    now?: () => number;
+    randomId?: () => string;
+    /** Stable identity for the process attempting durable provider publication. */
+    publicationOwnerId?: string;
+    publicationLeaseMs?: number;
+    resolveEndpoint?: (sessionId: string) => Promise<SlackEndpoint | null>;
+    createClient: (endpoint: SlackEndpoint) => SlackSdkClient;
+    onCommand?: (sessionId: string, content: string, endpoint: SlackEndpoint, idempotencyKey: string) => Promise<boolean>;
+}
+/**
+ * Slack Socket Mode notification daemon. Accepted inbound SDK effects are
+ * persisted before acknowledgement, including their replay payload and captured
+ * endpoint generation; endpoint credentials and Socket Mode cursors are never
+ * written to disk.
+ */
+export declare class SlackNotificationDaemon {
+    #private;
+    private readonly options;
+    readonly store: ConversationStore<SlackConversation>;
+    constructor(options: SlackNotificationDaemonOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** Accepted inbound effects are durably claimed before their Socket Mode ACK. */
+    handleEnvelope(envelope: SlackSocketEnvelope): Promise<boolean>;
+    postRoot(sessionId: string, body: string, endpointGeneration?: number): Promise<SlackConversation>;
+    /** Deliver a notification into the mapped root thread, creating that root once. */
+    notify(sessionId: string, body: string, actionId?: string, endpointGeneration?: number): Promise<SlackConversation>;
+    /** Posts a safe command outcome to the active mapped root thread. */
+    postCommandResult(sessionId: string, content: string): Promise<boolean>;
+    resolveAction(sessionId: string, actionId: string): Promise<void>;
+    close(sessionId: string, marker?: string): Promise<boolean>;
+    resume(sessionId: string, body: string, endpointGeneration?: number): Promise<SlackConversation>;
+    findSession(sessionId: string, includeInactive: boolean): Promise<{
+        key: string;
+        record: SlackConversation;
+    } | undefined>;
+}

package/dist/types/sdk/bus/slack-live-provider.d.ts

@@ -0,0 +1,59 @@
+import type { SlackMessageSearchResult, SlackPostedMessage, SlackProviderClient, SlackSocketEnvelope } from "./slack-provider";
+export type SlackProviderErrorCode = "connection" | "protocol" | "web_api" | "rate_limited";
+/** A Slack transport failure whose fields are safe to surface without credentials. */
+export declare class SlackProviderError extends Error {
+    readonly code: SlackProviderErrorCode;
+    readonly operation: string;
+    readonly status?: number | undefined;
+    readonly retryAfterMs?: number | undefined;
+    /** The server may have accepted the request before its response became unusable. */
+    readonly mayHaveBeenAccepted: boolean;
+    readonly retryable: boolean;
+    constructor(code: SlackProviderErrorCode, operation: string, status?: number | undefined, retryAfterMs?: number | undefined, 
+    /** The server may have accepted the request before its response became unusable. */
+    mayHaveBeenAccepted?: boolean);
+}
+export interface SlackWebSocket {
+    readonly readyState: number;
+    onopen: ((event: Event) => void) | null;
+    onmessage: ((event: MessageEvent) => void) | null;
+    onclose: ((event: CloseEvent) => void) | null;
+    onerror: ((event: Event) => void) | null;
+    send(data: string): void;
+    close(): void;
+}
+export interface SlackLiveProviderOptions {
+    appToken: string;
+    botToken: string;
+    fetch?: (input: string, init?: RequestInit) => Promise<Response>;
+    webSocket?: (url: string) => SlackWebSocket;
+    now?: () => number;
+    sleep?: (milliseconds: number) => Promise<void>;
+    reconnectDelayMs?: number;
+    maxRateLimitRetries?: number;
+    maxRetryAfterMs?: number;
+    activityTimeoutMs?: number;
+}
+/**
+ * Production Socket Mode and Web API client. It keeps all connection state in
+ * memory and deliberately never maintains a Slack cursor.
+ */
+export declare class SlackLiveProvider implements SlackProviderClient {
+    #private;
+    get transportHealthy(): boolean;
+    constructor(options: SlackLiveProviderOptions);
+    start(onEnvelope: (envelope: SlackSocketEnvelope) => void | Promise<void>): Promise<void>;
+    stop(): Promise<void>;
+    ack(envelopeId: string): Promise<void>;
+    postMessage(input: {
+        channel: string;
+        text: string;
+        threadTs?: string;
+        clientMsgId: string;
+    }): Promise<SlackPostedMessage>;
+    findMessageByClientMsgId(input: {
+        channel: string;
+        clientMsgId: string;
+        threadTs?: string;
+    }): Promise<SlackMessageSearchResult | null>;
+}

package/dist/types/sdk/bus/slack-provider.d.ts

@@ -0,0 +1,55 @@
+export interface SlackSocketEnvelope {
+    envelope_id: string;
+    payload: unknown;
+}
+export interface SlackPostedMessage {
+    channel: string;
+    ts: string;
+    client_msg_id?: string;
+}
+export interface SlackMessageSearchResult {
+    channel: string;
+    ts: string;
+    client_msg_id?: string;
+}
+/** Minimal Socket Mode + Web API seam. Implementations may wrap the official Slack SDK. */
+export interface SlackProviderClient {
+    start(onEnvelope: (envelope: SlackSocketEnvelope) => void | Promise<void>): Promise<void>;
+    stop?(): Promise<void>;
+    ack(envelopeId: string): Promise<void>;
+    postMessage(input: {
+        channel: string;
+        text: string;
+        threadTs?: string;
+        clientMsgId: string;
+    }): Promise<SlackPostedMessage>;
+    findMessageByClientMsgId?(input: {
+        channel: string;
+        clientMsgId: string;
+        threadTs?: string;
+    }): Promise<SlackMessageSearchResult | null>;
+    readonly transportHealthy?: boolean;
+}
+/**
+ * Transport wrapper deliberately limited to Slack SDK operations. Keeping it injectable
+ * makes Socket Mode acknowledgement and Web API failure cases deterministic in tests.
+ */
+export declare class SlackProvider {
+    private readonly client;
+    constructor(client: SlackProviderClient);
+    start(onEnvelope: (envelope: SlackSocketEnvelope) => void | Promise<void>): Promise<void>;
+    get transportHealthy(): boolean;
+    stop(): Promise<void>;
+    ack(envelopeId: string): Promise<void>;
+    postMessage(input: {
+        channel: string;
+        text: string;
+        threadTs?: string;
+        clientMsgId: string;
+    }): Promise<SlackPostedMessage>;
+    findMessageByClientMsgId(input: {
+        channel: string;
+        clientMsgId: string;
+        threadTs?: string;
+    }): Promise<SlackMessageSearchResult | null>;
+}

package/dist/types/{notifications → sdk/bus}/telegram-cli.d.ts

@@ -1,19 +1,19 @@
 #!/usr/bin/env bun
 /**
- * Reference CLI for the notifications SDK Telegram client.
+ * Reference CLI for the Gajae-Code SDK Telegram client.
  *
  * Bridges a running GJC session's notification endpoint to a Telegram bot so you
  * can answer asks / see idle pings from your phone — no RPC mode required. This
- * is an EXAMPLE/template (the SDK contract is in `docs/notifications-sdk.md`);
+ * is an EXAMPLE/template (the SDK contract is in `docs/sdk.md`);
  * Discord/Slack clients are written the same way.
  *
  * Usage:
- *   bun run packages/coding-agent/src/notifications/telegram-cli.ts \
+ *   bun run packages/coding-agent/src/sdk/bus/telegram-cli.ts \
  *     --bot-token <token> [--chat-id <id>] [--endpoint-file <path> | --session-id <id>] [--repo <dir>]
  *
  * Env fallbacks: GJC_TG_BOT_TOKEN, GJC_TG_CHAT_ID.
  * If --chat-id is omitted it is auto-resolved from getUpdates (message the bot once).
  * If neither --endpoint-file nor --session-id is given, the newest endpoint file
- * under <repo>/.gjc/state/notifications/ is used.
+ * under <repo>/.gjc/state/sdk/ is used.
  */
 export {};

package/dist/types/{notifications → sdk/bus}/telegram-daemon-cli.d.ts

@@ -1,25 +1,34 @@
-import type { Settings } from "../config/settings";
-import type { TelegramDaemonOptions } from "./telegram-daemon";
+import type { Settings } from "../../config/settings";
+import { type NotificationSettingsReader } from "./config";
+import { type DaemonState, type TelegramDaemonOptions } from "./telegram-daemon";
 type TelegramDaemonRunner = {
     run(): Promise<void>;
     requestStop(reason?: "reload" | "signal" | "stop"): void;
 };
 type TelegramDaemonConstructor = new (opts: TelegramDaemonOptions) => TelegramDaemonRunner;
+export type LightweightDaemonSettings = Pick<Settings, "get" | "getAgentDir" | "set" | "flush"> & NotificationSettingsReader;
 export interface RunDaemonInternalDeps {
     SettingsImpl?: {
         init: (options?: {
             agentDir?: string;
-        }) => Promise<Pick<Settings, "get" | "getAgentDir" | "set" | "flush">>;
+        }) => Promise<LightweightDaemonSettings>;
     };
     DaemonImpl?: TelegramDaemonConstructor;
     processPid?: number;
     pidAlive?: (pid: number) => boolean;
+    /** Clock used by the ownership-progress watchdog; defaults to `Date.now`. */
+    now?: () => number;
+    /** Timer pair backing the ownership-progress watchdog; defaults to globals. */
+    setInterval?: (callback: () => void, ms: number) => Timer;
+    clearInterval?: (timer: Timer) => void;
+    /** Reads persisted daemon ownership state; defaults to the real reader. */
+    readDaemonState?: (settings: Settings) => Promise<DaemonState | undefined>;
 }
 export declare function createLightweightDaemonSettings(input: {
     agentDir: string;
     rawConfig?: unknown;
-}): Pick<Settings, "get" | "getAgentDir" | "set" | "flush">;
-export declare function loadLightweightDaemonSettings(agentDir: string): Promise<Pick<Settings, "get" | "getAgentDir" | "set" | "flush">>;
+}): LightweightDaemonSettings;
+export declare function loadLightweightDaemonSettings(agentDir: string): Promise<LightweightDaemonSettings>;
 export declare function ownerPidFromOwnerId(ownerId: string): number | undefined;
 export declare function runDaemonSmoke(opts?: {
     agentDir?: string;

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

@@ -0,0 +1,12 @@
+/**
+ * Lightweight daemon protocol contract for consumers that need generation
+ * metadata without loading the Telegram daemon runtime.
+ */
+/** Protocol version the daemon advertises in its ClientHello. */
+export declare const NOTIFICATION_PROTOCOL_VERSION = 3;
+/**
+ * Operational generation the current daemon build speaks. It is tied to the
+ * wire protocol version so a freshly-upgraded host can identify an older,
+ * still-live daemon without coupling status readers to the daemon runtime.
+ */
+export declare const DAEMON_GENERATION = 3;

package/dist/types/{notifications → sdk/bus}/telegram-daemon-control.d.ts

@@ -7,8 +7,8 @@
  * keeps the single-poller invariant (no Telegram getUpdates 409 overlap) and
  * never steals a still-live owner.
  */
-import type { Settings } from "../config/settings";
-import type { BuiltInDaemonController, DaemonOperationOptions, DaemonOperationResult, DaemonStatus } from "../daemon/control-types";
+import type { Settings } from "../../config/settings";
+import type { BuiltInDaemonController, DaemonOperationOptions, DaemonOperationResult, DaemonStatus } from "../../daemon/control-types";
 import { type TelegramDaemonDeps, type TelegramDaemonFs } from "./telegram-daemon";
 export interface TelegramDaemonControlRequest {
     version: 1;

package/dist/types/{notifications → sdk/bus}/telegram-daemon.d.ts

@@ -1,11 +1,15 @@
 import * as fs from "node:fs";
-import type { Settings } from "../config/settings";
-import type { DaemonRuntimeInfo } from "../daemon/control-types";
+import type { Settings } from "../../config/settings";
+import type { DaemonRuntimeInfo } from "../../daemon/control-types";
 import { HEARTBEAT_TTL_MS } from "./daemon-paths";
+export { DAEMON_GENERATION, NOTIFICATION_PROTOCOL_VERSION } from "./telegram-daemon-contract";
 import { type ControlServerLike, type LifecycleControlServerFactory } from "./lifecycle-control-runtime";
+import type { OrchestratorDeps } from "./lifecycle-orchestrator";
 import { NotificationOperatorRuntime, OperatorBackoffPolicy } from "./operator-runtime";
 import { type AliasTable, type CallbackRoute } from "./telegram-reference";
 export type EnsureDaemonResult = "owner_spawned" | "attached" | "disabled" | "blocked";
+/** Detailed result for orchestration that must distinguish a #2028 handoff from a fresh spawn. */
+export type EnsureTelegramDaemonDetailedResult = "spawned" | "reloaded" | "attached" | "disabled" | "blocked_identity";
 export interface DaemonState {
     pid: number;
     ownerId: string;
@@ -66,22 +70,11 @@ export { HEARTBEAT_TTL_MS };
 export declare const DAEMON_VERSION = 1;
 /** Capability token advertised when the server supports app-level ping/pong. */
 export declare const CLIENT_PING_PONG_CAPABILITY = "client_ping_pong";
-/** Protocol version the daemon advertises in its ClientHello. */
-export declare const NOTIFICATION_PROTOCOL_VERSION = 3;
 /** Capability required for typed controls and semantic Selected acknowledgement frames. */
 export declare const ASK_SELECTED_ACK_CAPABILITY = "ask_selected_ack_v1";
 export declare const ASK_CONTROLS_CAPABILITY = "ask_controls_v1";
-/**
- * Operational generation the current daemon build speaks, persisted into
- * {@link DaemonState.generation} on ownership acquisition. It is tied to the
- * wire {@link NOTIFICATION_PROTOCOL_VERSION} so any protocol bump (which is what
- * gates capabilities like {@link ASK_SELECTED_ACK_CAPABILITY}) also bumps the
- * generation, letting a freshly-upgraded host recognise an older, still-live
- * daemon and reload it instead of silently attaching to it. Distinct from the
- * persisted schema {@link DAEMON_VERSION}, which did not change across #1999.
- */
-export declare const DAEMON_GENERATION = 3;
 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.
  *
@@ -96,14 +89,26 @@ export declare function startDaemonLifecycleControl(input: {
     controlServer: ControlServerLike;
     pairedChatId: string;
     agentDir: string;
+    auditRedactionKey: Uint8Array;
     env?: NodeJS.ProcessEnv;
-}): void;
+}): OrchestratorDeps;
 export declare function registerNotificationRoot(input: {
     settings: Settings;
     cwd: string;
     sessionId: string;
     fs?: TelegramDaemonFs;
 }): Promise<string>;
+export interface UnregisterNotificationRootResult {
+    root: string;
+    remainingRoots: number;
+}
+/** 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;
+}): Promise<UnregisterNotificationRootResult>;
 export declare function isFreshLiveOwner(input: {
     state: DaemonState | undefined;
     now: number;
@@ -143,9 +148,9 @@ export declare function releaseDaemonOwnership(input: {
     now?: () => number;
 }): Promise<void>;
 /** Read the persisted daemon ownership state (or undefined when absent). */
-export declare function readDaemonState(settings: Settings, fs?: TelegramDaemonFs): Promise<DaemonState | undefined>;
+export declare function readDaemonState(settings: Pick<Settings, "getAgentDir">, fs?: TelegramDaemonFs): Promise<DaemonState | undefined>;
 /** Read the persisted notification roots list. */
-export declare function readDaemonRoots(settings: Settings, fs?: TelegramDaemonFs): Promise<string[]>;
+export declare function readDaemonRoots(settings: Pick<Settings, "getAgentDir">, fs?: TelegramDaemonFs): Promise<string[]>;
 export interface TelegramSpawnOwnerInput {
     settings: Settings;
     roots?: string[];
@@ -185,6 +190,19 @@ export declare function buildTelegramDaemonSpawnArgs(input: {
  * already-persisted roots.
  */
 export declare function spawnTelegramDaemonOwner(input: TelegramSpawnOwnerInput, deps?: TelegramDaemonDeps): Promise<TelegramSpawnOwnerResult>;
+/**
+ * Ensure a configured daemon owns this session root, preserving ownership safety
+ * while exposing whether a #2028 generation handoff was required.
+ */
+export declare function ensureTelegramDaemonRunningDetailed(input: {
+    settings: Settings;
+    cwd: string;
+    sessionId: string;
+}, deps?: TelegramDaemonDeps): Promise<EnsureTelegramDaemonDetailedResult>;
+/**
+ * Legacy compatibility mapping for callers that only distinguish ownership from
+ * attachment. New orchestration should use {@link ensureTelegramDaemonRunningDetailed}.
+ */
 export declare function ensureTelegramDaemonRunning(input: {
     settings: Settings;
     cwd: string;
@@ -271,6 +289,16 @@ export interface TelegramDaemonOptions {
      * 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;
     /** Rich text promotion (enabled by default; see rich-render.ts). */
     rich?: {
         enabled: boolean;
@@ -289,7 +317,10 @@ export interface TelegramDaemonOptions {
     };
 }
 interface SessionSocket {
+    /** Immutable key of the transport endpoint that owns this socket. */
     sessionId: string;
+    /** Current logical session carried by valid threaded frames on this transport. */
+    logicalSessionId: string;
     token: string;
     endpointKey: string;
     ws: WebSocket;
@@ -305,8 +336,14 @@ interface SessionSocket {
     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. */
+    replayId: string;
+    /** Queues live frames until startup replay is applied. */
+    replayPending: boolean;
+    replayQueue: Record<string, unknown>[];
 }
 export declare class TelegramNotificationDaemon {
+    #private;
     private readonly opts;
     readonly aliasTable: AliasTable;
     readonly messageRoutes: Map<string | number, CallbackRoute | Omit<CallbackRoute, "answer">>;
@@ -416,6 +453,7 @@ export declare class TelegramNotificationDaemon {
     persistSeenUpdateIds(): Promise<void>;
     private pruneSeenUpdateIds;
     private rememberSeenUpdateId;
+    private rememberSeenUpdateIdForUnavailableNotice;
     scanRoots(): Promise<void>;
     connectSession(sessionId: string, url: string, token: string): void;
     /**

package/dist/types/{notifications → sdk/bus}/telegram-reference.d.ts

@@ -1,8 +1,8 @@
 /**
- * Telegram **reference** client for the notifications SDK.
+ * Telegram **reference** client for the Gajae-Code SDK.
  *
  * This is an example/template, NOT an upstream-owned integration: it implements
- * the documented WS protocol (see `docs/notifications-sdk.md`) so you can copy it
+ * the documented WS protocol (see `docs/sdk.md`) so you can copy it
  * to build Discord/Slack/etc. clients with zero upstream changes. The Bot API
  * transport shape is salvaged from the removed `telegram-remote` package.
  *