@gajae-code/coding-agent 0.12.0 → 0.12.1

package/dist/types/modes/components/gjc-bundle-settings.d.ts

@@ -0,0 +1,34 @@
+import { Container } from "@gajae-code/tui";
+import { type GjcLifecycleContext } from "../../extensibility/gjc-plugins/lifecycle";
+import { type GjcRuntimeSnapshotProvider } from "../../extensibility/gjc-plugins/runtime-quarantine";
+import type { GjcBundleIdentity, GjcBundleSummary, GjcLifecycleResult, GjcReviewedUpdateToken, GjcToggleResult, GjcUpdateApplyResult, GjcUpdatePreview } from "../../extensibility/gjc-plugins/types";
+/** Injectable lifecycle boundary; Settings never reads registries or executes bundle code. */
+export interface GjcBundleLifecyclePort {
+    listGjcBundles(ctx: GjcLifecycleContext): Promise<GjcBundleSummary[]>;
+    getGjcBundle(ctx: GjcLifecycleContext, identity: GjcBundleIdentity): Promise<GjcLifecycleResult<GjcBundleSummary>>;
+    previewGjcBundleUpdate(ctx: GjcLifecycleContext, identity: GjcBundleIdentity): Promise<GjcLifecycleResult<GjcUpdatePreview>>;
+    applyGjcBundleUpdate(ctx: GjcLifecycleContext, token: GjcReviewedUpdateToken): Promise<GjcLifecycleResult<GjcUpdateApplyResult>>;
+    setGjcBundleEnabled(ctx: GjcLifecycleContext, identity: GjcBundleIdentity, enabled: boolean): Promise<GjcLifecycleResult<GjcToggleResult>>;
+    setGjcBundleSurfaceEnabled(ctx: GjcLifecycleContext, identity: GjcBundleIdentity, surfaceId: string, enabled: boolean): Promise<GjcLifecycleResult<GjcToggleResult>>;
+}
+export interface GjcBundleSettingsDependencies {
+    lifecycle?: GjcBundleLifecyclePort;
+    runtimeSnapshotProvider?: GjcRuntimeSnapshotProvider;
+    activationGeneration?: number;
+}
+export interface GjcBundleSettingsCallbacks {
+    onClose: () => void;
+    onBundlesChanged?: () => void;
+}
+export type GjcBundleSettingsState = "loading" | "error" | "empty" | "list" | "detail" | "unsupported-source" | "update-review" | "update-confirm" | "update-running" | "update-result" | "stale-result" | "quarantined-blocked" | "mutation-in-flight-locked";
+/** Scope-qualified, lifecycle-backed Settings UI for installed GJC bundles. */
+export declare class GjcBundleSettingsComponent extends Container {
+    #private;
+    private readonly callbacks;
+    private readonly dependencies;
+    constructor(cwd: string, callbacks: GjcBundleSettingsCallbacks, dependencies?: GjcBundleSettingsDependencies);
+    get stateId(): GjcBundleSettingsState;
+    get navigationLocked(): boolean;
+    dispose(): void;
+    handleInput(data: string): void;
+}

package/dist/types/modes/components/notifications-settings-editor.d.ts

@@ -12,6 +12,7 @@ export interface NotificationsEditorPreferences {
     richDraftEnabled: boolean;
     toolActivityEnabled: boolean;
     streamingEnabled: boolean;
+    sound: "all" | "important" | "none";
 }
 /** Secret-safe snapshot used to render the Notifications tab. */
 export interface NotificationsEditorState {

package/dist/types/modes/components/session-observer-overlay.d.ts

@@ -2,6 +2,24 @@ import type { KeyId } from "../../config/keybindings";
 import type { SessionMessageEntry } from "../../session/session-manager";
 import type { SessionObserverRegistry } from "../session-observer-registry";
 import { type TranscriptViewerEntry, TranscriptViewerOverlay } from "./transcript-viewer-overlay";
+export declare const __sessionObserverProjectionCounters: {
+    enabled: boolean;
+    projectionFullRuns: number;
+    projectionIncrementalRuns: number;
+    sourceMessagesProjected: number;
+    projectedEntriesAppended: number;
+    resultPatchCount: number;
+    snapshot(): {
+        projectionFullRuns: number;
+        projectionIncrementalRuns: number;
+        sourceMessagesProjected: number;
+        projectedEntriesAppended: number;
+        resultPatchCount: number;
+    };
+    enable(): void;
+    disable(): void;
+    reset(): void;
+};
 /** Session-observer adapter. The shared viewer owns navigation and fold state. */
 export declare class SessionObserverOverlayComponent extends TranscriptViewerOverlay {
     #private;

package/dist/types/modes/components/settings-selector.d.ts

@@ -3,6 +3,7 @@ import type { Effort } from "@gajae-code/ai";
 import { type Component, Container } from "@gajae-code/tui";
 import { type SettingPath } from "../../config/settings";
 import type { StatusLinePreset, StatusLineSegmentId, StatusLineSeparatorStyle } from "../../config/settings-schema";
+import type { GjcRuntimeSnapshotProvider } from "../../extensibility/gjc-plugins/runtime-quarantine";
 import { type NotificationsEditorOperations } from "./notifications-settings-editor";
 import type { StatusLineSegmentOptions } from "./tool-status-header";
 /**
@@ -24,6 +25,14 @@ export interface SettingsRuntimeContext {
     petAvailable?: boolean;
     /** Terminal environment used to select unavailable-pet guidance. Omitted in production to use Bun.env. */
     terminalEnv?: NodeJS.ProcessEnv;
+    /**
+     * Runtime evidence published by the session for the current activation
+     * generation. Omitted when no session published one, in which case the GJC
+     * Bundles tab honestly reports runtime status as unavailable.
+     */
+    gjcRuntimeSnapshot?: GjcRuntimeSnapshotProvider;
+    /** Activation generation the published snapshot must match to be merged. */
+    gjcActivationGeneration?: number;
 }
 /** Status line settings subset for preview */
 export interface StatusLinePreviewSettings {

package/dist/types/modes/components/status-line/gh.d.ts

@@ -0,0 +1,5 @@
+import { type RunGh } from "../../../utils/gh";
+export declare function lookupCurrentPr(runGh?: RunGh): Promise<{
+    number: number;
+    url: string;
+} | null>;

package/dist/types/modes/components/transcript-viewer-overlay.d.ts

@@ -29,13 +29,30 @@ export type TranscriptViewerOverlayOptions = {
     footerControls?: string;
     getEntryText?: (entry: TranscriptViewerEntry, expanded: boolean) => string;
 };
+export declare const __transcriptViewerPerfCounters: {
+    enabled: boolean;
+    layoutCacheHits: number;
+    layoutCacheMisses: number;
+    refreshRuns: number;
+    rebuildRuns: number;
+    snapshot(): {
+        layoutCacheHits: number;
+        layoutCacheMisses: number;
+        refreshRuns: number;
+        rebuildRuns: number;
+    };
+    enable(): void;
+    disable(): void;
+    reset(): void;
+};
 /** Message-agnostic, modal transcript browser over resolved projection entries. */
 export declare class TranscriptViewerOverlay extends Container {
     #private;
     constructor(options: TranscriptViewerOverlayOptions);
     get selectedEntryId(): string | undefined;
     get isFullscreen(): boolean;
-    refresh(identityMap?: ReadonlyMap<string, string>): void;
+    refresh(identityMap?: ReadonlyMap<string, string>, preserveLayoutCache?: boolean): void;
+    invalidateLayoutEntries(entryIds: readonly string[]): void;
     render(width: number): string[];
     handleMouse(event: MouseEvent): void;
     handleInput(keyData: string): void;

package/dist/types/reminders/star-reminder.d.ts

@@ -1,5 +1,8 @@
 import type { ImageContent } from "@gajae-code/ai";
 import type { CustomMessage } from "../session/messages";
+import { type GhResult, type RunGh, runGhDefault } from "../utils/gh";
+export type { GhResult, RunGh };
+export { runGhDefault };
 export declare const STAR_REMINDER_REPO = "Yeachan-Heo/gajae-code";
 export declare const STAR_REMINDER_CUSTOM_TYPE = "star-reminder";
 export declare const STARRED_CACHE_TTL_MS: number;
@@ -10,15 +13,6 @@ export interface StarReminderState {
     starredCheckedAt: string;
 }
 export type StarCheckStatus = "starred" | "unstarred" | "unavailable";
-export interface GhResult {
-    exitCode: number;
-    stdout: string;
-    stderr: string;
-    timedOut?: boolean;
-}
-export type RunGh = (args: string[], options?: {
-    timeoutMs?: number;
-}) => Promise<GhResult>;
 export interface StarReminderDeps {
     statePath?: string;
     now?: () => Date;
@@ -49,10 +43,6 @@ export declare function recordStarredFromPut(deps?: StarReminderDeps): Promise<S
 export declare function recordFreshStarCheck(status: "starred" | "unstarred", deps?: StarReminderDeps): Promise<StarReminderState>;
 /** Record a launch-nudge decline. Never downgrades a confirmed star. */
 export declare function recordDeclinedAfterNo(deps?: StarReminderDeps): Promise<StarReminderState>;
-/** Default `gh` runner. Returns an unavailable-style result instead of throwing. */
-export declare function runGhDefault(args: string[], options?: {
-    timeoutMs?: number;
-}): Promise<GhResult>;
 /** Classify the star state of the repo via `gh api`. */
 export declare function checkGhStarred(deps?: StarReminderDeps): Promise<StarCheckStatus>;
 /** Star the repo via `gh api -X PUT`. Returns whether the PUT succeeded. */

package/dist/types/runtime-mcp/manager.d.ts

@@ -6,6 +6,7 @@ import type { MCPToolDetails } from "./tool-bridge";
 import type { MCPToolCache } from "./tool-cache";
 import type { MCPGetPromptResult, MCPPrompt, MCPRequestOptions, MCPResource, MCPResourceReadResult, MCPResourceTemplate, MCPServerConfig, MCPServerConnection } from "./types";
 export declare function resolveStartupTimeoutMs(configs: MCPServerConfig[], maxStartupTimeoutMs?: number): number;
+export declare function resolveExactConfigStartupTimeoutMs(configs: MCPServerConfig[]): number;
 /**
  * Stable, total ordering on MCP tools by name.
  *

package/dist/types/sdk/acp/adapter.d.ts

@@ -2,7 +2,9 @@ import { SdkClient, SdkClientError, type SdkFrame } from "../client";
 type JsonObject = Record<string, unknown>;
 /** The small agent-side ACP surface used for reverse requests. */
 export interface AcpReverseConnection {
-    request?(method: string, params: JsonObject): Promise<unknown>;
+    request?(method: string, params: JsonObject, options?: {
+        cancellationSignal?: AbortSignal;
+    }): Promise<unknown>;
     [key: string]: unknown;
 }
 export interface AcpProviderRegistration {

package/dist/types/sdk/broker/transport.d.ts

@@ -1,4 +1,6 @@
 import type { Broker } from "./broker";
+export type BrokerShutdownSendAction = "dropped" | "wait_for_drain" | "close";
+export declare function brokerShutdownSendAction(status: number): BrokerShutdownSendAction;
 /** Loopback-only WebSocket transport for the agent-global SDK broker. */
 export declare class BrokerTransport {
     #private;

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

@@ -7,6 +7,7 @@
 export type TelegramFileSink = (file: {
     path: string;
     caption?: string;
+    mime?: string;
 }) => Promise<{
     ok: boolean;
     error?: string;

package/dist/types/sdk/bus/chat-daemon-control.d.ts

@@ -16,7 +16,10 @@ export type ChatDaemonAction = "stop" | "reload";
  * when deleting an observed owner-lock lease. Generation 12 refreshes retained
  * native path and process authority semantics. Generation 13 rejects special
  * files before retained native authority opens. Generation 14 reloads shared
- * chat daemons after notification configuration parsing changes.
+ * chat daemons after notification configuration parsing changes. Generation 15
+ * applies the current notification configuration directly when starting chat
+ * daemon transports. Generation 16 applies Telegram sound-policy configuration
+ * through shared notification parsing.
  */
 export declare const CHAT_DAEMON_GENERATIONS: Readonly<Record<ChatDaemonKind, number>>;
 export declare function chatDaemonGeneration(kind: ChatDaemonKind): number;

package/dist/types/sdk/bus/config.d.ts

@@ -28,6 +28,7 @@ export interface NotificationSettingsSnapshot {
         botToken?: string;
         chatId?: string;
         activation?: Record<string, unknown>;
+        sound: "all" | "important" | "none";
         btw: {
             enabled: boolean;
         };
@@ -105,6 +106,7 @@ export interface NotificationConfig {
      * (those carrying {@link SPAWN_PROVENANCE_ENV}) unless they explicitly opt in.
      */
     sessionScope: "all" | "primary";
+    sound: "all" | "important" | "none";
     idleTimeoutMs: number;
     btw: {
         enabled: boolean;
@@ -177,7 +179,7 @@ export declare function isTelegramConfigured(cfg: NotificationConfig): cfg is No
     chatId: string;
 };
 /** Is Discord configured with all credentials and routing identifiers required by its daemon. */
-export declare function isDiscordConfigured(cfg: NotificationConfig): cfg is NotificationConfig & {
+export declare function isDiscordConfigured(cfg: Pick<NotificationConfig, "enabled" | "discord">): cfg is Pick<NotificationConfig, "enabled"> & {
     discord: {
         botToken: string;
         applicationId: string;
@@ -186,7 +188,7 @@ export declare function isDiscordConfigured(cfg: NotificationConfig): cfg is Not
     };
 };
 /** Is Slack configured with both SDK tokens and its workspace/channel routing identifiers. */
-export declare function isSlackConfigured(cfg: NotificationConfig): cfg is NotificationConfig & {
+export declare function isSlackConfigured(cfg: Pick<NotificationConfig, "enabled" | "slack">): cfg is Pick<NotificationConfig, "enabled"> & {
     slack: {
         botToken: string;
         appToken: string;
@@ -286,6 +288,8 @@ export interface RedactableAction {
     workflowGateId?: string;
     question?: string;
     options?: string[];
+    /** Selected zero-based option positions for transport-specific multi-select rendering. */
+    selectedOptionIndices?: number[];
     summary?: string;
     /** Optional zero-based recommendation into the authoritative raw options. */
     recommendedIndex?: number;

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

@@ -26,6 +26,7 @@ import type { AgentSessionEvent } from "../../session/agent-session";
 import type { AskAnswerSourceResult, AskRemoteControl } from "../../tools";
 import { SessionSdkHost } from "../host";
 import { CursorRegistry, RevisionStore } from "../host/query";
+import { type SdkPromptTerminalOutcome } from "../prompt-status";
 import { type SdkStartupFailure } from "../startup-capability";
 import { type NotificationConfig } from "./config";
 import { NotificationSessionController } from "./session-control";
@@ -348,6 +349,23 @@ interface SessionRuntime {
         commandId: string;
         turnId: string;
     };
+    /** Binds the executing Agent run to a correlated prompt so cleanup targets only it. */
+    bindPromptExecutionHandle: (correlation: {
+        commandId: string;
+        turnId: string;
+    }, handle: string | undefined) => void;
+    /** Reads the durable non-terminal claim for a correlated prompt, if any. */
+    peekPromptPendingOutcome: (correlation: {
+        commandId: string;
+        turnId: string;
+    }) => SdkPromptTerminalOutcome | undefined;
+    /** Claims, fences, finalizes, and publishes exactly one normalized prompt terminal. */
+    terminalizePrompt: (correlation: {
+        commandId: string;
+        turnId: string;
+    }, outcome: SdkPromptTerminalOutcome, extra?: {
+        finalText?: string;
+    }) => Promise<void>;
     /** Records a correlated prompt terminal boundary after agent unwind. */
     /** Atomically claims a correlated prompt terminal boundary after agent unwind. */
     recordPromptTerminal: (correlation: {
@@ -379,6 +397,7 @@ interface SessionRuntime {
         commandId?: string;
         turnId?: string;
         finalText?: string;
+        outcome?: SdkPromptTerminalOutcome;
     } | {
         type: "agent_failed";
         sessionId: string;
@@ -388,6 +407,7 @@ interface SessionRuntime {
             code: string;
             message: string;
         };
+        outcome?: SdkPromptTerminalOutcome;
     }) => void;
     /** Publishes one canonical agent-wire event to the client that owns the active prompt. */
     emitPromptEvent: (event: AgentSessionEvent) => void;
@@ -446,6 +466,15 @@ type SessionStartResult = {
     failure?: SdkStartupFailure;
     suppressExtensionError?: boolean;
 };
+/**
+ * Whether the notifications control channel is enabled.
+ *
+ * Trusted sources only: enabling it opens the session control/answer channel, so
+ * a repository must not be able to turn it on. `$env` merges the caller's
+ * `cwd/.env` into `process.env`; the sibling resolvers in `config.ts` and
+ * `session-control.ts` already read an injected env record rather than the merged
+ * view, and this direct read was the outlier.
+ */
 export declare function notificationsEnabled(): boolean;
 /** Workflow-gate answer shape. */
 interface GateAnswer {

package/dist/types/sdk/bus/kind-aware-reconciliation.d.ts

@@ -2,7 +2,8 @@
  * Kind-aware invocation reconciliation (prompt | skill) with optional durable store.
  * Preserves Q26 admit/first-terminal/capacity/TTL semantics; indexes and caps are per-kind.
  */
-import { type PromptCorrelation, type PromptReconciliationStatus, type TurnPromptReconciliation } from "./prompt-reconciliation";
+import type { PromptReconciliationStatus, SdkPromptTerminalOutcome, TurnPromptReconciliation } from "../prompt-status";
+import { type PromptCorrelation } from "./prompt-reconciliation";
 import type { ReconciliationKind, ReconciliationStore } from "./reconciliation-store";
 export type { ReconciliationKind };
 export interface KindCorrelation extends PromptCorrelation {
@@ -20,6 +21,12 @@ export interface KindAwareReconciliation {
         type: "agent_failed";
         error: unknown;
     }): Promise<void>;
+    claimPendingOutcome(correlation: PromptCorrelation, outcome: SdkPromptTerminalOutcome): Promise<SdkPromptTerminalOutcome>;
+    finalizePromptOutcome(correlation: PromptCorrelation, outcome?: SdkPromptTerminalOutcome, recordError?: {
+        code: string;
+        message: string;
+    }): Promise<void>;
+    peekPendingOutcome(correlation: PromptCorrelation): SdkPromptTerminalOutcome | undefined;
     lookup(kind: ReconciliationKind, selector: {
         commandId?: string;
         turnId?: string;

package/dist/types/sdk/bus/lifecycle-control-runtime.d.ts

@@ -48,6 +48,8 @@ export declare function buildCreateArgv(frame: SessionCreateFrame, _ids: {
 /** Real daemon-safe tmux launcher: canonical owner-isolation plan + GJC tags. */
 export declare function daemonSpawnCreate(env?: NodeJS.ProcessEnv, opts?: {
     ownerIsolationProbe?: OwnerIsolationProbe;
+    platform?: NodeJS.Platform;
+    processIncarnation?: (pid: number) => string | undefined;
 }): (frame: SessionCreateFrame, ids: {
     lifecycleRequestId: string;
     intendedSessionId: string;
@@ -73,6 +75,8 @@ export declare function daemonResumeSession(env?: NodeJS.ProcessEnv, opts?: {
     sessionsRoot?: string;
     listSessions?: (env: NodeJS.ProcessEnv) => GjcTmuxSessionStatus[];
     ownerIsolationProbe?: OwnerIsolationProbe;
+    platform?: NodeJS.Platform;
+    processIncarnation?: (pid: number) => string | undefined;
 }): (target: {
     sessionIdOrPrefix: string;
     path?: string;

package/dist/types/sdk/bus/reconciliation-store.d.ts

@@ -1,4 +1,5 @@
-import type { PromptCorrelation, PromptReconciliationStatus } from "./prompt-reconciliation";
+import type { PromptReconciliationStatus, SdkPromptTerminalOutcome } from "../prompt-status";
+import type { PromptCorrelation } from "./prompt-reconciliation";
 export declare const RECONCILIATION_STORE_VERSION = 1;
 export declare const RECONCILIATION_SESSION_ID_PATTERN: RegExp;
 export declare const RECONCILIATION_DIR_NAME = ".sdk-reconciliation";
@@ -14,6 +15,8 @@ export interface DurableReconciliationRecord extends PromptCorrelation {
     acceptedAt: number;
     startedAt?: number;
     terminalAt?: number;
+    outcome?: SdkPromptTerminalOutcome;
+    pendingOutcome?: SdkPromptTerminalOutcome;
     /** Skill-only safe token; never skill args bodies. */
     skillName?: string;
 }
@@ -43,8 +46,9 @@ export declare function isSafeReconciliationSessionId(sessionId: string): boolea
 /** Derive private store path; throws if sessionId is unsafe (path escape). */
 export declare function reconciliationStorePath(sessionFile: string, sessionId: string): string;
 /**
- * Settle non-terminal durable records after process death: failed/process_restart.
- * Meaning: reconciliation incomplete — not proof of agent failure.
+ * Settle non-terminal durable records after process death.
+ * Prompt records preserve a durable pending outcome; skills retain the existing
+ * reconciliation-incomplete result.
  */
 export declare function settleProcessRestart(records: DurableReconciliationRecord[], now: number): DurableReconciliationRecord[];
 export interface ReconciliationStore {

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

@@ -63,6 +63,7 @@ export declare class DraftStreamState {
 export declare function deliverDraft(botApi: BotApi, base: {
     chat_id: string | number;
     message_thread_id?: number;
+    disable_notification?: true;
 }, draftId: number, raw: string, log?: {
     warn(msg: string): void;
 }): Promise<void>;

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

@@ -43,6 +43,7 @@ export declare function shouldPromoteRich(input: {
 export declare function deliverRichWithFallback(botApi: BotApi, base: {
     chat_id: string | number;
     message_thread_id?: number;
+    disable_notification?: true;
 }, send: ThreadedSend, signal: AbortSignal, fallbackDeliver: () => Promise<void>, log?: {
     warn(msg: string): void;
 }): Promise<number | undefined>;
@@ -55,6 +56,7 @@ export declare function deliverRichWithFallback(botApi: BotApi, base: {
 export declare function deliverRichActionWithFallback(botApi: BotApi, base: {
     chat_id: string | number;
     message_thread_id?: number;
+    disable_notification?: true;
 }, opts: {
     markdown: string;
     replyMarkup?: unknown;

package/dist/types/sdk/bus/telegram-adoption-intent.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Durable, non-routable sidecar store for "adopt a user-created Telegram forum
+ * topic into a preallocated session" intents.
+ *
+ * When a user creates a new forum topic, the daemon first records durable
+ * pending-topic authorization. After folder selection it preallocates an
+ * `intendedSessionId` and records an adoption intent here *before* spawning.
+ * Later, the authenticated `ensureTopic` create callback reads that intent and
+ * returns the user's existing topicId to `TopicRegistry.getOrCreateTopic`, which
+ * is the only authority that commits a topic binding. This keeps the intent out
+ * of routing/endpoint authority until commit, so a failed spawn or a late socket
+ * never deletes the user's topic and never strands a duplicate.
+ *
+ * Invariants (see `pending-approval.md`):
+ * - One file per intent, named `<intendedSessionId>.adoption-intent.json` under
+ *   the daemon notifications dir. Sweep touches files only; never the Telegram API.
+ * - Only `{ intendedSessionId, topicId, chatId, target, createdAt, expiresAt }`
+ *   is persisted. Bot/control tokens and endpoint digests are never stored.
+ * - Owner-only dir (0o700) and 0o600 files; atomic temp→fsync→chmod→rename→parent sync.
+ * - `tryClaim` is a synchronous, in-memory claim keyed by topicId; it excludes a
+ *   second `intendedSessionId` from winning the same topic across awaits. It
+ *   does not delete the sidecar; `releaseClaim` re-enables retry on commit failure.
+ */
+import type { SessionCreateTarget } from "./index";
+/** Persisted document version. */
+export declare const TELEGRAM_ADOPTION_INTENT_VERSION = 1;
+export type TelegramAdoptionTarget = Extract<SessionCreateTarget, {
+    kind: "existing_path";
+}>;
+/** Default intent TTL (configurable at write time). Plan starts at 10 minutes. */
+export declare const DEFAULT_ADOPTION_INTENT_TTL_MS: number;
+/**
+ * Minimal async filesystem surface the store needs. Structurally a subset of the
+ * daemon's `TelegramDaemonFs` / `ConversationStoreFs`, so the daemon can pass its
+ * own `fs` straight through and tests can inject a fake. `open`/`sync`/`close`
+ * mirror `ConversationStoreFileHandle` so the atomic fsync path reuses the same
+ * shape as the conversation store.
+ */
+export interface AdoptionIntentFs {
+    mkdir(directory: string, options: {
+        recursive: true;
+        mode: number;
+    }): Promise<unknown>;
+    chmod(target: string, mode: number): Promise<void>;
+    readFile(file: string, encoding: "utf8"): Promise<string>;
+    writeFile(file: string, data: string, options: {
+        mode: number;
+    }): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+    unlink(file: string): Promise<unknown>;
+    readdir(directory: string): Promise<readonly string[]>;
+    open(file: string, flags: string): Promise<AdoptionIntentFileHandle>;
+}
+export interface AdoptionIntentFileHandle {
+    sync(): Promise<void>;
+    close(): Promise<void>;
+}
+/** What gets persisted per intent. No tokens, no digests. */
+export interface TelegramAdoptionIntent {
+    intendedSessionId: string;
+    topicId: number;
+    chatId: string;
+    target: TelegramAdoptionTarget;
+    createdAt: number;
+    expiresAt: number;
+}
+/** Durable authorization that a topic was observed through forum_topic_created. */
+export interface TelegramPendingTopic {
+    topicId: number;
+    chatId: string;
+    createdAt: number;
+    expiresAt: number;
+}
+/** Compose the per-intent sidecar path. Public so callers/tests can inspect it. */
+export declare function adoptionIntentFilePath(agentDir: string, intendedSessionId: string): string;
+/** Compose the sidecar path for a user-created topic awaiting a folder choice. */
+export declare function pendingTopicFilePath(agentDir: string, topicId: number): string;
+/** Build a fresh intent with `createdAt`/`expiresAt` derived from `now`/`ttlMs`. */
+export declare function buildAdoptionIntent(input: {
+    intendedSessionId: string;
+    topicId: number;
+    chatId: string;
+    target: TelegramAdoptionTarget;
+    now?: number;
+    ttlMs?: number;
+}): TelegramAdoptionIntent;
+/** Test-only: filename suffix used to recognize intent sidecars in a directory listing. */
+export declare const ADOPTION_INTENT_FILENAME_SUFFIX = ".adoption-intent.json";
+export declare const PENDING_TOPIC_FILENAME_SUFFIX = ".pending-topic.json";
+/**
+ * Durable, non-routable adoption-intent store. Owns durable sidecar files and
+ * the synchronous in-memory topicId claim table. The daemon owns Telegram and
+ * lifecycle wiring; this store never calls the Telegram API.
+ */
+export declare class TelegramAdoptionIntentStore {
+    #private;
+    constructor(input: {
+        agentDir: string;
+        fs?: AdoptionIntentFs;
+        now?: () => number;
+        platform?: NodeJS.Platform;
+    });
+    /** Directory holding the sidecar files. */
+    get directory(): string;
+    /** In-memory lookup by intendedSessionId (no disk read). undefined if absent/expired. */
+    bySession(intendedSessionId: string): TelegramAdoptionIntent | undefined;
+    /** In-memory lookup of the (single) non-expired intent for a topicId. */
+    byTopic(topicId: number): TelegramAdoptionIntent | undefined;
+    /** `true` if a non-expired intent already references `topicId`. */
+    hasNonExpiredTopic(topicId: number): boolean;
+    /** Durable authorization for an observed user-created topic, if still live. */
+    pendingTopic(topicId: number): TelegramPendingTopic | undefined;
+    hasPendingTopic(topicId: number, chatId: string): boolean;
+    /**
+     * Synchronously claim `topicId` for `intendedSessionId`. Returns false if a
+     * *different* non-expired intendedSessionId already holds the claim (or has a
+     * non-expired intent for the topic). Same intendedSessionId re-claiming its
+     * own topic is idempotent and succeeds. The claim is in-memory only; it never
+     * deletes the sidecar, so a commit failure can `releaseClaim` and retry.
+     */
+    tryClaim(topicId: number, intendedSessionId: string): boolean;
+    /** Release a claim held by `intendedSessionId` on `topicId`. No-op otherwise. */
+    releaseClaim(topicId: number, intendedSessionId: string): void;
+    /**
+     * Durable write of one intent: temp→write→fsync→chmod(0600)→atomic rename→
+     * chmod(final, 0600)→parent-dir fsync, then track it in memory. The dir is
+     * created owner-only (0700). chmod-ing the final path after the rename makes
+     * the 0600 contract durable regardless of whether the platform's rename
+     * preserves the source mode (POSIX does; some test/network filesystems and
+     * the in-memory test double model rename as copy+delete and would otherwise
+     * drop it). The rename is still the atomic commit point; the final chmod only
+     * tightens permissions on the already-durable file. The in-memory map is only
+     * mutated after the atomic persist succeeds. Rejects (does not swallow) so the
+     * daemon can decide fail-closed behavior.
+     */
+    put(intent: TelegramAdoptionIntent): Promise<void>;
+    /** Persist authorization for a topic observed through forum_topic_created. */
+    putPendingTopic(pendingTopic: TelegramPendingTopic): Promise<void>;
+    /**
+     * Read a single intent sidecar from disk and track it if it is non-expired
+     * and well-formed. Returns the parsed intent (or undefined). Used by
+     * `rehydrate`; callers normally use `rehydrate` / `bySession`.
+     */
+    readIntent(intendedSessionId: string): Promise<TelegramAdoptionIntent | undefined>;
+    readPendingTopic(topicId: number): Promise<TelegramPendingTopic | undefined>;
+    /**
+     * Rehydrate all non-expired intents from the notifications dir. Files are the
+     * only source: missing/corrupt/expired entries are skipped (never thrown).
+     * Returns the count of live intents loaded.
+     */
+    rehydrate(): Promise<number>;
+    /**
+     * Remove a single intent sidecar and drop its in-memory entry. Safe to call
+     * after a successful registry commit or a definite spawn failure. Missing
+     * files are not an error. Never calls the Telegram API.
+     */
+    remove(intendedSessionId: string): Promise<void>;
+    /** Remove a pending-topic authorization after an adoption intent is durable. */
+    removePendingTopic(topicId: number): Promise<void>;
+    /**
+     * Sweep expired intent sidecars from disk. Touches files only. Returns the
+     * count of expired sidecars removed. Safe to run at startup and periodically.
+     */
+    sweepExpired(): Promise<number>;
+}

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

@@ -16,4 +16,16 @@
  * If neither --endpoint-file nor --session-id is given, the newest endpoint file
  * under <repo>/.gjc/state/sdk/ is used.
  */
+import { type TelegramNotificationSound } from "./telegram-reference";
+interface CliArgs {
+    botToken?: string;
+    chatId?: string;
+    endpointFile?: string;
+    sessionId?: string;
+    repo: string;
+    apiBase?: string;
+    sound: TelegramNotificationSound;
+    force: boolean;
+}
+export declare function parseArgs(argv: string[]): CliArgs;
 export {};

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

@@ -38,12 +38,19 @@ export declare const NOTIFICATION_PROTOCOL_VERSION = 3;
  * Generation 29 adds serving-epoch compatibility, sidecar heartbeat, root GC,
  * and Bot API cooldown structural fixes (#2956, #2960, #3048).
  * Generation 30 adds opt-in tool activity delivery, closed lifecycle phases,
- * and capability-versioned mixed-host compatibility.
+ * and capability-versioned mixed-host compatibility. Generation 31 rolls out
+ * non-Linux direct tmux lifecycle cleanup semantics. Generation 32 applies
+ * Telegram sound-notification policy across daemon delivery paths. Generation
+ * 33 adds action-bound multi-select state rendering and replay-safe option
+ * snapshots. Generation 34 converts non-photo image formats (including WebP)
+ * into Telegram-compatible photo uploads when possible. Generation 35 adds
+ * user-created topic adoption (forum-topic folder picker).
  */
-export declare const DAEMON_GENERATION = 30;
+export declare const DAEMON_GENERATION = 35;
 /**
  * Serving-compatibility boundary for daemon lifecycle requests. Epoch 1 covers
  * all builds published before this field existed; epoch 2 covered generation 29;
- * bump this to force serving convergence and reload of compatible live predecessors.
+ * epoch 3 covered generation 30; bump this to force serving convergence and
+ * reload of compatible live predecessors.
  */
-export declare const SERVING_EPOCH = 3;
+export declare const SERVING_EPOCH = 4;