@gajae-code/coding-agent 0.10.1 → 0.11.0

package/dist/types/sdk/bus/discord-provider.d.ts

@@ -0,0 +1,85 @@
+/** Injectable Discord boundary. The daemon owns all persistence and SDK routing. */
+export interface DiscordThread {
+    id: string;
+    guildId: string;
+    parentId: string;
+    archived: boolean;
+    locked?: boolean;
+}
+export interface DiscordInboundEvent {
+    id: string;
+    guildId: string;
+    parentId: string;
+    threadId: string;
+    authorId: string;
+    bot?: boolean;
+    content?: string;
+    interaction?: {
+        id: string;
+        token: string;
+        customId: string;
+        value?: string | number;
+    };
+}
+/** Discord API message components used for action-needed controls. */
+export interface DiscordMessageComponent {
+    type: 1;
+    components: Array<{
+        type: 3;
+        customId: string;
+        placeholder?: string;
+        minValues?: number;
+        maxValues?: number;
+        options: Array<{
+            label: string;
+            value: string;
+        }>;
+    }>;
+}
+export interface DiscordProvider {
+    readonly applicationId: string;
+    readonly botUserId: string;
+    readonly transportHealthy?: boolean;
+    /** Starts a generic text-channel thread from a nonce-bearing parent starter message. */
+    createThread(input: {
+        guildId: string;
+        parentId: string;
+        name: string;
+        nonce: string;
+    }): Promise<DiscordThread>;
+    /** Finds a thread created with a caller-generated nonce after an uncertain create. */
+    findThreadByNonce(input: {
+        guildId: string;
+        parentId: string;
+        nonce: string;
+    }): Promise<DiscordThread | null>;
+    /** Finds a posted message by its caller-generated nonce after an uncertain post. */
+    findMessageByNonce(input: {
+        threadId: string;
+        nonce: string;
+    }): Promise<{
+        id: string;
+    } | null>;
+    postMessage(input: {
+        threadId: string;
+        content: string;
+        nonce?: string;
+        components?: DiscordMessageComponent[];
+    }): Promise<{
+        id: string;
+    }>;
+    /** Defers an accepted component interaction before SDK routing can exceed Discord's response deadline. */
+    deferInteraction(input: {
+        id: string;
+        token: string;
+    }): Promise<void>;
+    archiveThread(input: {
+        threadId: string;
+        locked?: boolean;
+    }): Promise<void>;
+    unarchiveThread(input: {
+        threadId: string;
+    }): Promise<void>;
+    start(onEvent: (event: DiscordInboundEvent) => Promise<void>, onError?: (error: unknown) => void): Promise<void>;
+    stop(): Promise<void>;
+}

package/dist/types/{notifications → sdk/bus}/html-format.d.ts

@@ -1,7 +1,7 @@
 /**
- * Telegram HTML formatting helpers for the notifications SDK.
+ * Telegram HTML formatting helpers for the Gajae-Code SDK.
  *
- * All notifications-SDK Telegram output is sent with `parse_mode: "HTML"`. This
+ * All Gajae-Code SDK Telegram output is sent with `parse_mode: "HTML"`. This
  * module is the single source of truth for: escaping dynamic text, converting a
  * bounded markdown subset into Telegram HTML, safely truncating a finished
  * message to Telegram's 4096-char limit without breaking tags/entities, and

package/dist/types/{notifications → sdk/bus}/index.d.ts

@@ -3,13 +3,13 @@
  *
  * Hosts a per-session loopback WebSocket notification server (the Rust core via
  * N-API) and bridges GJC session events + the `ask` tool to it so a remote client
- * (e.g. a Telegram bot) can both see action-needed signals and ANSWER them —
- * without requiring RPC/unattended mode:
+ * (e.g. a Telegram bot) can both see action-needed signals and answer them
+ * through SDK-native session capabilities:
  *
  * - `ask` (interactive): registers an {@link AskAnswerSource}; the ask tool races
  *   the local UI against a remote reply. First valid answer wins; a local answer
  *   aborts the remote wait (and broadcasts `action_resolved` resolvedBy=local).
- * - `ask` (unattended/RPC): observes emitted workflow gates and resolves the real
+ * - `ask` (workflow gate): observes emitted workflow gates and resolves the real
  *   gate on a remote reply via `ctx.workflowGate`.
  * - `turn_end` -> `action_needed` (kind `idle`, deduped per turn).
  * - `session_shutdown` -> `session_closed` frame, stop server, deregister answer source.
@@ -17,8 +17,13 @@
  * Enable with Settings notifications config, `GJC_NOTIFICATIONS=1` (a token is
  * generated), or `GJC_NOTIFICATIONS_TOKEN`.
  */
-import { Settings } from "../config/settings";
-import type { ExtensionAPI, ExtensionContext } from "../extensibility/extensions";
+import { NotificationServer } from "@gajae-code/natives";
+import { Settings } from "../../config/settings";
+import type { ExtensionAPI, ExtensionContext } from "../../extensibility/extensions";
+import type { WorkflowGateTerminalProof } from "../../modes/shared/agent-wire/workflow-gate-broker";
+import type { AskRemoteControl } from "../../tools";
+import { NotificationSessionController } from "./session-control";
+import { type EnsureDaemonResult } from "./telegram-daemon";
 /** Where a `session_create` should run. Discriminated by `kind`. */
 export type SessionCreateTarget = {
     kind: "existing_path";
@@ -59,7 +64,7 @@ export interface SessionCreateFrame {
     /** Control-endpoint token authorizing this frame. */
     token: string;
     target: SessionCreateTarget;
-    /** Reference to the daemon-written, once-consumed startup-prompt file. */
+    /** Reserved for a future capability transport; any supplied value is rejected before lifecycle acceptance. */
     startupPromptRef?: string;
     /** Model profile preset to activate for the spawned session (--mpreset). */
     modelPreset?: string;
@@ -83,6 +88,7 @@ export interface SessionResumeFrame {
     chatId: string;
     token: string;
     target: SessionResumeTarget;
+    /** Reserved for a future capability transport; any supplied value is rejected before lifecycle acceptance. */
     startupPromptRef?: string;
 }
 /** Any client -> ingress lifecycle request frame. */
@@ -136,7 +142,7 @@ export interface SessionResumeResponseFrame {
     topic: LifecycleTopic;
 }
 /** Machine-readable reason a lifecycle request failed. */
-export type LifecycleErrorReason = "unauthorized" | "rate_limited" | "duplicate_conflict" | "invalid_target" | "ambiguous_target" | "spawn_failed" | "discovery_timeout" | "readiness_timeout" | "close_refused" | "not_found" | "terminal_uncertain";
+export type LifecycleErrorReason = "unauthorized" | "rate_limited" | "duplicate_conflict" | "invalid_target" | "ambiguous_target" | "spawn_failed" | "discovery_timeout" | "readiness_timeout" | "close_refused" | "not_found" | "terminal_uncertain" | "unsupported_platform";
 /** A candidate returned with an `ambiguous_target` resume error. */
 export interface ResumeCandidate {
     sessionId: string;
@@ -175,8 +181,86 @@ export interface SessionReadyFrame {
  * instead of the worktree directory (e.g. `feat-foo-01047f11`).
  */
 export declare function readGitRepoName(cwd: string): string | undefined;
+interface UnattendedGatePresentation {
+    gateId: string;
+    sessionId: string;
+    question: string;
+    options: string[];
+    controls: readonly AskRemoteControl[];
+    multi: boolean;
+    allowEmpty: boolean;
+    navigationLabel?: "Next" | "Done";
+    selectedOptions: string[];
+    workflowGateId?: string;
+    onActivated?: (actionId: string, lease: {
+        actionId: string;
+        registrationEpoch: number;
+    }) => void;
+    onClosed?: () => void;
+}
+type RetireStatus = "retired" | "already_terminal" | "claimed" | "stale";
+type DirectControlOutcome = "accepted" | "rejected" | "unknown";
+export declare class PresentationArbiter {
+    #private;
+    private readonly server;
+    private readonly redact;
+    private readonly tag;
+    private readonly presentations;
+    private readonly routes;
+    private active;
+    private readonly queue;
+    private readonly retries;
+    private readonly retiredProofs;
+    private readonly directControls;
+    /** Explicit terminal proof for a direct control fenced before native publication. */
+    private readonly queuedDirectControls;
+    private retryTimer;
+    private retryTimerGateId;
+    private retryTimerGeneration;
+    private readonly terminalCancellationTimers;
+    private headGeneration;
+    private observedHead;
+    static readonly maxRegistrationAttempts = 3;
+    static readonly retryBaseDelayMs = 50;
+    static readonly retryMaxDelayMs = 1000;
+    /** Bound an unavailable interactive answer source without discarding its head silently. */
+    static readonly terminalCancellationDelayMs = 250;
+    /** Revalidates the live endpoint queue head before bounded recovery. */
+    reconcile(): void;
+    /** Explicit production recovery for a previously exhausted endpoint queue head. */
+    recover(gateId?: string): void;
+    hasActivePresentation(): boolean;
+    retireForDirectControl(gateId: string): RetireStatus;
+    prepareDirectControl(gateId: string): {
+        status: "retired" | "queued";
+        ordinal: number;
+    } | {
+        status: "claimed" | "stale";
+    };
+    finishDirectControl(gateId: string, prepared: {
+        status: "retired" | "queued";
+        ordinal: number;
+    }, outcome: DirectControlOutcome): void;
+    constructor(server: NotificationServer, redact: () => boolean, tag: string);
+    retain(presentation: UnattendedGatePresentation): void;
+    routeFor(actionId: string): string | undefined;
+    presentationFor(actionId: string): UnattendedGatePresentation | undefined;
+    /** The native generic claim has already resolved this old action. */
+    toggle(actionId: string, label: string): boolean;
+    /** Clears an interactive route only when it is still the route that settled. */
+    completeInteractive(gateId: string, actionId: string): void;
+    /** Clears an interactive presentation after its route was retired for direct control. */
+    completeDirect(gateId: string): void;
+    reissueAfterFailure(actionId: string): void;
+    reissue(gateId: string): string | undefined;
+    closeInteraction(actionId: string, reason: string): boolean;
+    complete(gateId: string): WorkflowGateTerminalProof;
+    cancelInteractive(): void;
+    cancel(gateId: string, reason: string): void;
+    dispose(): void;
+}
 export declare function notificationsEnabled(): boolean;
-/** Workflow-gate answer shape (unattended mode). */
+/** Workflow-gate answer shape. */
 interface GateAnswer {
     selected: string[];
     other?: boolean;
@@ -195,11 +279,11 @@ type GateAnswerResult = {
     reason: string;
 };
 /**
- * Map a client answer to the workflow-gate answer shape (unattended mode).
+ * Map a client answer to the workflow-gate answer shape.
  *
  * The protocol defines a numeric reply as an option index, so a number outside
- * `options` is invalid (issue #2030): it must NOT be converted into a free-text
- * `Other` that passes the ask schema and triggers a misleading success ack.
+ * `options` is invalid: it must NOT be converted into free text that passes the
+ * ask schema and triggers a misleading success acknowledgement.
  * Only JSON strings enter the free-text/Other path.
  */
 export declare function mapAnswerToGate(answerJson: string, options: string[]): GateAnswerResult;
@@ -207,13 +291,29 @@ interface NotificationControlCommandPayload {
     name?: unknown;
     action?: unknown;
     level?: unknown;
+    global?: unknown;
+    selector?: unknown;
     instructions?: unknown;
 }
-export declare function executeNotificationControlCommand(command: NotificationControlCommandPayload | undefined, ctx: ExtensionContext, api: ExtensionAPI): Promise<{
+export interface NotificationControlCommandResult {
     status: "ok" | "error" | "unavailable";
     message: string;
-}>;
+    modelChoices?: Array<{
+        selector: string;
+        label: string;
+    }>;
+}
+export declare function executeNotificationControlCommand(command: NotificationControlCommandPayload | undefined, ctx: ExtensionContext, api: ExtensionAPI, expectedSessionId?: string): Promise<NotificationControlCommandResult>;
 export declare function createNotificationsExtension(api: ExtensionAPI, options?: {
     settings?: Settings;
+    ensureTelegramDaemon?: (input: {
+        settings: Settings;
+        cwd: string;
+        sessionId: string;
+    }) => Promise<EnsureDaemonResult>;
+    /** Suppress auto-delivery for a GJC-spawned child under `sessionScope=primary`. */
+    spawnedByGjc?: boolean;
+    controller?: NotificationSessionController;
+    onSdkRequest?: (kind: "control" | "query", connectionId: string, frame: Record<string, unknown>) => void;
 }): void;
 export {};

package/dist/types/{notifications → sdk/bus}/lifecycle-control-runtime.d.ts

@@ -1,5 +1,5 @@
-import { type OwnerIsolationProbe } from "../gjc-runtime/tmux-owner-isolation";
-import { type GjcTmuxSessionStatus } from "../gjc-runtime/tmux-sessions";
+import { type OwnerIsolationProbe } from "../../gjc-runtime/tmux-owner-isolation";
+import { type GjcTmuxSessionStatus } from "../../gjc-runtime/tmux-sessions";
 import type { ResumeCandidate, SessionCreateFrame, SessionLifecycleRequest, SessionLifecycleResponse } from "./index";
 import { type AuditEvent, type CreateEffectResult, type LedgerStore, type LifecycleOutcome, type OrchestratorDeps, type ResumeEffectResult } from "./lifecycle-orchestrator";
 /** Minimal view of the native control server this runtime depends on. */
@@ -96,6 +96,8 @@ export declare function attachLifecycleControl(server: ControlServerLike, deps:
 export declare function buildOrchestratorDeps(input: {
     pairedChatId: string;
     agentNotificationsDir: string;
+    /** Required in-memory, 32-byte audit-v2 redaction key. */
+    auditRedactionKey: Uint8Array;
     /** Root of saved session histories (`<agentDir>/sessions`), for resume resolution. */
     sessionsRoot?: string;
     env?: NodeJS.ProcessEnv;

package/dist/types/{notifications → sdk/bus}/lifecycle-orchestrator.d.ts

@@ -19,6 +19,7 @@ export interface LedgerEntry {
     /** Close effect outcome: whether the tmux process is confirmed gone. */
     processGone?: boolean;
     reason?: LifecycleErrorReason;
+    resumeMode?: ResumeEffectResult["mode"];
 }
 /** The full on-disk ledger document. */
 export interface LedgerDoc {
@@ -31,23 +32,18 @@ export interface LedgerStore {
     /** Write atomically (temp + fsync + rename) under a per-ledger lock. */
     write(doc: LedgerDoc): Promise<void>;
 }
-/** One audit line. Tokens and raw prompts are NEVER included. */
+/** Redacted audit-v2 event. */
 export interface AuditEvent {
+    schemaVersion: 2;
     ts: string;
     event: "accepted" | "rejected" | "duplicate_reack" | "rate_limited" | "spawn_started" | "recovered_in_progress" | "success" | "failure" | "terminal_uncertain";
-    chatId: string;
+    chatRef: string;
     updateId: number;
-    requestId: string;
-    requestHash: string;
+    requestRef: string;
     verb: SessionLifecycleRequest["type"];
-    targetSummary: Record<string, unknown>;
-    sessionId?: string;
-    tmuxSession?: string;
+    targetKind: CanonicalTargetKind;
+    targetRef: string;
     reason?: LifecycleErrorReason;
-    /** Prompt byte length only (never the prompt text). */
-    promptBytes?: number;
-    /** Prompt content hash only (never the prompt text). */
-    promptHash?: string;
 }
 export interface CreateEffectResult {
     sessionId: string;
@@ -63,13 +59,17 @@ export interface ResumeEffectResult extends CreateEffectResult {
 export interface OrchestratorDeps {
     /** The single paired chat id. Anything else is rejected before parsing. */
     pairedChatId: string;
+    /** In-memory, derived 32-byte audit-v2 HMAC key. */
+    auditRedactionKey: Uint8Array;
     now: () => number;
     store: LedgerStore;
     audit: (event: AuditEvent) => Promise<void> | void;
+    /** Resolves the returned tmux provider once per request for psmux preflight. */
+    isPsmuxProvider: () => boolean;
     /** Per-chat create rate limiter: returns true when allowed. */
     allowCreate: (chatId: string, nowMs: number) => boolean;
-    /** Persist the once-consumed 0600 startup-prompt file; returns its ref. */
-    writeStartupPrompt: (requestId: string, prompt: string | undefined) => Promise<string | undefined>;
+    /** Persist the once-consumed 0600 startup-prompt file after durably recording its ref. */
+    writeStartupPrompt: (requestId: string, prompt: string | undefined, persistRef: (ref: string) => Promise<void>) => Promise<string | undefined>;
     /** Spawn a session for a create/cold-restart. */
     spawnCreate: (frame: SessionCreateFrame, ids: {
         lifecycleRequestId: string;
@@ -91,16 +91,13 @@ export interface OrchestratorDeps {
     } | {
         notFound: true;
     }>;
-    newLifecycleRequestId: () => string;
-    newSessionId: () => string;
 }
-/** A redaction-safe summary of a request target (never includes the token). */
-export declare function summarizeTarget(frame: SessionLifecycleRequest): Record<string, unknown>;
-/**
- * Stable request hash over the meaningful (non-token) request content. Used to
- * detect a duplicate update id reused with a DIFFERENT body (conflict).
- */
+export type CanonicalTargetKind = "existing_path" | "worktree" | "plain_dir" | "session_close" | "session_resume";
+export declare function canonicalTarget(frame: SessionLifecycleRequest): string;
+export declare function canonicalRequest(frame: SessionLifecycleRequest): string;
 export declare function requestHash(frame: SessionLifecycleRequest): string;
+export declare function auditRedactionRef(key: Uint8Array, domain: string, value: string): string;
+export declare function summarizeTarget(frame: SessionLifecycleRequest): Record<string, unknown>;
 export declare function ledgerKey(chatId: string, updateId: number): string;
 /** How a freshly-arrived request relates to the durable ledger. */
 export type DuplicateClass = {

package/dist/types/{notifications → sdk/bus}/managed-daemon.d.ts

@@ -1,4 +1,4 @@
-import type { Settings } from "../config/settings";
+import type { Settings } from "../../config/settings";
 import { RateLimitPool } from "./rate-limit-pool";
 import { type ThreadedSend } from "./threaded-render";
 export interface ManagedNotificationDaemonFs {

package/dist/types/sdk/bus/native-runtime-compatibility.d.ts

@@ -0,0 +1,13 @@
+export declare class NativeRuntimeCompatibilityError extends Error {
+    readonly runtimeVersion: string;
+    readonly nativeVersion: string;
+    readonly workflowArbitrationAvailable: boolean;
+    readonly code = "native_runtime_incompatible";
+    readonly retryable = false;
+    constructor(runtimeVersion: string, nativeVersion: string, workflowArbitrationAvailable: boolean);
+}
+export declare function assertNativeRuntimeCompatibility(input: {
+    runtimeVersion: string;
+    nativeVersion: string;
+    notificationServer: unknown;
+}): void;

package/dist/types/sdk/bus/notification-orchestration.d.ts

@@ -0,0 +1,170 @@
+import type { RawSettings, SettingsAtomicPatch, SettingsAtomicReceipt } from "../../config/settings";
+import { type NotificationSettingsReader, type TelegramActivationMarker, type TelegramActivationMarkers, type TelegramActivationReason, type TelegramActivationState, telegramActivationIdentity } from "./config";
+import { type EnsureTelegramDaemonDetailedResult, type TelegramDaemonFs } from "./telegram-daemon";
+export type { TelegramActivationMarker, TelegramActivationMarkers, TelegramActivationReason, TelegramActivationState };
+export { telegramActivationIdentity };
+/** The identity relationship between a proposed Telegram configuration and a live daemon owner. */
+export type ProposedTelegramIdentityStatus = "absent" | "same" | "foreign" | "unknown";
+/**
+ * Non-secret metadata about a daemon owner. Token fingerprints and the owner's
+ * chat ID intentionally never cross this boundary. `chatDisplay`, when present,
+ * is supplied by the caller from an already-approved proposed-chat display.
+ */
+export interface TelegramDaemonOwnerMetadata {
+    ownerId: string;
+    pid: number;
+    generation?: number;
+    chatDisplay?: string;
+}
+/** Secret-safe proposed-identity preflight outcome. */
+export interface ProposedTelegramIdentity {
+    status: ProposedTelegramIdentityStatus;
+    owner?: TelegramDaemonOwnerMetadata;
+}
+export interface ProposedTelegramIdentityPreflightInput {
+    settings: NotificationSettingsReader;
+    botToken: string;
+    chatId: string;
+    /** A UI-approved display value for the proposed chat; never inferred from a foreign daemon state. */
+    chatDisplay?: string;
+    deps?: {
+        fs?: TelegramDaemonFs;
+        pidAlive?: (pid: number) => boolean;
+    };
+}
+/**
+ * Compare a proposed identity with the current daemon owner without exposing a
+ * token or token fingerprint. Invalid/unreadable state is deliberately
+ * `unknown`, which callers must treat as cancel-by-default.
+ */
+export declare function proposedTelegramIdentity(input: ProposedTelegramIdentityPreflightInput): Promise<ProposedTelegramIdentity>;
+export interface NotificationConfigurationWriter extends NotificationSettingsReader {
+    commitAtomicBatch(patches: readonly SettingsAtomicPatch[]): Promise<SettingsAtomicReceipt>;
+    commitAtomicBatchWithCurrent?(buildPatches: (current: Readonly<RawSettings>) => Promise<readonly SettingsAtomicPatch[]> | readonly SettingsAtomicPatch[]): Promise<SettingsAtomicReceipt>;
+}
+export declare function createTelegramActivationMarker(input: {
+    botToken: string;
+    chatId: string;
+    state: TelegramActivationState;
+    reason?: TelegramActivationReason;
+    now?: Date;
+}): TelegramActivationMarker;
+export declare function observedTelegramActivationMarker(settings: NotificationSettingsReader, botToken: string, chatId: string): TelegramActivationMarker | undefined;
+/** Persist one durable marker without discarding markers for other identities. */
+export declare function persistTelegramActivationMarker(settings: NotificationConfigurationWriter, marker: TelegramActivationMarker): Promise<SettingsAtomicReceipt>;
+/** Clear only the exact marker that was safely reconciled. */
+export declare function clearTelegramActivationMarker(settings: NotificationConfigurationWriter, marker: TelegramActivationMarker): Promise<void>;
+export type CompleteNonTelegramAdapter = "discord" | "slack";
+export type SaveTelegramInactiveAvailability = {
+    available: true;
+};
+/**
+ * Telegram-specific activation markers let Save inactive preserve globally
+ * enabled Discord and Slack adapters, so the action is always available.
+ */
+export declare function getSaveTelegramInactiveAvailability(_settings: NotificationSettingsReader): SaveTelegramInactiveAvailability;
+export type SaveTelegramInactiveResult = {
+    status: "saved_inactive";
+    receipt: SettingsAtomicReceipt;
+};
+/**
+ * Atomically persist Telegram credentials with a non-secret inactive marker.
+ * Global notifications are disabled only when Telegram is the sole complete adapter.
+ */
+export declare function saveTelegramInactive(input: {
+    settings: NotificationConfigurationWriter;
+    botToken: string;
+    chatId: string;
+}): Promise<SaveTelegramInactiveResult>;
+export interface TelegramRemovalRuntime {
+    /** Stops the local endpoint, unregisters its root, and stops an unreferenced old daemon. */
+    stopAndUnregister(): Promise<void>;
+}
+/**
+ * Remove Telegram credentials without disturbing other adapters. Runtime
+ * teardown is intentionally first: a failed teardown leaves durable credentials
+ * untouched rather than orphaning an old daemon/root behind a successful delete.
+ */
+export declare function removeTelegramConfiguration(input: {
+    settings: NotificationConfigurationWriter;
+    removal: TelegramRemovalRuntime;
+}): Promise<{
+    receipt: SettingsAtomicReceipt;
+    globallyDisabled: boolean;
+}>;
+/** Detailed outcome of checking or reconnecting the Telegram daemon after a durable commit. */
+export type TelegramDaemonReconnectOutcome = EnsureTelegramDaemonDetailedResult;
+/**
+ * The session controller must not resolve `enterBlockedRuntime` until its
+ * current endpoint has stopped and been removed. This lets callers report a
+ * blocked save only after no further frames can reach the foreign owner.
+ */
+export interface NotificationRuntimeController {
+    /** Resolves only after the current endpoint is stopped and removed. */
+    enterBlockedRuntime(): Promise<unknown>;
+    clearBlockedRuntime(): Promise<unknown>;
+    reconcileCurrentSession(): Promise<unknown>;
+}
+export interface TelegramPostCommitActivation {
+    controller: NotificationRuntimeController;
+    reconnect: () => Promise<TelegramDaemonReconnectOutcome>;
+    /** Durable Telegram-only marker write after the endpoint has stopped. */
+    persistInactive(marker: TelegramActivationMarker): Promise<SettingsAtomicReceipt>;
+    /** Remove the exact activation marker only after a safe reconnect. */
+    clearInactive(marker: TelegramActivationMarker): Promise<void>;
+    marker: TelegramActivationMarker;
+}
+export type PostCommitTelegramActivationResult = {
+    status: "activated";
+    reconnect: Exclude<TelegramDaemonReconnectOutcome, "blocked_identity">;
+} | {
+    status: "blocked_identity";
+    message: string;
+    restore(): Promise<BlockedTelegramRestoreResult>;
+    retainCommitted(): void;
+};
+export type BlockedTelegramRestoreResult = {
+    status: "restored";
+    reconnect: TelegramDaemonReconnectOutcome;
+} | {
+    status: "conflict";
+    paths: readonly string[];
+} | {
+    status: "discarded";
+} | {
+    status: "still_blocked";
+};
+/**
+ * Complete a committed Telegram update in the required order: identity
+ * reconnect first, normal session reconciliation second. A post-commit foreign
+ * owner race stops the endpoint, durably marks only that Telegram identity
+ * inactive, then exposes an ordered CAS restore/retain choice.
+ */
+export declare function reconcileCommittedTelegramConfiguration(input: {
+    receipt: SettingsAtomicReceipt;
+    activation: TelegramPostCommitActivation;
+    inactiveMarkerToClear?: TelegramActivationMarker;
+}): Promise<PostCommitTelegramActivationResult>;
+export type SaveTelegramConfigurationResult = {
+    status: "cancelled";
+    preflight: ProposedTelegramIdentity;
+    guidance: string;
+} | SaveTelegramInactiveResult | {
+    status: "saved";
+    receipt: SettingsAtomicReceipt;
+    preflight: ProposedTelegramIdentity;
+} | PostCommitTelegramActivationResult;
+/**
+ * Guard a Telegram setup commit with proposed-identity preflight. Foreign and
+ * unreadable ownership are cancel-by-default and make no configuration changes.
+ */
+export declare function saveTelegramConfiguration(input: {
+    settings: NotificationConfigurationWriter;
+    botToken: string;
+    chatId: string;
+    chatDisplay?: string;
+    /** Explicitly persist credentials disabled after a foreign/unknown preflight; otherwise cancel remains the default. */
+    saveInactive: boolean;
+    preflight?: (input: Omit<ProposedTelegramIdentityPreflightInput, "settings">) => Promise<ProposedTelegramIdentity>;
+    activation?: TelegramPostCommitActivation;
+}): Promise<SaveTelegramConfigurationResult>;

package/dist/types/{notifications → sdk/bus}/notification-service.d.ts

@@ -1,4 +1,4 @@
-import type { Settings } from "../config/settings";
+import type { Settings } from "../../config/settings";
 /**
  * Strip secrets from a human-facing diagnostic string. Redacts the configured
  * bot token (exact match) and any token-shaped substring so health/test details
@@ -60,7 +60,13 @@ export interface DaemonHealth {
     heartbeatFresh: boolean;
     identityMatches: boolean;
     stopped: boolean;
+    heartbeatAt: number | undefined;
+    heartbeatAgeMs: number | undefined;
+    generation: number | undefined;
+    currentGeneration: number;
+    generationRelation: DaemonGenerationRelation;
 }
+export type DaemonGenerationRelation = "pre_generation" | "older" | "current" | "newer" | "unknown";
 export interface EndpointHealth {
     total: number;
     live: number;