@gajae-code/coding-agent 0.11.0 → 0.11.2

package/dist/types/sdk/bus/rate-limit-pool.d.ts

@@ -41,6 +41,11 @@ export interface RateLimitItem<T = unknown> {
     /** Opaque payload the caller maps to an actual Telegram send. */
     payload: T;
 }
+export type RateLimitDisposition = "queued" | "sending" | "accepted" | "rejected" | "ambiguous" | "removed" | "expired";
+export interface RateLimitHandle {
+    itemId: string;
+    settled: Promise<Exclude<RateLimitDisposition, "queued" | "sending">>;
+}
 /** Options for {@link RateLimitPool}. */
 export interface RateLimitPoolOptions {
     /** Burst capacity (max tokens). Default 20 (Telegram per-chat burst). */
@@ -74,6 +79,7 @@ export declare class RateLimitPool<T = unknown> {
     private readonly laneCursor;
     private tokens;
     private lastRefill;
+    private readonly settlements;
     private seqCounter;
     constructor(options?: RateLimitPoolOptions);
     /** Number of items currently queued across all lanes. */
@@ -85,7 +91,12 @@ export declare class RateLimitPool<T = unknown> {
      * 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;
+    submit(item: RateLimitItem<T>): RateLimitHandle;
+    /** Settle a stable item after its external transport effect has a known outcome. */
+    settle(itemId: string, disposition: Exclude<RateLimitDisposition, "queued" | "sending">): void;
+    /** Mark a granted item as owned by an external transport effect. */
+    markSending(itemId: string): void;
+    private handle;
     /**
      * Grant as many queued items as tokens allow at `nowMs`. This compatibility
      * wrapper discards items that expired during the drain.
@@ -98,7 +109,7 @@ export declare class RateLimitPool<T = unknown> {
      */
     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>[];
+    removeWhere(predicate: (item: RateLimitItem<T>) => boolean, disposition?: Exclude<RateLimitDisposition, "queued" | "sending">): RateLimitItem<T>[];
     /** Remove exactly one queued item by its stable id without consuming a token. */
     removeById(itemId: string): RateLimitItem<T> | undefined;
     private refill;

package/dist/types/sdk/bus/recent-activity.d.ts

@@ -1,8 +1,8 @@
 /** One ranked recent-session entry surfaced to the picker. */
 export interface RecentSessionEntry {
-    /** Session id (the `.jsonl` file stem). */
+    /** Session id from the validated managed candidate header. */
     sessionId: string;
-    /** Working directory / repo path, when recoverable from the header. */
+    /** Validated workspace path recorded by the managed candidate. */
     path?: string;
     /** Branch, when recoverable from the header. */
     branch?: string;
@@ -18,22 +18,31 @@ export interface RecentSessionEntry {
     internal?: boolean;
 }
 export interface RecentActivityDeps {
-    /** Root holding `<encoded-cwd>/<sessionId>.jsonl` history files. */
-    sessionsRoot: string;
+    /** Workspace whose managed sessions will be listed readonly. */
+    cwd: string;
+    /** Agent directory used to resolve the managed session scope. */
+    agentDir?: string;
+    /** Explicit managed root for isolated tests. */
+    sessionsRoot?: string;
     /** Optional breadcrumb session-file paths (current terminals). */
     breadcrumbPaths?: string[];
     /** Max entries to return (default 20). */
     limit?: number;
     /** Include internal helper/sub-agent sessions (default true). */
     includeInternal?: boolean;
+    /** Search every validated v2 workspace scope below the session root (default false). */
+    allWorkspaces?: boolean;
     /** Injection seam for tests. */
     readInitialLines?: (file: string, maxLines: number) => string[];
 }
-/**
- * List recent sessions ranked by history-file mtime (newest first).
- *
- * Scans `<sessionsRoot>/<encoded-cwd>/<sessionId>.jsonl`, stats each file, and
- * returns up to `limit` entries enriched with header metadata and a
- * `currentTerminal` flag for any breadcrumb-referenced session file.
- */
-export declare function listRecentSessions(deps: RecentActivityDeps): RecentSessionEntry[];
+/** Lists readonly managed candidates, optionally across every validated v2 workspace scope, ranked by history-file mtime. */
+export type ListRecentSessionsResult = {
+    kind: "complete";
+    entries: RecentSessionEntry[];
+    warnings: readonly string[];
+} | {
+    kind: "error";
+    code: "scope_unavailable" | "managed_scan_failed";
+    message: string;
+};
+export declare function listRecentSessions(deps: RecentActivityDeps): Promise<ListRecentSessionsResult>;

package/dist/types/sdk/bus/rich-document.d.ts

@@ -0,0 +1,7 @@
+export type RichEligibility = {
+    kind: "eligible";
+} | {
+    kind: "ineligible";
+};
+/** Conservatively recognize `/btw` Markdown that can be represented as rich content. */
+export declare function parseRichEligibility(markdown: string): RichEligibility;

package/dist/types/sdk/bus/rich-render.d.ts

@@ -2,26 +2,17 @@
  * Rich-message promotion for stable non-editable Telegram text sends.
  *
  * When enabled, the daemon promotes eligible finalized `sendMessage` payloads
- * carrying raw markdown to the Bot API `sendRichMessage` method. On any miss or
- * failure the daemon keeps the unchanged HTML `sendMessage` path, so the
- * off-state request bodies are byte-identical.
+ * carrying raw markdown to Bot API `sendRichMessage`. Only an explicit
+ * `{ ok: false }` response selects the unchanged HTML path; ambiguous transport
+ * outcomes remain single-attempt and never fall back.
  */
 import type { BotApi } from "./telegram-daemon";
 import type { ThreadedSend } from "./threaded-render";
 /**
- * Telegram's hard per-message character ceiling (4096). Surfaced here purely as
- * documentation and a marker for a future native rich-message splitter — it is
- * intentionally NON-BEHAVIORAL and MUST stay that way: nothing in the rich path
- * branches on this value.
- *
- * Overflow is already safe without it. The production final-answer text is capped
- * at 3500 chars upstream (`summaryFromMessage(..., 3500)`), so a promoted
- * `sendRichMessage` never approaches this ceiling; and if the Bot API ever rejects
- * an oversized rich payload it returns `{ ok: false }`, which
- * `deliverRichWithFallback` (below) turns into the chunked HTML `splitTelegramHtml`
- * fallback (each chunk ≤ TELEGRAM_MESSAGE_LIMIT). This constant only marks where a
- * future rich splitter would read its ceiling; wiring it into a branch would change
- * byte-for-byte behavior and is out of scope.
+ * Telegram's hard per-message character ceiling (4096). Final-answer promotion
+ * uses this value to keep oversized Markdown on the existing chunked HTML path.
+ * `/btw` eligibility has its own 32,768-scalar route guard; only a definite
+ * rich rejection may select the correlated HTML path.
  */
 export declare const RICH_MESSAGE_LIMIT = 4096;
 /** Wrap raw markdown in the `sendRichMessage` request payload shape. */
@@ -30,9 +21,12 @@ export declare function buildRichMessage(raw: string, extras?: {
 }): {
     rich_message: {
         markdown: string;
+        skip_entity_detection: true;
     };
     reply_markup?: unknown;
 };
+/** Whether `/btw` Markdown may use Bot API 10.1 rich delivery. */
+export declare function isBtwRichEligible(markdown: string): boolean;
 /**
  * Whether a granted send should be promoted to `sendRichMessage`. Fail-closed
  * and class-aware: every clause must hold, otherwise the daemon keeps the HTML path.
@@ -42,37 +36,21 @@ export declare function shouldPromoteRich(input: {
     send: ThreadedSend;
 }): boolean;
 /**
- * Deliver the promoted rich message, falling back to `fallbackDeliver` (the
- * unchanged HTML `sendMessage` loop) on any failure. A failure is either a
- * thrown transport error or a `{ ok: false }` JSON response (the transport
- * returns `res.json()` for JSON methods, so `ok:false` does not throw). On
- * failure exactly one diagnostic is logged before the fallback runs; on success
- * the fallback never runs.
- *
- * Returns the sent message's `message_id` on success (when the response carries
- * one), otherwise `undefined` — including every failure/fallback path and a
- * success whose response omits `result.message_id`. Callers that ignore the
- * return value are unaffected.
+ * Deliver the promoted rich message, falling back to `fallbackDeliver` only
+ * after an explicit `{ ok: false }` response. Transport errors and malformed or
+ * ambiguous responses are logged but never retried or sent again through HTML.
  */
 export declare function deliverRichWithFallback(botApi: BotApi, base: {
     chat_id: string | number;
     message_thread_id?: number;
-}, send: ThreadedSend, fallbackDeliver: () => Promise<void>, log?: {
+}, send: ThreadedSend, signal: AbortSignal, fallbackDeliver: () => Promise<void>, log?: {
     warn(msg: string): void;
 }): Promise<number | undefined>;
 /**
  * Deliver an action-needed (ask/idle) message via `sendRichMessage`, falling
- * back to the unchanged HTML chunk loop on any failure. Mirrors
- * {@link deliverRichWithFallback} but takes an explicit markdown body plus an
- * optional top-level `reply_markup` (probe-confirmed: `sendRichMessage` accepts
- * `reply_markup` alongside `rich_message`), and surfaces a structured outcome so
- * the daemon can route inbound replies to the resulting message id.
- *
- * On rich success: returns `{ messageId, usedRich: true, usedFallback: false }`
- * where `messageId` is `res.result.message_id` when present. On a `{ ok:false }`
- * response or a thrown transport error: warns exactly once, runs `htmlFallback`,
- * and returns `{ messageId, usedRich: false, usedFallback: true }` where
- * `messageId` is the fallback's return value (the last HTML chunk's id).
+ * back to the unchanged HTML chunk loop only after an explicit `{ ok:false }`
+ * response. Other outcomes are ambiguous, are logged, and preserve the single
+ * physical rich delivery.
  */
 export declare function deliverRichActionWithFallback(botApi: BotApi, base: {
     chat_id: string | number;
@@ -80,8 +58,7 @@ export declare function deliverRichActionWithFallback(botApi: BotApi, base: {
 }, opts: {
     markdown: string;
     replyMarkup?: unknown;
-    requireMessageId?: boolean;
-}, htmlFallback: () => Promise<number | undefined>, log?: {
+}, signal: AbortSignal, htmlFallback: () => Promise<number | undefined>, log?: {
     warn(msg: string): void;
 }): Promise<{
     messageId?: number;

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

@@ -5,8 +5,13 @@
 /** 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.
+ * Operational generation the current daemon build speaks. Decoupled from
+ * {@link NOTIFICATION_PROTOCOL_VERSION} (#2304): additive `tool_activity` /
+ * `reasoning_summary` frames do not bump the wire protocol version, but a
+ * freshly-upgraded host must still recognize an older, still-live daemon that
+ * predates capability-gated frame enforcement and trigger a reload. Bump this
+ * on every daemon-behavior change independent of the wire version.
+ * The current development baseline already includes #2299's generation 4;
+ * this behavior change therefore advances the operational generation to 5.
  */
-export declare const DAEMON_GENERATION = 3;
+export declare const DAEMON_GENERATION = 5;

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

@@ -18,6 +18,11 @@ export interface DaemonState {
     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.
+     */
+    launcherPid?: number;
     version: 1;
     /**
      * Operational daemon generation of the process that owns the lock, distinct
@@ -55,6 +60,8 @@ export interface TelegramDaemonDeps {
         logPath?: string;
     }) => SpawnResult;
     execPath?: string;
+    /** Injectable platform seam for source-linked Windows daemon spawning. */
+    platform?: NodeJS.Platform;
     randomId?: () => string;
     /**
      * Signal delivery + poll timing for the stale-generation reload handoff in
@@ -73,6 +80,11 @@ export declare const CLIENT_PING_PONG_CAPABILITY = "client_ping_pong";
 /** 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";
+/** Capability required for tool lifecycle and reasoning-summary frames. */
+export declare const TOOL_ACTIVITY_CAPABILITY = "tool_activity_v1";
+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;
 /**
@@ -126,6 +138,10 @@ export declare function acquireDaemonOwnership(input: {
     pid?: number;
     pidAlive?: (pid: number) => boolean;
     randomId?: () => string;
+    /** Permit one Windows source launcher PID to daemon PID handoff. */
+    allowPidRebind?: boolean;
+    /** A caller-supplied opaque owner identity, used when the launcher PID is not durable. */
+    ownerId?: string;
 }): Promise<{
     acquired: boolean;
     ownerId?: string;
@@ -137,13 +153,22 @@ export declare function acquireDaemonOwnership(input: {
 export declare function renewDaemonHeartbeat(input: {
     settings: Settings;
     ownerId: string;
+    /** Bind a daemon heartbeat to the Telegram identity that acquired the lock. */
+    tokenFingerprint: string;
+    chatId: string;
+    /** Require the current daemon PID after the launcher-to-daemon PID rebind. */
+    pid: number;
     fs?: TelegramDaemonFs;
     now?: () => number;
-    pid?: number;
 }): Promise<boolean>;
 export declare function releaseDaemonOwnership(input: {
     settings: Settings;
     ownerId: string;
+    /** Bind release to the Telegram identity that acquired the lock. */
+    tokenFingerprint: string;
+    chatId: string;
+    /** Require the current daemon PID after the launcher-to-daemon PID rebind. */
+    pid: number;
     fs?: TelegramDaemonFs;
     now?: () => number;
 }): Promise<void>;
@@ -230,17 +255,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 {
@@ -275,6 +323,9 @@ export interface TelegramDaemonOptions {
     clearTimeoutImpl?: typeof clearTimeout;
     setIntervalImpl?: typeof setInterval;
     clearIntervalImpl?: typeof clearInterval;
+    btw?: {
+        enabled: boolean;
+    };
     idleTimeoutMs?: number;
     scanIntervalMs?: number;
     pid?: number;
@@ -323,6 +374,8 @@ interface SessionSocket {
     logicalSessionId: string;
     token: string;
     endpointKey: string;
+    endpointDigest: string;
+    hostGeneration: number;
     ws: WebSocket;
     pending: Map<string, {
         sessionId: string;
@@ -330,6 +383,7 @@ interface SessionSocket {
     }>;
     /** True once the server advertised the `client_ping_pong` capability. */
     capable: boolean;
+    ephemeralCapable: boolean;
     /** 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. */
@@ -357,6 +411,7 @@ export declare class TelegramNotificationDaemon {
     private running;
     private readonly fsImpl;
     private readonly botApi;
+    private readonly effects;
     private readonly topics;
     /** Serializes registry snapshots so an older atomic write cannot overwrite newer rename state. */
     private topicsPersistQueue;
@@ -453,7 +508,7 @@ export declare class TelegramNotificationDaemon {
     persistSeenUpdateIds(): Promise<void>;
     private pruneSeenUpdateIds;
     private rememberSeenUpdateId;
-    private rememberSeenUpdateIdForUnavailableNotice;
+    private reserveSeenUpdateId;
     scanRoots(): Promise<void>;
     connectSession(sessionId: string, url: string, token: string): void;
     /**
@@ -490,6 +545,9 @@ export declare class TelegramNotificationDaemon {
     private sessionCanClaimIdentity;
     private submitThreadedFrame;
     private existingTopicForPrivateChat;
+    private topicAuthorityLease;
+    private topicAuthorityLeaseFromRegistry;
+    private topicLeaseIsCurrent;
     /** Best-effort re-assertion for a durable user-owned topic name. */
     private reconcileUserTopicName;
     private rememberPendingThreadedFrame;
@@ -502,7 +560,7 @@ export declare class TelegramNotificationDaemon {
      */
     private ensureTopic;
     private topicPastOrphanGrace;
-    private deleteOrphanedTopic;
+    private observeOrphanedTopic;
     /** Best-effort delete of a session topic once its local notification endpoint shuts down. */
     private deleteTopic;
     private persistTopics;
@@ -540,6 +598,7 @@ 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;
     /**
      * Track the Telegram message id backing a streamed `(sessionId, coalesceKey)`
@@ -570,6 +629,13 @@ export declare class TelegramNotificationDaemon {
     private notifyThreadedFallback;
     private startFlushTimer;
     private stopFlushTimer;
+    private renewOwnershipHeartbeat;
+    /**
+     * 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;
     /** Run a root scan, guarding against overlapping scans from the timer + loop. */
     private runScan;
     private startScanTimer;

package/dist/types/sdk/bus/threaded-inbound.d.ts

@@ -60,7 +60,7 @@ export type ThreadedInboundDecision = {
     text: string;
     updateId: number;
     threadId: string;
-    messageId?: number;
+    messageId: number;
     attachment?: InboundAttachment;
 } | {
     kind: "duplicate";

package/dist/types/sdk/bus/threaded-render.d.ts

@@ -41,6 +41,13 @@ export interface ThreadedSend {
     richMarkdown?: string;
     /** Live-turn raw markdown for opt-in draft streaming (set ONLY on non-finalized turn frames; never triggers rich-final promotion, which requires `lane === "finalized"`). */
     richDraftMarkdown?: string;
+    /**
+     * True for a terminal tool_activity frame (phase completed/failed/cancelled/
+     * unknown). The daemon evicts the tool's `tool:<toolCallId>` live-message entry
+     * after delivering it, so completed tools do not accumulate unbounded across a
+     * long session (concurrent in-flight `started` entries are retained).
+     */
+    terminal?: boolean;
 }
 interface ThreadedFrame {
     type?: unknown;
@@ -60,6 +67,12 @@ interface ThreadedFrame {
     finalAnswer?: boolean;
     text?: unknown;
     messageRef?: unknown;
+    turnRef?: unknown;
+    toolCallId?: unknown;
+    toolName?: unknown;
+    argsSummary?: unknown;
+    resultSummary?: unknown;
+    isError?: unknown;
     source?: unknown;
     data?: unknown;
     mime?: unknown;

package/dist/types/sdk/bus/topic-registry.d.ts

@@ -20,6 +20,8 @@ export interface TopicRecord {
     identitySent: boolean;
     /** Creation timestamp (ms epoch). */
     createdAt: number;
+    /** First positive observation that the owning endpoint is stale, dead, or missing. */
+    orphanedAt?: number;
     /** Last applied or observed Telegram topic title. */
     name?: string;
     /** Naming authority. Missing values are legacy daemon-owned records. */
@@ -34,11 +36,17 @@ export interface TopicRecord {
     replayGeneration?: number;
     /** Last SDK event sequence durably consumed within replayGeneration. */
     replaySeq?: number;
+    /** Serialized authority epoch; a late create may commit only in its starting epoch. */
+    authorityEpoch?: number;
+    /** An uncertain delete fences future creation and inbound routing. */
+    authorityState?: "active" | "delete_pending";
 }
 /** Serialisable shape persisted to disk. */
 export interface TopicRegistryState {
     /** sessionId -> record. */
     topics: Record<string, TopicRecord>;
+    /** Durable deletion epochs retained after a definite delete. */
+    fences?: Record<string, number>;
 }
 export declare function emptyTopicRegistryState(): TopicRegistryState;
 /**
@@ -47,14 +55,18 @@ export declare function emptyTopicRegistryState(): TopicRegistryState;
  * `createForumTopic` call); reuse-on-resume is automatic when a record exists.
  */
 export declare class TopicRegistry {
+    #private;
     private readonly topics;
     /** Maps topicId -> sessionId for fast inbound routing. */
     private readonly byTopic;
     /** In-flight create promises, keyed by session, to dedupe concurrent creates. */
     private readonly inflight;
+    /** Monotonic authority epochs, including deletion fences for absent records. */
+    private readonly epochs;
     constructor(state?: TopicRegistryState);
     /** Merge serialized state and normalize authority fields from older releases. */
     load(state: TopicRegistryState): void;
+    private rebuildInboundRoutes;
     /** Resolve the owning session for a topic id (for fail-closed inbound routing). */
     sessionForTopic(topicId: string): string | undefined;
     /** All session ids with a persisted topic record. */
@@ -65,13 +77,17 @@ export declare class TopicRegistry {
      * Return the existing active topic for `sessionId`, or create one via
      * `create` (called only on first use).
      */
-    getOrCreateTopic(sessionId: string, create: () => Promise<string>, now?: () => number, name?: string): Promise<TopicRecord>;
+    getOrCreateTopic(sessionId: string, create: () => Promise<unknown>, now?: () => number, name?: string): Promise<TopicRecord>;
     /** Mark the identity header as sent for a session. Idempotent. */
     markIdentitySent(sessionId: string): void;
     /** Whether the identity header still needs sending for this session. */
     needsIdentity(sessionId: string): boolean;
     /** Remember stable repo/branch identity independently of the displayed name. */
     markIdentityKey(sessionId: string, identityKey: string): boolean;
+    /** Start the orphan grace clock on the first positive liveness-loss observation. */
+    markOrphaned(sessionId: string, now: number): boolean;
+    /** Clear a prior orphan observation after the endpoint is positively live again. */
+    clearOrphaned(sessionId: string): boolean;
     /** Last durably consumed SDK event cursor for reconnect replay. */
     replayCursor(sessionId: string): {
         generation: number;
@@ -93,7 +109,13 @@ export declare class TopicRegistry {
     markUserNamePending(sessionId: string, name: string): boolean;
     /** Commit a successfully-applied daemon topic title. */
     markNameApplied(sessionId: string, name: string): void;
-    /** Remove a session topic record after Telegram deletes the topic. */
+    /** Fence new work before the remote delete starts, including an absent in-flight create. */
+    beginDelete(sessionId: string): TopicRecord | undefined;
+    /** Wait for a revoked create to settle before admitting a later lifecycle epoch. */
+    awaitInflight(sessionId: string): Promise<void>;
+    /** Remove only after a definite remote deletion; ambiguity deliberately retains its fence. */
+    settleDelete(sessionId: string, topicId: string): boolean;
+    /** Remove a topic record immediately for local/test cleanup compatibility. */
     delete(sessionId: string): boolean;
     /** Serialise for atomic persistence beside the daemon state. */
     serialize(): TopicRegistryState;

package/dist/types/sdk/host/control/operations.d.ts

@@ -11,7 +11,7 @@ export interface ControlSurface {
     abort(): Promise<ControlValue> | ControlValue;
     abortAndPrompt(text: string): Promise<ControlValue> | ControlValue;
     answerAsk(id: string, answer: ControlValue): Promise<ControlValue> | ControlValue;
-    answerGate(id: string, response: ControlValue, expectedSessionId?: string): Promise<ControlValue> | ControlValue;
+    answerGate(id: string, response: ControlValue, expectedSessionId?: string, idempotencyKey?: string): Promise<ControlValue> | ControlValue;
     approvePlan(id: string, choice: ControlValue, expectedSessionId?: string): Promise<ControlValue> | ControlValue;
     invokeSkill(name: string, args: ControlValue): Promise<ControlValue> | ControlValue;
     setPlanMode(on: boolean): Promise<ControlValue> | ControlValue;

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

@@ -12,6 +12,8 @@ export interface SessionSdkHostOptions extends HostEndpointAdapters {
     installProviderDefinitions?: (capability: string, definitions: unknown) => void;
     onProviderDefinitionsRemoved?: (capability: string) => void;
     onReverseCancel?: (requestId: string, reason: "provider_disconnected" | "lease_released") => void;
+    /** Best-effort capabilities mirrored from the native transport for out-of-band consumers. */
+    connectionCapabilities?: (connectionId: string) => ReadonlySet<string>;
 }
 /** SDK hosting is independent of notification configuration. Only root sessions host an endpoint. */
 export declare function shouldHostSdk(_settings: unknown, isTopLevel: boolean, env?: NodeJS.ProcessEnv): boolean;

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

@@ -4,3 +4,4 @@ export * as host from "./host";
 export * as mcp from "./mcp";
 export type { Q10CurrentThinkingLevel, Q10Model, Q10SettableThinkingLevel, Q10ThinkingCapabilities, Q10ThinkingEffort, Q10ThinkingMode, } from "./models";
 export * from "./session";
+export * from "./session-directory";

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

@@ -0,0 +1,56 @@
+import type { ResumeSessionIdentity } from "../session/session-manager";
+/** Version of the supported readonly managed-session directory API. */
+/** Broker-owned policy for managed-session migration decisions after scope validation. */
+export type DirectoryMigrationPolicy = "copy-retain" | "disabled";
+export declare const SESSION_DIRECTORY_API_VERSION: 1;
+/** A collision-resistant v2 managed-session scope for one canonical workspace identity. */
+export interface ManagedSessionScope {
+    readonly apiVersion: 1;
+    readonly layoutVersion: 2;
+    readonly identityVersion: 1;
+    readonly agentDir: string;
+    readonly sessionsRoot: string;
+    readonly canonicalCwd: string;
+    readonly legacyLexicalCwd: string;
+    readonly directoryName: string;
+    readonly directoryPath: string;
+}
+export type ResolveManagedSessionScopeResult = {
+    kind: "resolved";
+    scope: ManagedSessionScope;
+} | {
+    kind: "error";
+    code: "cwd_missing" | "cwd_not_directory" | "identity_unavailable" | "network_unsupported" | "sessions_root_unavailable" | "binding_conflict" | "binding_invalid";
+    message: string;
+};
+export interface LogicalSessionCandidate {
+    readonly sessionId: string;
+    readonly path: string;
+    readonly cwd: string;
+    readonly provenance: "v2" | "legacy";
+    readonly identity: Readonly<ResumeSessionIdentity>;
+    readonly migrationState: "native_v2" | "legacy_unmigrated" | "migrated_v2";
+}
+export type ListManagedSessionCandidatesResult = {
+    kind: "complete";
+    scope: ManagedSessionScope;
+    owned: readonly LogicalSessionCandidate[];
+    foreignCount: number;
+    invalid: readonly {
+        code: string;
+    }[];
+} | {
+    kind: "error";
+    code: "scan_failed" | "unsafe_root" | "invalid_candidate";
+    message: string;
+};
+/** Resolve a v2 scope without creating, migrating, or deleting session data. */
+export declare function resolveManagedSessionScope(input: {
+    cwd: string;
+    agentDir?: string;
+    sessionsRoot?: string;
+}): Promise<ResolveManagedSessionScopeResult>;
+/** List readonly v2 and validated legacy candidates for an already resolved scope. */
+export declare function listManagedSessionCandidates(input: {
+    scope: ManagedSessionScope;
+}): Promise<ListManagedSessionCandidatesResult>;