@sayknow-cli/coding-agent 0.3.12 → 0.3.15

package/dist/types/modes/types.d.ts

@@ -21,10 +21,14 @@ import type { EvalExecutionComponent } from "./components/eval-execution";
 import type { HookEditorComponent } from "./components/hook-editor";
 import type { HookInputComponent } from "./components/hook-input";
 import type { HookSelectorComponent } from "./components/hook-selector";
+import type { PetMode } from "./components/sayknow-pet-widget";
 import type { StatusLineComponent } from "./components/status-line";
 import type { ToolExecutionHandle } from "./components/tool-execution";
+import type { IrcObservationLedger } from "./irc-observation-ledger";
 import type { OAuthManualInputManager } from "./oauth-manual-input";
 import type { Theme } from "./theme/theme";
+import type { ParsedIrcMessage } from "./utils/irc-message";
+export type TranscriptRebuildPolicy = "replace-identity" | "reconcile-same-transcript";
 export type CompactionQueuedMessage = {
     text: string;
     mode: "steer" | "followUp";
@@ -49,6 +53,13 @@ export type TodoPhase = {
     name: string;
     tasks: TodoItem[];
 };
+export type IrcArrivalSnapshot = Readonly<{
+    panelVisible: boolean;
+    /** User-requested open state; may be true while the panel yields at narrow widths. */
+    panelRequestedVisible: boolean;
+    sidebarAvailable: boolean;
+    resolvedToggleKey: string | null;
+}>;
 export interface InteractiveModeContext {
     ui: TUI;
     chatContainer: Container;
@@ -69,6 +80,7 @@ export interface InteractiveModeContext {
     historyStorage?: HistoryStorage;
     mcpManager?: MCPManager;
     lspServers?: LspStartupServerInfo[];
+    readonly ircLedger: IrcObservationLedger;
     isInitialized: boolean;
     isBackgrounded: boolean;
     isBashMode: boolean;
@@ -141,6 +153,11 @@ export interface InteractiveModeContext {
     setWorkingMessage(message?: string): void;
     applyPendingWorkingMessage(): void;
     ensureLoadingAnimation(): void;
+    setPetMode(mode: PetMode): void;
+    /** Live-preview a pet skin during a selector without persisting. */
+    previewPetMode(mode: PetMode): void;
+    /** Re-mount the composer (pet-aware) after an overlay/selector closes. */
+    restoreComposer(): void;
     startPendingSubmission(input: {
         text: string;
         images?: ImageContent[];
@@ -169,22 +186,30 @@ export interface InteractiveModeContext {
     addMessageToChat(message: AgentMessage, options?: {
         populateHistory?: boolean;
     }): Component[];
+    addLiveIrcObservationToChat(message: ParsedIrcMessage, arrival: IrcArrivalSnapshot): Component[];
+    removeRenderedIrcInlineComponents(observationId: string): readonly Component[] | undefined;
+    resetRenderedIrcInlineComponents(): readonly (readonly Component[])[];
     renderSessionContext(sessionContext: SessionContext, options?: {
         updateFooter?: boolean;
         populateHistory?: boolean;
     }): void;
-    renderInitialMessages(prebuiltContext?: SessionContext, options?: {
+    rebuildInitialMessages(policy: TranscriptRebuildPolicy, prebuiltContext?: SessionContext, options?: {
         preserveExistingChat?: boolean;
     }): void;
     getUserMessageText(message: Message): string;
+    getAssistantViewportAnchorId?(message: AssistantMessage): string;
     findLastAssistantMessage(): AssistantMessage | undefined;
     extractAssistantText(message: AssistantMessage): string;
     updateEditorTopBorder(): void;
     updateEditorBorderColor(): void;
-    rebuildChatFromMessages(): void;
+    rebuildChatFromMessages(policy: TranscriptRebuildPolicy): void;
     setTodos(todos: TodoItem[] | TodoPhase[]): void;
     reloadTodos(): Promise<void>;
     toggleTodoExpansion(): void;
+    toggleIrcSidebar(): void;
+    captureIrcArrivalSnapshot(): IrcArrivalSnapshot;
+    applyIrcSidebarAvailability(enabled: boolean): void;
+    resetIrcSidebarSession(): void;
     handleExportCommand(text: string): Promise<void>;
     handleShareCommand(): Promise<void>;
     handleCopyCommand(sub?: string): void;
@@ -219,6 +244,7 @@ export interface InteractiveModeContext {
     refreshSlashCommandState(cwd?: string): Promise<void>;
     showSettingsSelector(): void;
     showThemeSelector(): void;
+    showPetSelector(): void;
     showHistorySearch(): void;
     showExtensionsDashboard(): void;
     showAgentsDashboard(): void;

package/dist/types/modes/utils/abort-message.d.ts

@@ -1,4 +1,4 @@
-export declare function buildAbortDisplayMessage({ errorMessage, retryAttempt }: {
+export declare function buildAbortDisplayMessage({ errorMessage, retryAttempt, }: {
     errorMessage?: string;
     retryAttempt: number;
 }): string;

package/dist/types/modes/utils/context-usage.d.ts

@@ -1,9 +1,8 @@
 import type { AgentMessage } from "@sayknow-cli/agent-core";
 import type { Model } from "@sayknow-cli/ai";
-import type { Skill } from "../../extensibility/skills";
 import type { AgentSession } from "../../session/agent-session";
-import type { Tool } from "../../tools";
 import type { theme as Theme } from "../theme/theme";
+export { computeNonMessageTokens, estimateSkillsTokens, estimateToolSchemaTokens, } from "../../session/context-estimation";
 type CategoryId = "systemPrompt" | "systemContext" | "rules" | "tools" | "skills" | "messages" | "lastUserTurn";
 interface CategoryInfo {
     id: CategoryId;
@@ -17,25 +16,12 @@ export interface ContextBreakdown {
     contextWindow: number;
     categories: CategoryInfo[];
     lastUserTurnTokens: number;
-    usedTokens: number;
+    estimatedCategoryTotal: number;
+    usedTokens: number | null;
+    source: "provider_anchor" | "heuristic" | "unknown";
     autoCompactBufferTokens: number;
     freeTokens: number;
 }
-export declare function estimateSkillsTokens(skills: readonly Skill[]): number;
-export declare function estimateToolSchemaTokens(tools: ReadonlyArray<Pick<Tool, "name" | "description" | "parameters">>): number;
-/**
- * Compute just the NON-MESSAGE token total: system prompt (with its skills
- * section subtracted, since skills are tokenized separately) + system context
- * (the rest of the system-prompt array) + tools + skills.
- *
- * Exposed so callers like `StatusLineComponent` can cache the non-message
- * total separately from the message total. Non-message inputs (skills,
- * tools, system prompt) change rarely; the message list grows on every
- * streaming turn. Splitting the two lets the caller refresh each on its own
- * cadence — non-message recomputed only when the inputs identity changes,
- * messages walked incrementally as new entries append.
- */
-export declare function computeNonMessageTokens(session: AgentSession): number;
 /**
  * Compute a breakdown of estimated context usage by category for the active
  * session and model.
@@ -48,4 +34,3 @@ export declare function computeContextBreakdown(session: AgentSession, options?:
  * lines pairing the grid (left) with the legend (right).
  */
 export declare function renderContextUsage(breakdown: ContextBreakdown, theme: typeof Theme): string;
-export {};

package/dist/types/modes/utils/irc-message.d.ts

@@ -0,0 +1,38 @@
+import type { AgentMessage } from "@sayknow-cli/agent-core";
+export type IrcMessageKind = "incoming" | "autoreply" | "relay";
+export type ParsedIrcMessage = {
+    observationId: string;
+    from: string;
+    to: string;
+    text: string;
+    timestamp: number;
+    kind: IrcMessageKind;
+};
+export interface IrcMessageBlock {
+    readonly sender: string;
+    readonly recipient: string;
+    readonly kind: "incoming" | "autoreply" | "outgoing";
+    readonly time: string;
+    readonly bodyLines: readonly string[];
+}
+export declare function projectIrcText(text: string, maxUtf8Bytes: number): {
+    text: string;
+    truncated: boolean;
+    utf8Bytes: number;
+};
+/** Normalizes and bounds untrusted IRC identity fields without splitting visible graphemes. */
+export declare function normalizeIrcIdentity(identity: string): string;
+/** Formats IRC observations into display-neutral semantic blocks for both IRC surfaces. */
+export declare function formatIrcMessageBlock(message: ParsedIrcMessage & {
+    timestamp: number;
+}): IrcMessageBlock;
+type IrcCustomMessage = Extract<AgentMessage, {
+    role: "custom";
+}>;
+export declare function isIrcCustomType(customType: string | undefined): customType is `irc:${IrcMessageKind}`;
+/**
+ * Normalizes every supported IRC custom message into its UI observation shape.
+ * Legacy records have no UUID, so their immutable payload is used as a stable key.
+ */
+export declare function parseIrcMessage(message: IrcCustomMessage): ParsedIrcMessage | undefined;
+export {};

package/dist/types/modes/utils/ui-helpers.d.ts

@@ -1,8 +1,11 @@
 import type { AgentMessage } from "@sayknow-cli/agent-core";
 import type { AssistantMessage, Message } from "@sayknow-cli/ai";
-import { type Component } from "@sayknow-cli/tui";
-import type { InteractiveModeContext } from "../../modes/types";
-import type { SessionContext } from "../../session/session-manager";
+import { type Component, type TUI } from "@sayknow-cli/tui";
+import type { InteractiveModeContext, IrcArrivalSnapshot, TranscriptRebuildPolicy } from "../../modes/types";
+import { type SessionContext } from "../../session/session-manager";
+import { type ParsedIrcMessage } from "./irc-message";
+export type { TranscriptRebuildPolicy } from "../../modes/types";
+export declare function prepareTranscriptRebuild(ui: TUI, policy: TranscriptRebuildPolicy): void;
 interface RenderInitialMessagesOptions {
     preserveExistingChat?: boolean;
 }
@@ -23,6 +26,13 @@ export declare class UiHelpers {
     #private;
     private ctx;
     constructor(ctx: InteractiveModeContext);
+    assistantViewportAnchorId(message: AssistantMessage): string;
+    getRenderedIrcInlineComponents(): Map<string, readonly Component[]>;
+    removeRenderedIrcInlineComponents(observationId: string): readonly Component[] | undefined;
+    resetRenderedIrcInlineComponents(): readonly (readonly Component[])[];
+    addLiveIrcObservationToChat(message: ParsedIrcMessage, arrival: IrcArrivalSnapshot): Component[];
+    addRebuiltIrcObservationToChat(message: ParsedIrcMessage): Component[];
+    resetIrcSidebarHint(): void;
     /** Extract text content from a user message */
     getUserMessageText(message: Message): string;
     /**
@@ -63,4 +73,3 @@ export declare class UiHelpers {
     findLastAssistantMessage(): AssistantMessage | undefined;
     extractAssistantText(message: AssistantMessage): string;
 }
-export {};

package/dist/types/notifications/config.d.ts

@@ -1,4 +1,14 @@
 import type { Settings } from "../config/settings";
+/**
+ * Env marker set by SKC's own programmatic separate-process child spawn sites
+ * (team workers, harness RPC owners) and carrying the spawning session id.
+ *
+ * Presence — not the value — marks a session as SKC-spawned. It is consumed
+ * (read once, then deleted from the child's own env) at startup so it is
+ * per-spawn rather than dynastic: a grandchild is marked only if its own spawn
+ * site marks it, never by inheriting a marked ancestor's environment.
+ */
+export declare const SPAWN_PROVENANCE_ENV = "SKC_SPAWNED_BY_SESSION";
 export interface NotificationConfig {
     enabled: boolean;
     botToken?: string;
@@ -13,6 +23,12 @@ export interface NotificationConfig {
     };
     redact: boolean;
     verbosity: "lean" | "verbose";
+    /**
+     * Which sessions may register a notification endpoint. `all` (default)
+     * preserves historical behavior; `primary` suppresses SKC-spawned children
+     * (those carrying {@link SPAWN_PROVENANCE_ENV}) unless they explicitly opt in.
+     */
+    sessionScope: "all" | "primary";
     idleTimeoutMs: number;
     rich: {
         enabled: boolean;
@@ -20,6 +36,15 @@ export interface NotificationConfig {
     richDraft: {
         enabled: boolean;
     };
+    topics: {
+        /**
+         * Optional Telegram forum-topic name template with `{repo}`, `{branch}`,
+         * and `{title}` placeholders. Unset preserves the built-in
+         * `{repo}/{branch} - {title}` composition (with its title/repo/branch
+         * fallbacks).
+         */
+        nameTemplate?: string;
+    };
 }
 /** Read typed config from Settings. */
 export declare function getNotificationConfig(settings: Settings): NotificationConfig;
@@ -51,6 +76,15 @@ export declare function shouldRegisterNotificationsExtension(input: {
     parentTaskPrefix?: string;
     /** Role-agent type/name; present for task sessions even if depth metadata is lost. */
     currentAgentType?: string;
+    /**
+     * True when this session was launched by one of SKC's own programmatic
+     * separate-process child spawn sites (marked via {@link SPAWN_PROVENANCE_ENV}).
+     * Under `notifications.sessionScope = "primary"` such children are suppressed
+     * unless they explicitly opt in, so an interactive parent that fans out work
+     * does not flood the paired chat with topics for children the user never
+     * asked for. User-opened sessions (CLI/tmux/headless) never carry the marker.
+     */
+    spawnedBySkc?: boolean;
 }): boolean;
 /**
  * Resolve whether THIS session should run notifications.

package/dist/types/notifications/daemon-paths.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Owner heartbeat freshness window. A daemon ownership record older than this
+ * (without a live pid) is considered stale. Lives here, in the lightweight
+ * paths module, so secret-safe consumers (e.g. the notification service) can
+ * reuse it without importing the heavy daemon runtime.
+ */
+export declare const HEARTBEAT_TTL_MS = 20000;
 export interface DaemonPaths {
     dir: string;
     lock: string;

package/dist/types/notifications/index.d.ts

@@ -176,6 +176,33 @@ export interface SessionReadyFrame {
  */
 export declare function readGitRepoName(cwd: string): string | undefined;
 export declare function notificationsEnabled(): boolean;
+/** Workflow-gate answer shape (unattended mode). */
+interface GateAnswer {
+    selected: string[];
+    other?: boolean;
+    custom?: string;
+}
+/**
+ * Discriminated result of mapping a client answer to a workflow-gate answer.
+ * `ok: false` means the reply is invalid and the caller must close the exact
+ * claim/receipt and reissue the interaction rather than durably accepting it.
+ */
+type GateAnswerResult = {
+    ok: true;
+    answer: GateAnswer;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Map a client answer to the workflow-gate answer shape (unattended mode).
+ *
+ * The protocol defines a numeric reply as an option index, so a number outside
+ * `options` is invalid (issue #2030): it must NOT be converted into a free-text
+ * `Other` that passes the ask schema and triggers a misleading success ack.
+ * Only JSON strings enter the free-text/Other path.
+ */
+export declare function mapAnswerToGate(answerJson: string, options: string[]): GateAnswerResult;
 interface NotificationControlCommandPayload {
     name?: unknown;
     action?: unknown;

package/dist/types/notifications/lifecycle-control-runtime.d.ts

@@ -1,3 +1,5 @@
+import { type OwnerIsolationProbe } from "../skc-runtime/tmux-owner-isolation";
+import { type SkcTmuxSessionStatus } from "../skc-runtime/tmux-sessions";
 import type { ResumeCandidate, SessionCreateFrame, SessionLifecycleRequest, SessionLifecycleResponse } from "./index";
 import { type AuditEvent, type CreateEffectResult, type LedgerStore, type LifecycleOutcome, type OrchestratorDeps, type ResumeEffectResult } from "./lifecycle-orchestrator";
 /** Minimal view of the native control server this runtime depends on. */
@@ -24,7 +26,6 @@ export type LifecycleControlServerFactory = (input: {
     ownerId: string;
     agentDir: string;
 }) => LifecycleControlServer;
-/** Atomic + fsynced file-backed idempotency ledger store. */
 export declare function fileLedgerStore(idempotencyFile: string): LedgerStore;
 /** Append-only JSONL audit sink (0600). Never receives tokens or raw prompts. */
 export declare function fileAudit(auditPath: string): (e: AuditEvent) => void;
@@ -44,14 +45,19 @@ export declare function buildCreateArgv(frame: SessionCreateFrame, _ids: {
     cwd: string;
     args: string[];
 };
-/** Real daemon-safe tmux launcher: detached `tmux new-session -d` + SKC tags. */
-export declare function daemonSpawnCreate(env?: NodeJS.ProcessEnv): (frame: SessionCreateFrame, ids: {
+/** Real daemon-safe tmux launcher: canonical owner-isolation plan + SKC tags. */
+export declare function daemonSpawnCreate(env?: NodeJS.ProcessEnv, opts?: {
+    ownerIsolationProbe?: OwnerIsolationProbe;
+}): (frame: SessionCreateFrame, ids: {
     lifecycleRequestId: string;
     intendedSessionId: string;
     startupPromptRef?: string;
 }) => Promise<CreateEffectResult>;
 /** Real force-close effect (SKC-managed only, id-matched). */
-export declare function daemonCloseSession(env?: NodeJS.ProcessEnv): (target: {
+export declare function daemonCloseSession(env?: NodeJS.ProcessEnv, deps?: {
+    forceClose?: (name: string, env: NodeJS.ProcessEnv, expectedSessionId?: string, sessionStateFile?: string) => Promise<void>;
+    findSession?: (name: string, env: NodeJS.ProcessEnv) => SkcTmuxSessionStatus | undefined;
+}): (target: {
     sessionId: string;
     tmuxSession?: string;
     sessionStateFile?: string;
@@ -63,6 +69,8 @@ export declare function daemonCloseSession(env?: NodeJS.ProcessEnv): (target: {
  *  cold-restarting exactly one resolved session via the daemon-safe launcher. */
 export declare function daemonResumeSession(env?: NodeJS.ProcessEnv, opts?: {
     sessionsRoot?: string;
+    listSessions?: (env: NodeJS.ProcessEnv) => SkcTmuxSessionStatus[];
+    ownerIsolationProbe?: OwnerIsolationProbe;
 }): (target: {
     sessionIdOrPrefix: string;
     path?: string;

package/dist/types/notifications/notification-service.d.ts

@@ -0,0 +1,144 @@
+import type { Settings } from "../config/settings";
+/**
+ * Strip secrets from a human-facing diagnostic string. Redacts the configured
+ * bot token (exact match) and any token-shaped substring so health/test details
+ * can never leak a credential regardless of where the string originated.
+ */
+export declare function sanitizeDiagnostic(text: string, token?: string): string;
+/** Minimal filesystem surface the service needs; injectable for tests. */
+export interface NotificationServiceFs {
+    readdir(dir: string): Promise<string[]>;
+    readFile(file: string, encoding: "utf8"): Promise<string>;
+    unlink(file: string): Promise<void>;
+    /**
+     * Atomically create `file` with O_EXCL semantics: resolves `true` when this
+     * call created it, `false` when it already existed. Used to hold the daemon
+     * steal-mutex ({@link DaemonPaths.steal}) during owner-bound lock removal so
+     * recovery and a concurrent daemon takeover are mutually exclusive.
+     */
+    createExclusive(file: string): Promise<boolean>;
+}
+/** Injectable dependencies shared across service operations. */
+export interface NotificationServiceDeps {
+    fs?: NotificationServiceFs;
+    now?: () => number;
+    pidAlive?: (pid: number) => boolean;
+    fetchImpl?: typeof fetch;
+    apiBase?: string;
+}
+export interface AdapterConfigView {
+    botTokenMasked: string;
+    channel: string | undefined;
+    configured: boolean;
+}
+export interface NotificationStatusReport {
+    enabled: boolean;
+    redact: boolean;
+    verbosity: "lean" | "verbose";
+    globallyConfigured: boolean;
+    telegram: AdapterConfigView & {
+        tokenFingerprint: string | undefined;
+    };
+    discord: AdapterConfigView;
+    slack: AdapterConfigView;
+}
+/** Build a secret-safe structured status snapshot from settings. */
+export declare function buildNotificationStatusReport(settings: Settings): NotificationStatusReport;
+/** Render a status report as human-readable lines (no secrets). */
+export declare function formatNotificationStatusReport(report: NotificationStatusReport): string;
+export type HealthLevel = "ok" | "warn" | "error";
+export interface HealthCheck {
+    name: string;
+    level: HealthLevel;
+    detail: string;
+}
+export interface DaemonHealth {
+    present: boolean;
+    ownerId: string | undefined;
+    pid: number | undefined;
+    alive: boolean;
+    heartbeatFresh: boolean;
+    identityMatches: boolean;
+    stopped: boolean;
+}
+export interface EndpointHealth {
+    total: number;
+    live: number;
+    dead: number;
+    unknown: number;
+    unreadable: number;
+}
+export interface NotificationHealthReport {
+    overall: HealthLevel;
+    configured: boolean;
+    checks: HealthCheck[];
+    daemon: DaemonHealth;
+    endpoints: EndpointHealth;
+    reachability: {
+        probed: boolean;
+        ok: boolean;
+        detail: string;
+    };
+}
+export interface HealthOptions {
+    settings: Settings;
+    stateRoot?: string;
+    deps?: NotificationServiceDeps;
+    /** When true and Telegram is configured, probe the Bot API (getMe) for reachability. */
+    probe?: boolean;
+}
+/** Structural (offline-by-default) health of the notification subsystem. */
+export declare function checkNotificationHealth(opts: HealthOptions): Promise<NotificationHealthReport>;
+/** Render a health report as human-readable lines (no secrets). */
+export declare function formatNotificationHealthReport(report: NotificationHealthReport): string;
+export interface NotificationTestResult {
+    ok: boolean;
+    adapter: "telegram";
+    chatId: string | undefined;
+    detail: string;
+}
+export interface TestOptions {
+    settings: Settings;
+    deps?: NotificationServiceDeps;
+    text?: string;
+}
+/** Send a one-off test notification through the configured Telegram adapter. */
+export declare function sendNotificationTest(opts: TestOptions): Promise<NotificationTestResult>;
+/** Render a test result as a single human-readable line (no secrets). */
+export declare function formatNotificationTestResult(result: NotificationTestResult): string;
+export interface RecoveredEndpoint {
+    sessionId: string;
+    pid: number | undefined;
+    reason: "stale-flag" | "dead-pid";
+}
+export type DaemonRecoveryAction = "none" | "cleared-dead-owner-lock" | "left-active" | "left-contended" | "owner-superseded" | "orphan-lock-left";
+export interface NotificationRecoveryReport {
+    endpointsScanned: number;
+    endpointsRemoved: RecoveredEndpoint[];
+    endpointsKept: number;
+    endpointsUnreadable: number;
+    daemon: {
+        action: DaemonRecoveryAction;
+        detail: string;
+        ownerId: string | undefined;
+        pid: number | undefined;
+    };
+}
+export interface RecoveryOptions {
+    settings: Settings;
+    stateRoot?: string;
+    deps?: NotificationServiceDeps;
+}
+/**
+ * Ownership-protected cleanup. Removes only DEAD-owner artifacts:
+ * per-session endpoint files with positive proof of death (a stale tombstone or
+ * a dead recorded pid), and a daemon lock whose recorded owner is confirmed
+ * dead. A PID-less endpoint is treated as unknown (not dead) and kept. The
+ * daemon lock is removed through {@link removeDeadOwnerLock}, an owner-bound
+ * primitive that re-checks ownership under the daemon steal-mutex so it can
+ * never race a concurrent takeover. Never removes a live owner's lock, never
+ * deletes unreadable files, and never kills a process.
+ */
+export declare function recoverNotifications(opts: RecoveryOptions): Promise<NotificationRecoveryReport>;
+/** Render a recovery report as human-readable lines (no secrets). */
+export declare function formatNotificationRecoveryReport(report: NotificationRecoveryReport): string;

package/dist/types/notifications/rate-limit-pool.d.ts

@@ -29,11 +29,15 @@ export interface RateLimitItem<T = unknown> {
     /** Priority lane. */
     lane: RateLimitLane;
     /**
-     * Optional coalesce key. Submitting another item with the same
-     * `(sessionId, lane, coalesceKey)` replaces the queued payload with the
-     * newer one instead of enqueuing a duplicate (used for live edits).
+     * Optional coalesce key. Submitting another unidentifiable item with the
+     * same `(sessionId, lane, coalesceKey)` replaces the queued payload with
+     * the newer one instead of enqueuing a duplicate (used for live edits).
      */
     coalesceKey?: string;
+    /** Optional stable identifier for exact queued-item removal. Identified items never coalesce. */
+    itemId?: string;
+    /** Absolute Unix timestamp in ms. The item expires when `now >= deadlineAt`. */
+    deadlineAt?: number;
     /** Opaque payload the caller maps to an actual Telegram send. */
     payload: T;
 }
@@ -46,6 +50,13 @@ export interface RateLimitPoolOptions {
     /** Injectable clock in ms. Default `Date.now`. */
     now?: () => number;
 }
+/** The deterministic result of draining queued work at a point in time. */
+export interface RateLimitDrainResult<T = unknown> {
+    /** Items granted a token and ready to send. */
+    granted: RateLimitItem<T>[];
+    /** Items removed because their absolute deadline has elapsed. */
+    expired: RateLimitItem<T>[];
+}
 /**
  * A deterministic, pull-based shared rate-limit scheduler.
  *
@@ -70,19 +81,26 @@ export declare class RateLimitPool<T = unknown> {
     /** Current available token count (after refill at `now`). */
     availableTokens(nowMs?: number): number;
     /**
-     * Submit an item. If it carries a `coalesceKey` matching a queued item in
-     * the same `(sessionId, lane)`, the queued payload is replaced (latest
-     * wins) and FIFO position is preserved; otherwise it is appended.
+     * Submit an item. Unidentified items with a `coalesceKey` matching a queued
+     * item in the same `(sessionId, lane)` replace its payload (latest wins)
+     * while preserving FIFO position; identified items are always appended.
      */
     submit(item: RateLimitItem<T>): void;
     /**
-     * Grant as many queued items as tokens allow at `nowMs`. Items are selected
-     * by lane priority, then round-robin across sessions within a lane (so no
-     * single session monopolises a lane), consuming one token each.
+     * Grant as many queued items as tokens allow at `nowMs`. This compatibility
+     * wrapper discards items that expired during the drain.
      */
     drain(nowMs?: number): RateLimitItem<T>[];
+    /**
+     * Deterministically expire elapsed-deadline items, then grant as many live
+     * items as tokens allow. Expired items never consume tokens or receive a
+     * grant; both result lists preserve their deterministic queue ordering.
+     */
+    drainWithExpired(nowMs?: number): RateLimitDrainResult<T>;
     /** Remove queued items matching `predicate` without consuming tokens. Returns removed items in lane/FIFO order. */
     removeWhere(predicate: (item: RateLimitItem<T>) => boolean): RateLimitItem<T>[];
+    /** Remove exactly one queued item by its stable id without consuming a token. */
+    removeById(itemId: string): RateLimitItem<T> | undefined;
     private refill;
     /** Pop the next item by lane priority + per-session round-robin fairness. */
     private takeNext;

package/dist/types/notifications/telegram-daemon-control.d.ts

@@ -55,10 +55,16 @@ export declare class TelegramDaemonController implements BuiltInDaemonController
     status(): Promise<DaemonStatus>;
     private spawnDeps;
     private sleep;
+    /**
+     * Wait until the captured pid is dead. Ownership-file movement is NOT treated
+     * as quiescence here: only actual process death proves the old poller stopped,
+     * which is what the no-409 invariant requires before spawning a fresh poller.
+     */
     private waitForPidDeath;
     private result;
     reload(opts?: DaemonOperationOptions): Promise<DaemonOperationResult>;
     stop(opts?: DaemonOperationOptions): Promise<DaemonOperationResult>;
     private stopOrReload;
+    /** Clear our own control request unless a newer owner-scoped request replaced it. */
     private clearOwnRequest;
 }