@gajae-code/coding-agent 0.10.2 → 0.11.1

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;
@@ -212,17 +230,40 @@ export declare class TelegramBotTransport implements BotApi {
     }): Promise<unknown>;
 }
 export type TelegramUpdateOutcome = "consumed" | "retry";
+export type TelegramPollResult = {
+    kind: "success";
+    updateCount: number;
+} | {
+    kind: "aborted";
+} | {
+    kind: "getUpdates_failed";
+    error: string;
+} | {
+    kind: "api_failure";
+    errorCode?: number;
+    description: string;
+} | {
+    kind: "conflict";
+    description: string;
+    backoffMs: number;
+};
 export interface TelegramUpdatePollerOptions {
     botApi: BotApi;
     runtime: NotificationOperatorRuntime;
     backoff: OperatorBackoffPolicy;
     processUpdate: (update: unknown) => Promise<TelegramUpdateOutcome>;
+    health?: TelegramPollHealth;
+}
+export declare class TelegramPollHealth {
+    #private;
+    record(result: TelegramPollResult): void;
 }
 /** Owns getUpdates offset, conflict backoff, and per-update error isolation. */
 export declare class TelegramUpdatePoller {
     #private;
     constructor(opts: TelegramUpdatePollerOptions);
     pollOnce(signal?: AbortSignal): Promise<number>;
+    pollOnceResult(signal?: AbortSignal): Promise<TelegramPollResult>;
 }
 /** Mutable dispatch state shared by session frames and inbound Telegram updates. */
 export declare class TelegramEventDispatchState {
@@ -271,6 +312,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 +340,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 +359,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 +476,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.
  *

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

@@ -0,0 +1,128 @@
+export declare const DEFAULT_TELEGRAM_SETUP_API_BASE = "https://api.telegram.org";
+export declare const DEFAULT_TELEGRAM_SETUP_POLL_TIMEOUT_MS = 60000;
+export declare const DEFAULT_TELEGRAM_SETUP_POLL_INTERVAL_MS = 1000;
+export type TelegramThreadedModeState = "enabled" | "disabled" | "unknown";
+export type TelegramThreadedModeLabel = "verified" | "unverified" | "unknown";
+export type TelegramSetupPairingSource = "discovered" | "provided" | "reused";
+export type TelegramSetupFailureStatus = "error" | "cancelled" | "requires_explicit_chat" | "ownership_lost" | "aborted";
+export interface TelegramSetupTimers {
+    now(): number;
+    sleep(ms: number, signal?: AbortSignal): Promise<void>;
+}
+export interface TelegramSetupDeps {
+    fetchImpl: typeof fetch;
+    apiBase?: string;
+    timers?: TelegramSetupTimers;
+}
+/** Current daemon ownership facts collected by the caller before setup starts. */
+export interface TelegramSetupPreflight {
+    storedChatId?: string;
+    daemon?: {
+        live: boolean;
+        tokenFingerprint?: string;
+        /** Required with a live daemon so reuse verifies the complete token/chat identity. */
+        chatId?: string;
+    };
+}
+export type TelegramSetupPollingPolicy = {
+    kind: "discover";
+} | {
+    kind: "reuse_stored_chat";
+    chatId: string;
+} | {
+    kind: "validate_explicit_chat";
+    chatId: string;
+} | {
+    kind: "requires_explicit_chat";
+} | {
+    kind: "cancel_foreign_or_unknown_owner";
+    identity: "foreign" | "unknown";
+};
+export type TelegramSetupEvent = {
+    kind: "token_validated";
+    message: string;
+} | {
+    kind: "threaded_mode_guidance";
+    message: string;
+} | {
+    kind: "rejected_chat";
+    message: string;
+};
+export interface TelegramSetupSuccess {
+    ok: true;
+    chatId: string;
+    tokenFingerprint: string;
+    threadedMode: TelegramThreadedModeState;
+    threadedLabel: TelegramThreadedModeLabel;
+    pairingSource: TelegramSetupPairingSource;
+}
+export interface TelegramSetupFailure {
+    ok: false;
+    status: TelegramSetupFailureStatus;
+    detail: string;
+}
+export type TelegramSetupResult = TelegramSetupSuccess | TelegramSetupFailure;
+export interface TelegramBot {
+    id: number;
+    isBot?: boolean;
+    firstName?: string;
+    username?: string;
+    hasTopicsEnabled?: boolean;
+    allowsUsersToCreateTopics?: boolean;
+}
+export type TelegramTokenValidationResult = {
+    ok: true;
+    bot: TelegramBot;
+    threadedMode: TelegramThreadedModeState;
+} | TelegramSetupFailure;
+export type TelegramPrivateChatValidationResult = {
+    ok: true;
+    chatId: string;
+} | TelegramSetupFailure;
+export interface RunTelegramSetupInput {
+    token: string;
+    preflight: TelegramSetupPreflight;
+    /**
+     * Re-reads daemon ownership immediately before any `getUpdates` call. It is
+     * mandatory for discovery because an earlier preflight cannot own Telegram's
+     * single-poller slot.
+     */
+    revalidatePreflight?: (signal?: AbortSignal) => Promise<TelegramSetupPreflight>;
+    chatId?: string;
+    interactive: boolean;
+    threadedModePrompt?: (message: string) => Promise<string>;
+    pollTimeoutMs?: number;
+    pollIntervalMs?: number;
+    signal?: AbortSignal;
+    onEvent?: (event: TelegramSetupEvent) => void;
+    deps: TelegramSetupDeps;
+}
+export declare function withTelegramSetupLease<T>(token: string, operation: () => Promise<T>): Promise<T>;
+/** Validate a token with getMe without exposing it in diagnostics or results. */
+export declare function validateTelegramBotToken(input: {
+    token: string;
+    deps: TelegramSetupDeps;
+    signal?: AbortSignal;
+}): Promise<TelegramTokenValidationResult>;
+/** Validate that a supplied or stored chat is an actual Telegram private chat. */
+export declare function validateTelegramPrivateChat(input: {
+    token: string;
+    chatId: string;
+    deps: TelegramSetupDeps;
+    signal?: AbortSignal;
+}): Promise<TelegramPrivateChatValidationResult>;
+/**
+ * Decide whether setup may call getUpdates. Any live daemon is a hard polling
+ * boundary: only a verified complete token/chat identity may reuse the stored
+ * chat; setup never polls while any live owner exists.
+ */
+export declare function resolveTelegramSetupPollingPolicy(input: {
+    token: string;
+    preflight: TelegramSetupPreflight;
+    chatId?: string;
+}): TelegramSetupPollingPolicy;
+/**
+ * Validate a token, assess Threaded Mode, and obtain a private chat according
+ * to the daemon poller-contention policy. No settings are written here.
+ */
+export declare function runTelegramSetup(input: RunTelegramSetupInput): Promise<TelegramSetupResult>;

package/dist/types/{notifications → sdk/bus}/topic-registry.d.ts

@@ -30,6 +30,10 @@ export interface TopicRecord {
     userNameUpdateId?: number;
     /** Stable repo/branch identity used when topic names are user-owned or customized. */
     identityKey?: string;
+    /** Last SDK event generation durably consumed by the notification daemon. */
+    replayGeneration?: number;
+    /** Last SDK event sequence durably consumed within replayGeneration. */
+    replaySeq?: number;
 }
 /** Serialisable shape persisted to disk. */
 export interface TopicRegistryState {
@@ -68,6 +72,13 @@ export declare class TopicRegistry {
     needsIdentity(sessionId: string): boolean;
     /** Remember stable repo/branch identity independently of the displayed name. */
     markIdentityKey(sessionId: string, identityKey: string): boolean;
+    /** Last durably consumed SDK event cursor for reconnect replay. */
+    replayCursor(sessionId: string): {
+        generation: number;
+        seq: number;
+    } | undefined;
+    /** Advance the durable reconnect cursor without allowing stale responses to move it backwards. */
+    markReplayCursor(sessionId: string, generation: number, seq: number): boolean;
     /** Whether daemon identity reconciliation should apply `name`. */
     needsRename(sessionId: string, name: string): boolean;
     /** The user-owned name that must be preserved, when one exists. */

package/dist/types/sdk/cli/index.d.ts

@@ -0,0 +1 @@
+export * from "./session-cli";

package/dist/types/sdk/cli/session-cli.d.ts

@@ -0,0 +1,19 @@
+export type SdkSessionCliAction = "list" | "control" | "query" | "global";
+export interface SdkSessionCliArgs {
+    action?: string;
+    sessionId?: string;
+    operation?: string;
+    query?: string;
+    jsonInput?: string;
+    jsonInputFile?: string;
+    idempotencyKey?: string;
+    jsonInputStdin?: boolean;
+    confirm?: boolean;
+    cursor?: string;
+    showEndpointCredential?: boolean;
+    yes?: boolean;
+    repo?: string;
+    agentDir?: string;
+}
+/** Runs the pure-SDK `gjc daemon session` command family. */
+export declare function runSdkSessionCli(args: SdkSessionCliArgs, writeOutput?: (value: unknown) => void, setExitCode?: (exitCode: 1 | 2) => void): Promise<void>;

package/dist/types/sdk/client/client.d.ts

@@ -0,0 +1 @@
+export * from "@gajae-code/bridge-client";