@gajae-code/coding-agent 0.12.11 → 0.12.12

package/dist/types/sdk/bus/slack-thread-binding.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Adoption of an operator-supplied Slack thread as a live session's root.
+ *
+ * Three separate authorities have to agree before a mapping exists:
+ *  1. *Configuration*: a complete Slack target (both tokens plus workspace and
+ *     channel) must already be configured; binding never accepts a target.
+ *  2. *Daemon*: only the running owner may mutate mappings, and only while it is
+ *     still the exact owner (`ownerId`/`pid`/`incarnation`/daemon generation)
+ *     captured before the request was published.
+ *  3. *Session*: the SDK session must be attachable right now — indexed, live,
+ *     non-terminal, with a readable, non-stale endpoint whose pid matches the
+ *     indexed host and whose generation has not rolled.
+ *
+ * Provider verification happens before any lock is taken, and the mapping commit
+ * re-proves session authority inside the store lock, so an authority that
+ * changes mid-flight leaves no mapping behind.
+ */
+import type { Settings } from "../../config/settings";
+import type { SessionIndex } from "../broker/session-index";
+import { type SdkSessionEndpoint, type SdkSessionEndpointScope } from "../client/discovery";
+import { type EnsureChatDaemonResult } from "./chat-daemon-control";
+import { ConversationStore } from "./conversation-store";
+import { type SlackConversation } from "./slack-conversation";
+export type SlackThreadBindingErrorCode = "invalid_root" | "target_not_configured" | "daemon_unavailable" | "daemon_owner_changed" | "session_not_live" | "root_not_found" | "provider_unavailable" | "root_conflict" | "session_conflict" | "binding_outcome_unknown" | "binding_failed";
+/** A fail-closed rejection while adopting an operator-supplied Slack thread. */
+export declare class SlackThreadBindingError extends Error {
+    readonly code: SlackThreadBindingErrorCode;
+    constructor(code: SlackThreadBindingErrorCode, message: string);
+}
+export declare function isBoundedSlackRootTs(value: string): boolean;
+/** Reject a non-addressable root before any authority read or persistence. */
+export declare function assertBoundedSlackRootTs(rootTs: string): void;
+export interface SlackSessionBindingAuthority {
+    sessionId: string;
+    endpointGeneration: number;
+    pid: number;
+    repo: string;
+    /**
+     * The exact endpoint this authority was proven against. Callers must use it
+     * rather than re-reading discovery: a second read can observe a different
+     * process whose endpoint generation happens to repeat, and the numeric
+     * generation alone cannot tell the two apart.
+     */
+    endpoint: SdkSessionEndpoint;
+    scope: SdkSessionEndpointScope;
+    endpointMtimeMs: number;
+}
+export interface SessionBindingAuthorityInput {
+    sessionIndex: SessionIndex;
+    sessionId: string;
+    readEndpoint?: (repo: string, sessionId: string, scope?: SdkSessionEndpointScope) => Promise<SdkSessionEndpoint | null>;
+    statEndpoint?: (endpointPath: string) => Promise<{
+        mtimeMs: number;
+    } | undefined>;
+}
+/**
+ * Resolve exact discovery/attachment authority for one session.
+ *
+ * `IndexedSession.live` alone is only pid liveness, which a terminated or
+ * unregistered session can still satisfy through pid reuse or a stale record.
+ * Adoption additionally requires an intact index replay, a non-terminal record,
+ * and a discovery endpoint that is present, well-formed, not marked stale, and
+ * owned by the same host pid the index recorded.
+ */
+export declare function resolveSessionBindingAuthority(input: SessionBindingAuthorityInput): Promise<SlackSessionBindingAuthority | undefined>;
+export interface SlackThreadClaimInput {
+    store: ConversationStore<SlackConversation>;
+    /** The session root-claim key shared with stock root publication. */
+    key: string;
+    teamId: string;
+    channelId: string;
+    sessionId: string;
+    rootTs: string;
+    endpointGeneration: number;
+    /**
+     * Re-proves session authority inside the store lock, immediately before
+     * commit. It may be invoked more than once for one claim: authority here is
+     * monotone — a rolled endpoint generation, a replaced daemon owner tuple and
+     * a retired single-winner request claim never come back — so repeating the
+     * proof can only ever narrow the window, never widen it. It must therefore be
+     * idempotent and must never perform a remote call.
+     */
+    revalidate: () => Promise<boolean>;
+    now?: () => number;
+}
+/**
+ * Claim an existing Slack root for a session without publishing a replacement.
+ *
+ * The claim transacts the same `intent:<sessionId>` key that stock root
+ * publication uses, so a bind and a concurrent first notification serialize on
+ * one invariant: whichever commits first owns the session's single root, and
+ * the loser observes it instead of creating a second one.
+ */
+export declare function claimSlackThreadBinding(input: SlackThreadClaimInput): Promise<SlackConversation>;
+export interface ConfiguredSlackThreadBindingInput {
+    settings: Settings;
+    sessionId: string;
+    threadTs: string;
+}
+export interface ConfiguredSlackThreadBindingDeps {
+    ensureDaemon?: (settings: Settings) => Promise<EnsureChatDaemonResult>;
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    /** Bounded wait for a daemon that took terminal authority before the caller gave up. */
+    settleGraceMs?: number;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/** Safe confirmation of an applied binding. It carries identifiers only. */
+export interface BoundSlackThread {
+    sessionId: string;
+    endpointGeneration: number;
+    teamId: string;
+    channelId: string;
+    rootTs: string;
+    ownerId: string;
+    daemonGeneration: number;
+}
+/**
+ * Adopt an existing Slack root for a live session through the running daemon.
+ *
+ * The CLI never writes the mapping store: it proves the configured target and
+ * the exact current owner, then asks that owner to perform the mutation. A
+ * daemon that is no longer the captured owner answers `owner_changed`, so a
+ * replacement or restart between capture and execution can never apply the
+ * request.
+ *
+ * A submission that is not answered is cancelled through the channel's
+ * single-winner arbitration before it is reported as a failure. If that
+ * cancellation loses to the daemon's own commit authority, the outcome is
+ * reported as unknown instead of as a failure, because a mapping may already
+ * exist; re-running the same command observes the settled state idempotently.
+ *
+ * The command channel proves *correlation*, never authorship: every field a
+ * response echoes is copied verbatim out of the plaintext request published
+ * beside it. A definitive answer is therefore reported only after this caller
+ * itself observes the exact mutation in the conversation store — see
+ * `corroborateBoundMapping`.
+ */
+export declare function bindConfiguredSlackThread(input: ConfiguredSlackThreadBindingInput, deps?: ConfiguredSlackThreadBindingDeps): Promise<BoundSlackThread>;

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

@@ -23,6 +23,8 @@ export interface RunDaemonInternalDeps {
     clearInterval?: (timer: Timer) => void;
     /** Reads persisted daemon ownership state; defaults to the real reader. */
     readDaemonState?: (settings: Settings) => Promise<DaemonState | undefined>;
+    /** Loads the verified machine-local identity; injectable so daemon tests do not touch the host. */
+    loadInstallationHostId?: () => Promise<string>;
 }
 export declare function createLightweightDaemonSettings(input: {
     agentDir: string;

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

@@ -53,15 +53,32 @@ export declare const NOTIFICATION_PROTOCOL_VERSION = 3;
  * ownership, settlement, and descendant cleanup authority. Generation 38 also
  * adds durable provider-intent admission without changing owner, reclaim,
  * signal, or spawn authority.
+ * Generation 41 applies first-class provider-settings admission to Telegram
+ * lifecycle controls, plus cross-host topic-registry CAS convergence, host-and-epoch
+ * archive fencing, retained topic history, user-topic adoption provenance, and
+ * exact versionless shared-state upgrades with quarantined source snapshots.
  * Generation 42 applies first-class provider-settings admission to Telegram
  * lifecycle controls. Generation 43 applies identity-bound exact replacement
- * cleanup shared by managed-session and daemon filesystem authority.
+ * cleanup shared by managed-session and daemon filesystem authority. Generation
+ * 44 makes callback recovery restart-safe by revoking persisted routes and
+ * callback receipts durable before routing and binds aliases to exact asks.
+ * Generation 46 stages accepted callback activation and makes callback
+ * consumption transactional under exact pending and lease authority. Generation
+ * 47 settles failed staged revocation and guards the complete callback authority
+ * and polling dependency chain. Generation 48 uses crash-durable callback
+ * receipts, a legacy-disjoint random alias namespace, and exact topic leases.
+ * Generation 49 drains every admitted session-message handler before final
+ * durable persistence and ownership release. Generation 50 resolves intermediate
+ * notifications-directory symlinks before native exact unlink while keeping
+ * final-component file symlinks fail-closed under AT_SYMLINK_NOFOLLOW (bounded
+ * #3761 multi-account activation repair). Generation 51 adds shared durable
+ * topic authority, archive recovery, and requires Telegram's documented error
+ * code for idempotent archive settlement.
  */
-export declare const DAEMON_GENERATION = 43;
+export declare const DAEMON_GENERATION = 51;
 /**
- * Serving-compatibility boundary for daemon lifecycle requests. Epoch 1 covers
- * all builds published before this field existed; epoch 2 covered generation 29;
- * epoch 3 covered generation 30; bump this to force serving convergence and
- * reload of compatible live predecessors.
+ * Serving-compatibility boundary for daemon lifecycle requests. Epoch 5
+ * requires the complete generation-36 topic authority contract, so older
+ * epoch-4 daemons cannot keep serving across an upgrade.
  */
-export declare const SERVING_EPOCH = 4;
+export declare const SERVING_EPOCH = 5;

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

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import { type NativeExactFileIdentity, type NativeExactUnlinkResult } from "@gajae-code/natives";
 import type { Settings } from "../../config/settings";
 import type { DaemonRuntimeInfo } from "../../daemon/control-types";
 import { HEARTBEAT_TTL_MS } from "./daemon-paths";
@@ -10,7 +11,7 @@ import { type ControlServerLike, type LifecycleControlServerFactory } from "./li
 import type { OrchestratorDeps } from "./lifecycle-orchestrator";
 import { NotificationOperatorRuntime } from "./operator-runtime";
 import { type AliasTable, type CallbackRoute } from "./telegram-reference";
-import { type TopicEndpointBinding } from "./topic-registry";
+import { type TopicEndpointBinding, type TopicRegistryCasAuthority, type TopicRegistryState } from "./topic-registry";
 export type EnsureDaemonResult = "owner_spawned" | "attached" | "disabled" | "blocked";
 /** Detailed result for orchestration that must distinguish a #2028 handoff from a fresh spawn. */
 export type EnsureTelegramDaemonDetailedResult = "spawned" | "reloaded" | "attached" | "disabled" | "blocked_identity";
@@ -45,6 +46,14 @@ export interface DaemonState {
     servingEpoch?: number;
     stoppedAt?: number;
 }
+interface ExactFileStat {
+    dev: bigint;
+    ino: bigint;
+    nlink: bigint;
+    size: bigint;
+    mtimeNs: bigint;
+    isFile(): boolean;
+}
 export interface TelegramDaemonFs {
     mkdir(path: string, opts?: fs.MakeDirectoryOptions): Promise<void>;
     readFile(path: string, encoding: BufferEncoding): Promise<string>;
@@ -52,10 +61,14 @@ export interface TelegramDaemonFs {
     rename(oldPath: string, newPath: string): Promise<void>;
     unlink(path: string): Promise<void>;
     open(path: string, flags: string, mode?: number): Promise<{
+        sync?: () => Promise<void>;
         close(): Promise<void>;
     }>;
     readdir(path: string): Promise<string[]>;
     chmod(path: string, mode: number): Promise<void>;
+    /** Crash-atomic persistence seams. Implementations without them fail closed. */
+    fsyncFile?(path: string): Promise<void>;
+    fsyncDirectory?(path: string): Promise<void>;
     stat?(path: string): Promise<{
         mtimeMs: number;
         size?: number;
@@ -64,8 +77,11 @@ export interface TelegramDaemonFs {
         /** Hard-link count; required to prove a staging temp has no second name. */
         nlink?: number;
         ctimeMs?: number;
-        isDirectory?: () => boolean;
+        isDirectory?(): boolean;
     }>;
+    lstat?(path: string, opts: {
+        bigint: true;
+    }): Promise<ExactFileStat>;
     readEndpointFile?(path: string): Promise<NotificationEndpointFile>;
     exactUnlink?(path: string, identity: NotificationEndpointFileIdentity, quarantineName?: string): Promise<NotificationExactUnlinkResult>;
 }
@@ -151,6 +167,49 @@ export declare function startDaemonLifecycleControl(input: {
     auditRedactionKey: Uint8Array;
     env?: NodeJS.ProcessEnv;
 }): OrchestratorDeps;
+export declare class TopicRegistryDurabilityUnavailableError extends Error {
+    readonly code = "durability_unavailable";
+    constructor(cause: unknown);
+}
+type TopicRegistryExactReplace = (sourcePath: string, destinationPath: string, expectedSource: NativeExactFileIdentity, expectedDestination: NativeExactFileIdentity) => NativeExactUnlinkResult;
+/** Publish topic authority only after its staged bytes and replacement are durable. */
+export declare function writeTopicRegistryAtomic(fsImpl: TelegramDaemonFs, file: string, data: unknown, platform?: NodeJS.Platform, exactReplace?: TopicRegistryExactReplace, expectedDestination?: NativeExactFileIdentity): Promise<void>;
+/**
+ * Shared-volume topic authority backed by the existing cross-process file lock.
+ * A missing authority is the only valid bootstrap state; malformed and future
+ * snapshots are never interpreted as empty state.
+ */
+export declare class FilesystemTopicRegistryCasAuthority implements TopicRegistryCasAuthority {
+    #private;
+    private readonly file;
+    private readonly fsImpl;
+    private readonly platform;
+    private readonly exactReplace;
+    private readonly installationHostId;
+    constructor(file: string, input: {
+        installationHostId: string;
+        fs?: TelegramDaemonFs;
+        platform?: NodeJS.Platform;
+        exactReplace?: TopicRegistryExactReplace;
+    });
+    read(): Promise<TopicRegistryState>;
+    compareAndSet(expectedGeneration: number, next: TopicRegistryState): Promise<boolean>;
+    private readLocked;
+}
+export interface MachineIdentityDeps {
+    platform?: NodeJS.Platform;
+    readFile?: (file: string) => Promise<string>;
+    runCommand?: (command: string, args: readonly string[]) => {
+        exitCode: number;
+        stdout: Uint8Array;
+    };
+}
+/** @internal */
+export declare function parseWindowsMachineGuid(output: string): string | undefined;
+/** @internal */
+export declare function parseMacPlatformUuid(output: string): string | undefined;
+/** Loads a verified machine-local identity without persisting the underlying machine ID. */
+export declare function loadInstallationHostId(deps?: MachineIdentityDeps): Promise<string>;
 export declare function tryCreateOwnershipLock(fsImpl: TelegramDaemonFs, file: string, initialization: OwnershipLockMetadata): Promise<boolean>;
 type OwnershipLockMetadata = {
     pid: number;
@@ -552,6 +611,8 @@ export interface TelegramSpawnOwnerInput {
     roots?: string[];
     tokenFingerprint: string;
     chatId: string;
+    /** Ephemeral outbound-only validation destination for this owner launch. */
+    validationTestSupergroupChatId?: string;
 }
 export interface TelegramSpawnAcquisition {
     readonly ownerId: string;
@@ -587,6 +648,7 @@ export declare function buildTelegramDaemonSpawnArgs(input: {
     execPath?: string;
     ownerId: string;
     agentDir: string;
+    validationTestSupergroupChatId?: string;
 }): {
     command: string;
     args: string[];
@@ -732,6 +794,12 @@ export interface TelegramDaemonOptions {
     ownerId: string;
     botToken: string;
     chatId: string;
+    /**
+     * Exact ephemeral forum destination supplied to the daemon-internal validation
+     * command. Production ownership, pairing, and durable topic authority remain
+     * bound to `chatId`.
+     */
+    validationTestSupergroupChatId?: string;
     apiBase?: string;
     fetchImpl?: typeof fetch;
     fs?: TelegramDaemonFs;
@@ -793,6 +861,13 @@ export interface TelegramDaemonOptions {
     topics?: {
         nameTemplate?: string;
     };
+    /**
+     * Optional compare-and-set store for installations that share topic state
+     * across hosts. When configured, every publication is fenced by it.
+     */
+    topicRegistryAuthority?: TopicRegistryCasAuthority;
+    /** Stable host-local identity. Required whenever a shared authority is configured. */
+    installationHostId?: string;
 }
 interface SessionSocket {
     /** Immutable key of the transport endpoint that owns this socket. */
@@ -841,6 +916,9 @@ export declare class TelegramNotificationDaemon {
     private readonly opts;
     readonly aliasTable: AliasTable;
     readonly messageRoutes: Map<string | number, CallbackRoute | Omit<CallbackRoute, "answer">>;
+    /** Restart-revoked aliases retained only to terminalize their old keyboards on an authoritative replay. */
+    private readonly reissueBacklog;
+    private aliasPersistenceQueue;
     /** Telegram message id backing each streamed `${sessionId}:${coalesceKey}`, for in-place edits. */
     private readonly liveMessages;
     /** Endpoint-bound ownership for visible or dispatching tool bubbles. */
@@ -868,6 +946,8 @@ export declare class TelegramNotificationDaemon {
     private readonly botApi;
     private readonly effects;
     private readonly topics;
+    /** Stable host-local identity; never persisted in shared topic authority. */
+    private installationHostId;
     /** Serializes registry snapshots so an older atomic write cannot overwrite newer rename state. */
     /** Legacy sockets have no durable token, so explicit teardown is their revocation fence. */
     private readonly droppedSessions;
@@ -876,6 +956,8 @@ export declare class TelegramNotificationDaemon {
     private recoveryBindingClaimQueue;
     /** Durable compensation fences retry under supervision until persistence succeeds. */
     private readonly compensationFenceRetries;
+    /** All archive paths for one session share one durable fence and remote dispatch. */
+    private readonly archiveFlights;
     /** Daemon edit attempts that can race an accepted user service message. */
     private readonly daemonRenameAttempts;
     private readonly selectedAckPending;
@@ -906,8 +988,8 @@ export declare class TelegramNotificationDaemon {
     private threadedFallbackNoticeSent;
     /** Sessions whose identity header was already sent flat (Threaded Mode off). */
     private readonly flatIdentitySent;
-    /** Cached result of whether the paired chat is a private chat (flat-fallback gate). */
-    private pairedChatPrivate;
+    /** Cached delivery boundary for the private owner chat or validation forum. */
+    private pairedChatPrivacy;
     /** Bot username from getMe, cached once at owner startup for group/forum command targeting. */
     private botUsername;
     /** Sessions whose agent loop is currently busy (drives the typing indicator). */
@@ -972,6 +1054,7 @@ export declare class TelegramNotificationDaemon {
     /** Map a lifecycle response/error to a user-facing message (G010 surfacing). */
     private formatLifecycleResponse;
     private callBotApi;
+    private validationTopicDestination;
     private readonly callBotApiClassified;
     private botApiWithOutcomeCollector;
     constructor(opts: TelegramDaemonOptions);
@@ -1005,6 +1088,12 @@ export declare class TelegramNotificationDaemon {
     private beginToolActivityShutdown;
     private dropSession;
     private deleteMessageRoutes;
+    revokeCallbackAliases(socketLease: {
+        session: SessionSocket;
+        token: number;
+        logicalSessionId: string;
+    }): void;
+    private reissuePendingAction;
     private static readonly THREADED_FRAMES;
     private topicNameFor;
     /**
@@ -1054,20 +1143,19 @@ export declare class TelegramNotificationDaemon {
     private topicPastOrphanGrace;
     private observeOrphanedTopic;
     /** Best-effort delete of a session topic once its local notification endpoint shuts down. */
-    private deleteTopic;
+    /** Join all close, compensation, orphan, and restart callers for one session. */
+    private archiveTopic;
     private persistTopics;
     loadTopics(): Promise<void>;
     /**
-     * Rehydrate durable adoption intents after restart, then reconcile: a
-     * non-expired sidecar whose target session already has a committed topic
-     * record is a stale leftover (commit succeeded but sidecar cleanup failed)
-     * and is removed safely without touching the user topic.
+     * Rehydrate durable adoption intents after restart. A sidecar whose topic
+     * already committed is stale evidence and can be removed without touching
+     * the retained user-created topic.
      */
     loadAdoptionIntents(): Promise<void>;
-    /** Periodic sweep of expired adoption-intent sidecars (files only; no Telegram API). */
     private startAdoptionSweepTimer;
     private stopAdoptionSweepTimer;
-    /** Retry crash-interrupted topic deletes; only a definite Telegram result clears the durable fence. */
+    /** Retry crash-interrupted topic archives only when the durable backoff permits it. */
     private reconcilePendingTopicDeletes;
     /** Download one Telegram file with the Bot API's 20 MiB ceiling and one end-to-end deadline. */
     private downloadTelegramFile;
@@ -1122,13 +1210,13 @@ export declare class TelegramNotificationDaemon {
      */
     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.
+     * Resolve and cache the outbound delivery boundary. The validation forum is
+     * explicit and topic-only; all inbound and flat paths remain private-only.
      */
+    private validationMode;
     private resolvePairedChatPrivacy;
-    /** Keep existing outbound callers fail-closed for indeterminate privacy. */
+    private pairedChatAllowsTopics;
+    /** Keep all flat delivery and inbound control paths private-only. */
     private pairedChatIsPrivate;
     /** Tell the user once (per daemon run) how to enable Threaded Mode. */
     private notifyThreadedFallback;

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

@@ -51,16 +51,25 @@ export interface CallbackRoute {
     sessionId: string;
     actionId: string;
     answer: TelegramCallbackAnswer;
+    /** Durable audit metadata only; never sufficient to route a callback after restart. */
+    chatId?: string;
+    messageId?: number;
+    ownerId?: string;
+    generation?: number;
 }
 export interface SerializedAliasTable {
-    version: 1;
+    version: 1 | 2;
     next: number;
     routes: Record<string, CallbackRoute>;
 }
 export interface AliasTable {
+    allocate(isReserved?: (alias: string) => boolean): string;
+    activate(alias: string, route: CallbackRoute): boolean;
     put(route: CallbackRoute): string;
     get(alias: string): CallbackRoute | undefined;
+    update(alias: string, patch: Partial<CallbackRoute>): boolean;
     delete(alias: string): boolean;
+    clear(): void;
     serialize(): SerializedAliasTable;
     load(json: unknown): void;
     entries(): Array<[string, CallbackRoute]>;