@sayknow-cli/coding-agent 0.3.12 → 0.3.15

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

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import type { Settings } from "../config/settings";
 import type { DaemonRuntimeInfo } from "../daemon/control-types";
+import { HEARTBEAT_TTL_MS } from "./daemon-paths";
 import { type ControlServerLike, type LifecycleControlServerFactory } from "./lifecycle-control-runtime";
 import { NotificationOperatorRuntime, OperatorBackoffPolicy } from "./operator-runtime";
 import { type AliasTable, type CallbackRoute } from "./telegram-reference";
@@ -14,6 +15,14 @@ export interface DaemonState {
     heartbeatAt: number;
     roots: string[];
     version: 1;
+    /**
+     * Operational daemon generation of the process that owns the lock, distinct
+     * from the persisted state-schema {@link DaemonState.version}. It records the
+     * wire generation ({@link DAEMON_GENERATION}) the owning daemon speaks so a
+     * freshly-upgraded host can detect — and reload — a still-live pre-upgrade
+     * daemon whose schema version is unchanged. Absent on pre-generation state.
+     */
+    generation?: number;
     stoppedAt?: number;
 }
 export interface TelegramDaemonFs {
@@ -43,14 +52,35 @@ export interface TelegramDaemonDeps {
     }) => SpawnResult;
     execPath?: string;
     randomId?: () => string;
+    /**
+     * Signal delivery + poll timing for the stale-generation reload handoff in
+     * {@link ensureTelegramDaemonRunning}. Defaults use real signals/timers; tests
+     * inject them to drive the handoff deterministically.
+     */
+    sendSignal?: (pid: number, signal: NodeJS.Signals) => void;
+    sleep?: (ms: number) => Promise<void>;
+    waitStepMs?: number;
 }
 export declare const HEARTBEAT_INTERVAL_MS = 5000;
-export declare const HEARTBEAT_TTL_MS = 20000;
+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 = 2;
+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";
 /**
  * Attach session-lifecycle control (create/close/resume) to the running daemon.
@@ -97,6 +127,7 @@ export declare function acquireDaemonOwnership(input: {
     attached?: boolean;
     blocked?: boolean;
     reason?: "identity_mismatch";
+    reloadRequired?: boolean;
 }>;
 export declare function renewDaemonHeartbeat(input: {
     settings: Settings;
@@ -126,6 +157,12 @@ export interface TelegramSpawnOwnerResult {
     ownerId?: string;
     runtime: DaemonRuntimeInfo;
     warnings: string[];
+    /**
+     * Set when ownership was NOT acquired because a still-live owner is running an
+     * older daemon generation. The caller must hand off via a reload rather than
+     * attach; see {@link ensureTelegramDaemonRunning}.
+     */
+    reloadRequired?: boolean;
 }
 /**
  * Build the detached spawn command/args for the daemon-internal entrypoint.
@@ -156,6 +193,7 @@ export declare function ensureTelegramDaemonRunning(input: {
 export interface BotApi {
     call(method: string, body: unknown, opts?: {
         signal?: AbortSignal;
+        noRetry?: boolean;
     }): Promise<unknown>;
 }
 export interface TelegramTransportOptions {
@@ -170,13 +208,15 @@ export declare class TelegramBotTransport implements BotApi {
     constructor(opts: TelegramTransportOptions);
     call(method: string, body: unknown, opts?: {
         signal?: AbortSignal;
+        noRetry?: boolean;
     }): Promise<unknown>;
 }
+export type TelegramUpdateOutcome = "consumed" | "retry";
 export interface TelegramUpdatePollerOptions {
     botApi: BotApi;
     runtime: NotificationOperatorRuntime;
     backoff: OperatorBackoffPolicy;
-    processUpdate: (update: unknown) => Promise<void>;
+    processUpdate: (update: unknown) => Promise<TelegramUpdateOutcome>;
 }
 /** Owns getUpdates offset, conflict backoff, and per-update error isolation. */
 export declare class TelegramUpdatePoller {
@@ -239,6 +279,14 @@ export interface TelegramDaemonOptions {
     richDraft?: {
         enabled: boolean;
     };
+    /**
+     * Per-session Telegram forum-topic naming. `nameTemplate` supports the
+     * `{repo}`, `{branch}`, and `{title}` placeholders; unset preserves the
+     * built-in `{repo}/{branch} - {title}` composition and its fallbacks.
+     */
+    topics?: {
+        nameTemplate?: string;
+    };
 }
 interface SessionSocket {
     sessionId: string;
@@ -273,6 +321,11 @@ export declare class TelegramNotificationDaemon {
     private readonly fsImpl;
     private readonly botApi;
     private readonly topics;
+    /** Serializes registry snapshots so an older atomic write cannot overwrite newer rename state. */
+    private topicsPersistQueue;
+    /** Daemon edit attempts that can race an accepted user service message. */
+    private readonly daemonRenameAttempts;
+    private readonly selectedAckPending;
     private readonly pool;
     private readonly poller;
     private readonly dispatchState;
@@ -314,12 +367,24 @@ export declare class TelegramNotificationDaemon {
     private readonly pendingLifecycle;
     /** Monotonic counter for unique lifecycle request ids. */
     private lifecycleSeq;
+    /** Attempt tombstones live for the daemon lifetime so a commit key can never send twice. */
+    private readonly selectedAckCache;
+    private cacheSelectedAck;
+    private getCachedSelectedAck;
+    private finishSelectedAck;
     /**
      * Cooperatively stop the daemon: set the stop flag and abort the in-flight
      * long poll so the run loop wakes immediately instead of waiting out the
      * ~25s getUpdates timeout. Safe to call from a signal handler.
      */
     requestStop(_reason?: "reload" | "stop" | "signal"): void;
+    /**
+     * Start the owner-bound lifecycle control server and wire it to the
+     * orchestrator. Called from {@link run} ONLY after ownership is confirmed, so
+     * exactly one owner ever starts exactly one control server (no second poller
+     * / 409). A control-server failure degrades gracefully: the daemon keeps
+     * serving notifications without lifecycle control. Returns true when started.
+     */
     private startLifecycleControl;
     /** Stop the lifecycle control server (idempotent); called from run()'s finally. */
     private stopLifecycleControl;
@@ -334,6 +399,11 @@ export declare class TelegramNotificationDaemon {
     private nextLifecycleRequestId;
     /** Build an authenticated lifecycle frame from a parsed command + identity. */
     private buildLifecycleFrame;
+    /**
+     * Handle a paired-chat /session_* command: validate (shared validator),
+     * route to the control endpoint, and reply with the outcome. Returns true
+     * when the message was a lifecycle command (so the caller stops processing).
+     */
     private handleLifecycleCommand;
     private refreshBotIdentity;
     /** Map a lifecycle response/error to a user-facing message (G010 surfacing). */
@@ -366,20 +436,40 @@ export declare class TelegramNotificationDaemon {
     private deleteMessageRoutes;
     private static readonly THREADED_FRAMES;
     private topicNameFor;
+    /**
+     * Render the operator-configured topic name template, or `undefined` when no
+     * usable template applies so the caller uses the built-in composition. The
+     * template is honored only if it is non-blank AND every placeholder it
+     * references (`{repo}`, `{branch}`, `{title}`) has a value for this session,
+     * which preserves the default title/repo/branch fallbacks and prevents
+     * half-filled names with dangling separators. Unknown placeholders are left
+     * verbatim.
+     */
+    private renderTopicNameTemplate;
     private topicIdentityKey;
     private topicIdentityBase;
     private topicOwnerForIdentity;
     private sessionCanClaimIdentity;
     private submitThreadedFrame;
     private existingTopicForPrivateChat;
+    /** Best-effort re-assertion for a durable user-owned topic name. */
+    private reconcileUserTopicName;
     private rememberPendingThreadedFrame;
     private flushPendingThreadedFrames;
+    /**
+     * Resolve (creating once via `createForumTopic`) the forum topic for a
+     * session. On capability failure (e.g. Threaded Mode off) this returns
+     * `undefined`; callers then flat-deliver to a private paired chat (with a
+     * one-time nudge) or drop fail-closed for a non-private chat.
+     */
     private ensureTopic;
     private topicPastOrphanGrace;
     private deleteOrphanedTopic;
+    /** Best-effort delete of a session topic once its local notification endpoint shuts down. */
     private deleteTopic;
     private persistTopics;
     loadTopics(): Promise<void>;
+    /** Download a Telegram file by its file_path (from getFile) into memory. */
     private downloadTelegramFile;
     /**
      * Per-session private temp directories (mode 0700) holding inbound non-image
@@ -387,8 +477,19 @@ export declare class TelegramNotificationDaemon {
      * removed when the daemon stops (see {@link cleanupAllAttachmentDirs}).
      */
     private readonly attachmentDirs;
+    /** Lazily create a private, unguessable 0700 temp dir for `sessionId`. */
     private ensureAttachmentDir;
+    /** Remove all per-session attachment directories. Called on daemon shutdown. */
     private cleanupAllAttachmentDirs;
+    /**
+     * Resolve an inbound attachment to inline image bytes (forwarded as images) or
+     * a securely-saved file path note (non-images). Non-image bytes are written
+     * into a private per-session temp dir (0700) under an unguessable name via an
+     * exclusive 0600 create (`wx`), so the files are not world-readable and the
+     * write never follows a pre-existing symlink. The directory is removed when the
+     * daemon stops. Returns base64 images to inline plus human-readable file notes
+     * to append to the injected text.
+     */
     private resolveInboundAttachment;
     /**
      * Serialize all pool flushes. Every caller (`submitThreadedFrame`, the flat
@@ -400,6 +501,7 @@ export declare class TelegramNotificationDaemon {
      */
     private flushChain;
     private flushPool;
+    /** Drain the shared rate-limit pool and deliver each granted send to its topic. */
     private flushPoolInner;
     /**
      * Track the Telegram message id backing a streamed `(sessionId, coalesceKey)`
@@ -407,25 +509,50 @@ export declare class TelegramNotificationDaemon {
      * same-category entries (e.g. prior turns) so the map stays bounded.
      */
     private recordLiveMessage;
+    /**
+     * Threaded Mode is unavailable (the bot owner has not enabled forum topics in
+     * @BotFather, so `createForumTopic` fails). Deliver the rendered frame flat to
+     * the paired chat instead of dropping it, and nudge the user once. Flat delivery
+     * is gated on the paired chat being a private chat: for a group/supergroup/channel
+     * (e.g. a legacy or hand-edited `chatId`) we keep dropping fail-closed so session
+     * content never lands in a shared chat. Identity headers are sent at most once per
+     * session in flat mode.
+     */
     private deliverFlatFallback;
+    /**
+     * Resolve (and cache definitive resolution of) whether the paired `chatId` is
+     * a private chat. Topic and flat delivery are only safe in a private DM; an
+     * indeterminate `getChat` result fails closed for this attempt and is retried
+     * later.
+     */
+    private resolvePairedChatPrivacy;
+    /** Keep existing outbound callers fail-closed for indeterminate privacy. */
     private pairedChatIsPrivate;
+    /** Tell the user once (per daemon run) how to enable Threaded Mode. */
     private notifyThreadedFallback;
     private startFlushTimer;
     private stopFlushTimer;
+    /** Run a root scan, guarding against overlapping scans from the timer + loop. */
     private runScan;
     private startScanTimer;
     private stopScanTimer;
+    /** Send a single `typing` chat action into a busy session's topic (best-effort). */
     private sendTyping;
+    /** Set a native reaction on an inbound thread message (best-effort). */
     private setReaction;
     private startTypingTimer;
     private stopTypingTimer;
     handleSessionMessage(session: SessionSocket, msg: any): Promise<void>;
     private answerCallbackQueryBestEffort;
     private sendStaleGuidance;
+    /** Consume Telegram forum-topic rename service messages before text routing. */
+    private handleForumTopicEdited;
+    private processTelegramUpdate;
     handleTelegramUpdate(update: unknown): Promise<void>;
     pollOnce(signal?: AbortSignal): Promise<number>;
     /** Sync the bot's Telegram command menu to what the daemon actually handles. */
     registerBotCommands(): Promise<void>;
     run(): Promise<void>;
+    /** True when a signal-driven stop or an owner-scoped control request asks the loop to exit. */
     private controlStopRequested;
 }

package/dist/types/notifications/telegram-reference.d.ts

@@ -18,6 +18,16 @@ export interface InlineButton {
     text: string;
     callback_data: string;
 }
+/** Typed action controls are protocol data, never inferred from option labels. */
+export interface TelegramActionControl {
+    id: "navigation_forward";
+    kind: "navigation";
+    label: "Next" | "Done";
+    enabled: boolean;
+}
+export type TelegramCallbackAnswer = number | string | {
+    controlId: TelegramActionControl["id"];
+};
 /** A rendered Telegram message for an `action_needed`. */
 export interface RenderedMessage {
     text: string;
@@ -31,10 +41,16 @@ export declare function decodeCallbackData(data: string): {
     id: string;
     index: number;
 } | null;
+/** Encode a typed control independently from option labels. */
+export declare function encodeControlCallbackData(actionId: string, controlId: TelegramActionControl["id"]): string;
+export declare function decodeControlCallbackData(data: string): {
+    id: string;
+    controlId: TelegramActionControl["id"];
+} | null;
 export interface CallbackRoute {
     sessionId: string;
     actionId: string;
-    answer: number | string;
+    answer: TelegramCallbackAnswer;
 }
 export interface SerializedAliasTable {
     version: 1;
@@ -57,6 +73,7 @@ export declare function buildActionMessage(action: {
     id: string;
     question?: string;
     options?: string[];
+    controls?: readonly TelegramActionControl[];
     summary?: string;
 }): RenderedMessage;
 /** Render an `action_needed` body as raw markdown (rich-message source; the HTML fallback stays on buildActionMessage). */
@@ -72,7 +89,7 @@ export declare function sendTelegramHtmlChunks(send: TelegramSend, chatId: strin
 export interface ReplyFrame {
     type: "reply";
     id: string;
-    answer: number | string;
+    answer: TelegramCallbackAnswer;
     token: string;
 }
 /**

package/dist/types/notifications/topic-registry.d.ts

@@ -20,8 +20,16 @@ export interface TopicRecord {
     identitySent: boolean;
     /** Creation timestamp (ms epoch). */
     createdAt: number;
-    /** Last applied topic title (for rename detection). */
+    /** Last applied or observed Telegram topic title. */
     name?: string;
+    /** Naming authority. Missing values are legacy daemon-owned records. */
+    nameOwner?: "user";
+    /** Whether a user-owned name still needs a best-effort Telegram re-assert. */
+    nameReconcilePending?: boolean;
+    /** Last accepted Telegram update id for a user-owned name. */
+    userNameUpdateId?: number;
+    /** Stable repo/branch identity used when topic names are user-owned or customized. */
+    identityKey?: string;
 }
 /** Serialisable shape persisted to disk. */
 export interface TopicRegistryState {
@@ -41,7 +49,7 @@ export declare class TopicRegistry {
     /** In-flight create promises, keyed by session, to dedupe concurrent creates. */
     private readonly inflight;
     constructor(state?: TopicRegistryState);
-    /** Merge a serialized state into this registry, preserving all persisted fields. */
+    /** Merge serialized state and normalize authority fields from older releases. */
     load(state: TopicRegistryState): void;
     /** Resolve the owning session for a topic id (for fail-closed inbound routing). */
     sessionForTopic(topicId: string): string | undefined;
@@ -58,9 +66,21 @@ export declare class TopicRegistry {
     markIdentitySent(sessionId: string): void;
     /** Whether the identity header still needs sending for this session. */
     needsIdentity(sessionId: string): boolean;
-    /** Whether a known session topic's applied title differs from `name`. */
+    /** Remember stable repo/branch identity independently of the displayed name. */
+    markIdentityKey(sessionId: string, identityKey: string): boolean;
+    /** Whether daemon identity reconciliation should apply `name`. */
     needsRename(sessionId: string, name: string): boolean;
-    /** Commit a successfully-applied Telegram topic title. */
+    /** The user-owned name that must be preserved, when one exists. */
+    userOwnedName(sessionId: string): string | undefined;
+    /** A user-owned name whose Telegram reconciliation is still pending. */
+    userNameToReconcile(sessionId: string): string | undefined;
+    /** Record an explicit Telegram-side user rename, rejecting stale update ids. */
+    markUserName(sessionId: string, name: string, updateId: number): "updated" | "duplicate" | "stale";
+    /** Mark the matching preserved user name as reconciled with Telegram. */
+    markUserNameReconciled(sessionId: string, name: string): boolean;
+    /** Restore retryable reconciliation after a failed pending-clear persistence. */
+    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. */
     delete(sessionId: string): boolean;

package/dist/types/registry/agent-registry.d.ts

@@ -12,6 +12,7 @@ export type AgentKind = "main" | "sub";
 export interface AgentRef {
     id: string;
     displayName: string;
+    rosterLabel?: string;
     kind: AgentKind;
     parentId?: string;
     status: AgentStatus;
@@ -34,6 +35,7 @@ type RegistryListener = (event: RegistryEvent) => void;
 export interface RegisterInput {
     id: string;
     displayName: string;
+    rosterLabel?: string;
     kind: AgentKind;
     parentId?: string;
     session: AgentSession | null;

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

@@ -24,7 +24,7 @@ export declare function extractDataFlag(argv: string[]): {
     dataPath: string | undefined;
     rest: string[];
 };
-export declare function createRlmPreset({ dataContext, pythonTool, completeResearchTool, objective, resumeContext, onSessionReady }: RlmPresetOptions): RlmPreset;
+export declare function createRlmPreset({ dataContext, pythonTool, completeResearchTool, objective, resumeContext, onSessionReady, }: RlmPresetOptions): RlmPreset;
 export declare function buildRlmGoalObjective(input: {
     messages: readonly string[];
     dataContext: RlmDataContext | null;

package/dist/types/sdk.d.ts

@@ -122,6 +122,8 @@ export interface CreateAgentSessionOptions {
     agentId?: string;
     /** Display name for the agent in IRC. Default: "main" or "sub". */
     agentDisplayName?: string;
+    /** Compact task label for hidden IRC roster reminders. */
+    agentRosterLabel?: string;
     /** Optional restricted bash command prefixes for read-only role agents. */
     bashAllowedPrefixes?: string[];
     /** Restriction policy paired with bashAllowedPrefixes. */

package/dist/types/secrets/obfuscator.d.ts

@@ -1,5 +1,5 @@
 import type { Message } from "@sayknow-cli/ai";
-import type { SessionContext } from "../session/session-manager";
+import { type SessionContext } from "../session/session-manager";
 export interface SecretEntry {
     type: "plain" | "regex";
     content: string;

package/dist/types/session/agent-session.d.ts

@@ -12,9 +12,9 @@
  *
  * Modes use this class and add their own I/O layer on top.
  */
-import { type Agent, type AgentEvent, type AgentMessage, type AgentState, type AgentTool, type StablePrefixSnapshot, ThinkingLevel } from "@sayknow-cli/agent-core";
+import { type Agent, type AgentEvent, type AgentMessage, type AgentState, type AgentTool, type ResolvedThinkingLevel, type StablePrefixSnapshot, ThinkingLevel } from "@sayknow-cli/agent-core";
 import { type CompactionResult, type EmergencyCompactionSample } from "@sayknow-cli/agent-core/compaction";
-import type { AssistantMessage, Effort, ImageContent, Message, MessageAttribution, Model, ProviderSessionState, ServiceTier, SimpleStreamOptions, TextContent, ToolCall, ToolChoice, UsageReport } from "@sayknow-cli/ai";
+import type { AssistantMessage, Effort, ImageContent, Message, MessageAttribution, Model, ProviderSessionState, ServiceTier, SimpleStreamOptions, TextContent, ToolCall, ToolChoice, Usage, UsageReport } from "@sayknow-cli/ai";
 export interface ForkContextSeedMetadata {
     sourceSessionId: string;
     parentMessageCount: number;
@@ -79,7 +79,7 @@ import { type WorkspaceTree } from "../workspace-tree";
 import type { ClientBridge } from "./client-bridge";
 import { type ContributionPrepOptions, type ContributionPrepResult } from "./contribution-prep";
 import { type CustomMessage } from "./messages";
-import type { BranchSummaryEntry, CompactionEntry, NewSessionOptions, SessionContext, SessionManager } from "./session-manager";
+import type { BranchSummaryEntry, CompactionEntry, NewSessionOptions, SessionContext, SessionManager, SessionManagerCloseOutcome } from "./session-manager";
 import { ToolChoiceQueue } from "./tool-choice-queue";
 import { YieldQueue } from "./yield-queue";
 /** Session-specific events that extend the core AgentEvent */
@@ -309,6 +309,11 @@ export interface RoleModelCycleResult {
     thinkingLevel: ThinkingLevel | undefined;
     role: string;
 }
+export interface DefaultModelSelectionResult {
+    readonly provider: string;
+    readonly modelId: string;
+    readonly thinkingLevel: ResolvedThinkingLevel;
+}
 /** Session statistics for /session command */
 export interface SessionStats {
     sessionFile: string | undefined;
@@ -327,6 +332,7 @@ export interface SessionStats {
     };
     premiumRequests: number;
     cost: number;
+    costBreakdown?: Usage["cost"];
 }
 export type QueuedMessageEditMode = "steer" | "followUp";
 export interface QueuedMessageEditEntry {
@@ -483,6 +489,16 @@ export declare class AgentSession {
      * Call this when completely done with the session.
      */
     dispose(): Promise<void>;
+    /**
+     * Strict writer close for ACP session delete. On the first attempt it flushes
+     * pending writes, then returns the certainty-aware close outcome so the caller
+     * can block destructive mutation on a non-`closed` result. When the manager
+     * retains a retryable writer (a prior `close_failed_retryable`), the flush is
+     * NOT repeated: the underlying writer rejects flushes while in the retryable
+     * state, and `SessionManager.closeStrict()` owns the flush/close sequencing so
+     * a second call can return `closed` once the OS close lands.
+     */
+    closeWriterStrict(): Promise<SessionManagerCloseOutcome>;
     /**
      * Bounded, best-effort teardown of the subprocess-spawning resources this session
      * owns: the browser tool's headless/spawned Chrome and the Python eval kernel + JS VM
@@ -509,6 +525,17 @@ export declare class AgentSession {
     drainAsyncJobDeliveriesForAcp(options?: {
         timeoutMs?: number;
     }): Promise<boolean>;
+    /**
+     * Owner-scoped async-delivery snapshot used by the strict ACP delete
+     * quiescence barrier to PROVE quiescence after a best-effort drain. Unlike
+     * {@link drainAsyncJobDeliveriesForAcp}'s boolean return (which conflates
+     * "nothing to drain" with "timed out"), this reads the live state directly so
+     * any remaining queued/delivering work is observable and can block mutation.
+     */
+    getAsyncDeliveryStateForAcp(): {
+        queued: number;
+        delivering: boolean;
+    };
     /** Most recent assistant message in agent state. */
     getLastAssistantMessage(): AssistantMessage | undefined;
     /** Current effective system prompt blocks (includes any per-turn extension modifications) */
@@ -607,6 +634,8 @@ export declare class AgentSession {
     get hasPostPromptWork(): boolean;
     /** All messages including custom types like BashExecutionMessage */
     get messages(): AgentMessage[];
+    /** Main startup calls this exactly once, after a strict open returned `kind: "opened"`. */
+    continuePersistedHistory(): Promise<void>;
     buildDisplaySessionContext(): SessionContext;
     /** Convert session messages using the same pre-LLM pipeline as the active session. */
     convertMessagesToLlm(messages: AgentMessage[], signal?: AbortSignal): Promise<Message[]>;
@@ -830,6 +859,7 @@ export declare class AgentSession {
     setModelTemporary(model: Model, thinkingLevel?: ThinkingLevel, options?: {
         persistAsSessionDefault?: boolean;
     }): Promise<void>;
+    setDefaultModelSelection(model: Model, thinkingLevel: ThinkingLevel | undefined): Promise<DefaultModelSelectionResult>;
     /**
      * Cycle to next/previous model.
      * Uses scoped models (from --models flag) if available, otherwise all available models.
@@ -1084,9 +1114,13 @@ export declare class AgentSession {
         promptText: string;
         onTextDelta?: (delta: string) => void;
         signal?: AbortSignal;
+        /** Defer the successful roster-claim commit until the caller accepts its exchange. */
+        deferRosterCommit?: boolean;
     }): Promise<{
         replyText: string;
         assistantMessage: AssistantMessage;
+        commitRosterClaim?: () => void;
+        releaseRosterClaim?: () => void;
     }>;
     /**
      * Reload the current session from disk.
@@ -1152,6 +1186,9 @@ export declare class AgentSession {
      * otherwise estimates tokens for all messages.
      */
     getContextUsage(): ContextUsage | undefined;
+    getContextUsageObservabilityForTests(): {
+        estimateCount: number;
+    };
     fetchUsageReports(signal?: AbortSignal): Promise<UsageReport[] | null>;
     /**
      * Export session to HTML.

package/dist/types/session/cache-economics.d.ts

@@ -0,0 +1,79 @@
+import type { Usage } from "@sayknow-cli/ai";
+export interface CacheEconomicsPricing {
+    input: number;
+    cacheRead: number;
+    cacheWrite: number;
+}
+export interface CacheEconomicsModelCost extends CacheEconomicsPricing {
+    output: number;
+}
+export type CacheEconomicsBasis = {
+    kind: "persisted-aggregate";
+    costBreakdown: Usage["cost"];
+} | {
+    kind: "current-model-estimate";
+    pricing: CacheEconomicsPricing;
+};
+export interface CacheEconomicsUsage {
+    input: number;
+    output?: number;
+    cacheRead: number;
+    cacheWrite: number;
+    total?: number;
+    cost?: {
+        input?: number;
+        output?: number;
+        cacheRead?: number;
+        cacheWrite?: number;
+        total?: number;
+    };
+}
+export interface CacheMissCostSummary {
+    inputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    inputCostUsd: number;
+    cacheReadCostUsd: number;
+    cacheWriteCostUsd: number;
+    cacheHitRate: number | undefined;
+    missPremiumUsd: number | undefined;
+}
+/**
+ * How a detected cache-miss pattern is attributed, per issue #2020.
+ *
+ * - `actionable`: usage evidence points to a user-controllable cause and SKC
+ *   has a concrete remediation.
+ * - `diagnostic-only`: a miss pattern is observed but the cause is not
+ *   determinable from usage alone; describe what is unknown, assert no cause.
+ * - `provider-side-suspected`: the provider returned no cache activity, so the
+ *   miss cannot be attributed to the user's prompt; not user-actionable.
+ */
+export type CacheMissAttribution = "actionable" | "diagnostic-only" | "provider-side-suspected";
+export interface CacheBehaviorWarning {
+    code: "expensive_cache_miss" | "cache_write_spike" | "provider_side_cache_miss";
+    attribution: CacheMissAttribution;
+    reason: string;
+    /** Concrete remediation — present only when `attribution` is `actionable`. */
+    nextStep?: string;
+    /** What SKC cannot determine — present for non-actionable attributions. */
+    unknown?: string;
+    costUsd: number;
+}
+export interface CacheWarningBuildState {
+    warningsEmitted: number;
+}
+export declare function computeCacheMissCostSummary(usage: CacheEconomicsUsage | undefined, basis: CacheEconomicsBasis): CacheMissCostSummary | undefined;
+export declare function formatCacheMissSummaryLines(summary: CacheMissCostSummary): string[];
+export declare function buildCacheBehaviorWarning(usage: Usage | undefined, model: {
+    cost: CacheEconomicsModelCost;
+} | undefined | null): CacheBehaviorWarning | undefined;
+/**
+ * Render a cache warning as a single transcript line. Actionable attributions
+ * carry a concrete next step; non-actionable ones state what is unknown and,
+ * for provider-side patterns, that the miss is not user-actionable — never
+ * asserting a cause or blaming the provider (#2020).
+ */
+export declare function formatCacheWarningLine(warning: CacheBehaviorWarning): string;
+export declare function buildCacheEconomicsWarning(usage: Usage | undefined, model: {
+    cost: CacheEconomicsModelCost;
+} | undefined | null, state: CacheWarningBuildState): string | undefined;

package/dist/types/session/context-estimation.d.ts

@@ -0,0 +1,31 @@
+import type { Skill } from "../extensibility/skills";
+import type { Tool } from "../tools";
+import type { AgentSession } from "./agent-session";
+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;
+/**
+ * Shared helper for the four non-message token totals. Single source of truth
+ * for `computeNonMessageTokens` (session estimates + status-line incremental
+ * cache) and `computeContextBreakdown` (/context panel). The split avoids
+ * drift between the surfaces — they MUST report the same numbers.
+ */
+export declare function computeNonMessageBreakdown(session: AgentSession): {
+    rulesTokens: number;
+    skillsTokens: number;
+    toolsTokens: number;
+    systemContextTokens: number;
+    systemPromptTokens: number;
+};

package/dist/types/session/provider-safety-stop.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Recognizes legacy provider safety-stop labels persisted before `errorKind`.
+ * Keep this anchored and conservative so incidental transient-error prose stays retryable.
+ */
+export declare function isLegacyProviderSafetyStopMessage(errorMessage: string): boolean;