@gajae-code/coding-agent 0.13.2 → 0.14.0

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

@@ -1,41 +1,17 @@
 /**
- * Durable, non-routable sidecar store for "adopt a user-created Telegram forum
- * topic into a preallocated session" intents.
+ * Durable provider-local reservations for Telegram topic adoption.
  *
- * 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.
+ * A reservation is keyed by the stable provider request identity, never by a
+ * preallocated Broker SessionId.  Broker allocates the SessionId; the daemon
+ * CAS-binds that opaque value only after the lifecycle service returns it.
+ * This store owns only presentation mappings and pending-topic authorization.
  */
 import type { SessionCreateTarget } from "./index";
-/** Persisted document version. */
-export declare const TELEGRAM_ADOPTION_INTENT_VERSION = 1;
+export declare const TELEGRAM_ADOPTION_INTENT_VERSION = 2;
 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;
@@ -55,43 +31,34 @@ export interface AdoptionIntentFileHandle {
     sync(): Promise<void>;
     close(): Promise<void>;
 }
-/** What gets persisted per intent. No tokens, no digests. */
+/** Persisted before create; `sessionId` is added only by bindSession. */
 export interface TelegramAdoptionIntent {
-    intendedSessionId: string;
-    topicId: number;
-    chatId: string;
-    target: TelegramAdoptionTarget;
-    createdAt: number;
-    expiresAt: number;
+    readonly providerRequestKey: string;
+    readonly topicId: number;
+    readonly chatId: string;
+    readonly target: TelegramAdoptionTarget;
+    readonly createdAt: number;
+    readonly expiresAt: number;
+    readonly sessionId?: string;
 }
-/** Durable authorization that a topic was observed through forum_topic_created. */
 export interface TelegramPendingTopic {
-    topicId: number;
-    chatId: string;
-    createdAt: number;
-    expiresAt: number;
+    readonly topicId: number;
+    readonly chatId: string;
+    readonly createdAt: number;
+    readonly 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 adoptionIntentFilePath(agentDir: string, providerRequestKey: string): string;
 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;
+    providerRequestKey: 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: {
@@ -100,66 +67,25 @@ export declare class TelegramAdoptionIntentStore {
         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. */
+    byProviderRequestKey(providerRequestKey: string): TelegramAdoptionIntent | undefined;
+    /** Only a post-create CAS binding makes a reservation visible by SessionId. */
+    bySession(sessionId: string): TelegramAdoptionIntent | undefined;
     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.
-     */
+    /** Synchronous fail-closed topic claim keyed by provider request identity. */
+    tryClaim(topicId: number, providerRequestKey: string): boolean;
+    releaseClaim(topicId: number, providerRequestKey: string): void;
     put(intent: TelegramAdoptionIntent): Promise<void>;
-    /** Persist authorization for a topic observed through forum_topic_created. */
+    /** CAS-bind the Broker-returned opaque SessionId exactly once. */
+    bindSession(providerRequestKey: string, sessionId: string): Promise<boolean>;
     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>;
+    readIntent(providerRequestKey: 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. */
+    remove(providerRequestKey: string): Promise<void>;
     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-daemon-cli.d.ts

@@ -1,5 +1,6 @@
 import type { Settings } from "../../config/settings";
 import { type NotificationSettingsReader } from "./config";
+import { type NotificationDebrisSweepReport } from "./notification-service";
 import { type DaemonState, type TelegramDaemonOptions } from "./telegram-daemon";
 type TelegramDaemonRunner = {
     run(): Promise<void>;
@@ -16,6 +17,7 @@ export interface RunDaemonInternalDeps {
     DaemonImpl?: TelegramDaemonConstructor;
     processPid?: number;
     pidAlive?: (pid: number) => boolean;
+    pidIncarnation?: (pid: number) => string | undefined;
     /** Clock used by the ownership-progress watchdog; defaults to `Date.now`. */
     now?: () => number;
     /** Timer pair backing the ownership-progress watchdog; defaults to globals. */
@@ -25,6 +27,14 @@ export interface RunDaemonInternalDeps {
     readDaemonState?: (settings: Settings) => Promise<DaemonState | undefined>;
     /** Loads the verified machine-local identity; injectable so daemon tests do not touch the host. */
     loadInstallationHostId?: () => Promise<string>;
+    /**
+     * Startup hygiene sweep over the notifications dir; injectable so tests can
+     * prove it is fired, is never awaited by startup, and that a rejection is
+     * logged instead of failing the daemon.
+     */
+    sweepNotificationDebris?: (input: {
+        dir: string;
+    }) => Promise<NotificationDebrisSweepReport>;
 }
 export declare function createLightweightDaemonSettings(input: {
     agentDir: string;

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

@@ -4,6 +4,12 @@
  */
 /** Protocol version the daemon advertises in its ClientHello. */
 export declare const NOTIFICATION_PROTOCOL_VERSION = 3;
+/** Telegram transport generation; independent from SDK lifecycle protocol changes. */
+export declare const TELEGRAM_TRANSPORT_GENERATION = 1;
+/** Notification event schema version; payload compatibility is versioned separately. */
+export declare const NOTIFICATION_EVENT_SCHEMA_VERSION = 1;
+/** SDK Router/lifecycle protocol negotiated by core, not by Telegram transport. */
+export declare const SDK_LIFECYCLE_ROUTER_PROTOCOL_VERSION = 1;
 /**
  * Guarded behavior-inventory version for the current daemon build. Bump this
  * on every guarded daemon-behavior change independent of the wire version; it
@@ -91,25 +97,262 @@ export declare const NOTIFICATION_PROTOCOL_VERSION = 3;
  * later session from creating a topic or replaying notifications. Generation
  * 58 preserves that invariant during durable-fence load promotion and restores
  * the exact grace deadline when a failed archive publication rolls back.
- * Generation 59 publishes the owner's attached OPEN-socket count in the
- * heartbeat sidecar so `gjc notify health` can report a live daemon that is
- * attached to no registered endpoint (#4128). Generation 60 contains transient
- * heartbeat-sidecar publication failures: a Windows EPERM/EACCES/EBUSY on the
- * sidecar rename is retried bounded under the ownership-lock fence and an
- * exhausted publication keeps the daemon alive as `publish_failed` instead of
- * escaping as an uncaught exception, while only a proven state/lock mismatch
- * (`not_owner`) stops the owner (#4200). Generation 61 keeps authenticated
- * same-session transports attached while predecessor archival converges and
- * settles non-forum close responses. Generation 62 rejects replay-gap
- * authority claims that do not match the requested cursor, answer bounds,
- * and retained replay suffix.
- * Generation 63 contains transient steady-heartbeat state and ownership-lock
- * read failures and cleans every staged sidecar before retrying (#4200).
+ * Generation 59 moves lifecycle and attachment authority into SDK core,
+ * removes provider root scanning and direct endpoint credentials, and rebuilds
+ * Telegram presentation bindings from SessionRouter attachments. Generation 60
+ * persists Router publication receipts, awaits inbound attachment dispatch,
+ * restores actor-scoped create throttling, and exact-unlinks ownership locks.
+ * Generation 61 durably claims provider publication identities before dispatch
+ * and retains ambiguous claims across restart to prevent duplicate effects.
+ * Generation 62 confirms receipts only from accepted provider outcomes,
+ * retains queued/fallback claims, and quarantines legacy v1 confirmations.
+ * Generation 63 applies the same deferred confirmation boundary while draining
+ * replay-state and live-held frames during attachment recovery.
+ * Generation 64 additionally defers stale-lease frames, requires authoritative
+ * model message IDs, and retains claims when continuation admission fails.
+ * Generation 65 treats malformed or unknown Bot API responses as ambiguous
+ * rather than accepting them without a provider receipt.
+ * Generation 66 propagates publication identity through selected and ephemeral
+ * direct effects, retries definite pre-send route failures, and aggregates the
+ * worst continuation disposition before confirmation.
+ * Generation 67 quarantines oversized persisted receipt maps and retains claims
+ * for pending-topic frames evicted before provider delivery.
+ * Generation 68 releases claimed BTW publications when shutdown prevents dispatch.
+ * Generation 69 settles selected acknowledgements and queued BTW publications
+ * only from positive Telegram message receipts.
+ * Generation 70 separates queued claims from provider-attempt ambiguity so
+ * pre-send work remains replayable after daemon restart.
+ * Generation 71 preserves queued state through cooldown/shutdown suppression and
+ * never converts replay-suppressed ambiguity into delivered confirmation.
+ * Generation 72 keeps invalid selected publications queued and mirrors attempted
+ * BTW rejection outcomes across duplicate publication identities.
+ * Generation 73 reports queued publication disposition to SessionRouter so
+ * same-process reconnect retains the unadvanced replay cursor.
+ * Generation 74 serializes each Router frame until its durable publication state
+ * becomes attempted or delivered, preserving sequence order without cursor gaps.
+ * Generation 75 routes every direct effect through the suppression-aware adapter
+ * and gives each publication queue item a non-coalescing identity.
+ * Generation 76 adds durable terminal rejection for invalid direct frames and
+ * confirms accepted non-OK BTW status publications before returning.
+ * Generation 77 bounds terminal rejection receipts alongside delivered receipts.
+ * Generation 78 retries stale direct authority before dispatch and terminalizes
+ * intentionally superseded queued live publications.
+ * Generation 79 preserves rejected state through outer/replay confirmation and
+ * settles publication-level continuation and retry barriers.
+ * Generation 80 terminalizes every no-dispatch queue branch and revalidates
+ * terminal publication state after cooldown waits.
+ * Generation 81 terminalizes flat, pending, and stopped-pool no-dispatch work
+ * and removes the raw Router Broker mutation tunnel.
+ * Generation 82 terminalizes expired and out-of-band queue removals, defers BTW
+ * completion across all chunks, and classifies definitive direct rejections.
+ * Generation 83 terminalizes pending frames discarded during topic flush.
+ * Generation 84 closes policy/archive/selected direct waiter cleanup and routes
+ * pre-identity threaded output through flat delivery instead of a blocked queue.
+ * Generation 85 removes the obsolete pending-frame admission path entirely.
+ * Generation 86 terminalizes queued selected acknowledgements during shutdown.
+ * Generation 87 routes every run-loop exit through the publication stop boundary.
+ * Generation 88 rejects all queued publications before Router shutdown, disables
+ * implicit provider retries, and durably joins receipt persistence.
+ * Generation 89 rejects all pool submissions once a stop is requested.
+ * Generation 90 terminalizes replay-queued publications before Router shutdown.
+ * Generation 91 routes selected-ack retries through the stop admission fence.
+ * Generation 92 rejects Router waiters when terminal receipt persistence fails.
+ * Generation 93 aborts provider delivery immediately and resets failed settlement
+ * resolvers before same-daemon replay.
+ * Generation 94 wires the immediate delivery abort into every publication call.
+ * Generation 95 propagates selected-ack receipt persistence failure to Router.
+ * Generation 96 routes rich-draft delivery through the publication abort boundary.
+ * Generation 97 bounds strict tool terminalization with shutdown abort authority.
+ * Generation 98 applies delivery abort authority to every supervised Bot API call.
+ * Generation 99 propagates generic terminal receipt persistence failure to Router.
+ * Generation 100 centralizes terminal receipt failure propagation in state transitions.
+ * Generation 101 isolates batch terminal failures and replays rejected rollback.
+ * Generation 102 isolates expired and superseded pre-batch receipt failures.
+ * Generation 103 fences and joins Router reconciliation during stop.
+ * Generation 104 prevents Router timer installation after concurrent stop.
+ * Generation 105 revokes attachment capabilities immediately when Router stop begins.
+ * Generation 106 isolates every Router client close attempt during shutdown.
+ * Generation 107 joins reconnect replay within Router pending shutdown work.
+ * Generation 108 interrupts replay requests immediately when Router stop begins.
+ * Generation 109 isolates stale attachment client and provider cleanup failures.
+ * Generation 110 installs replay stop handling before starting the request.
+ * Generation 111 isolates replacement client and provider cleanup failures.
+ * Generation 112 preserves provider handoff while isolating replacement close failure.
+ * Generation 113 removes old provider authority when replacement races stop.
+ * Generation 114 removes successor provider authority when handoff races stop.
+ * Generation 115 removes provider authority for every attachment disposed by stop.
+ * Generation 116 creates publication waiters only after claim admission succeeds.
+ * Generation 117 exposes tentative claims to concurrent teardown and aborts revoked admission.
+ * Generation 118 prevents failed concurrent rejection from reviving tentative claims.
+ * Generation 119 bounds Router stop and preserves rejected failed continuations.
+ * Generation 120 awaits provisional rejection durability before replay suppression.
+ * Generation 121 fences bounded-stop continuations from later Router runs.
+ * Generation 122 fences every nested replay suppression on rejection durability.
+ * Generation 123 scopes stale Router errors to their originating run epoch.
+ * Generation 124 detaches restart tails and restores rejected rollback as replayable.
+ * Generation 125 prevents stale run cleanup from deleting restarted attachments.
+ * Generation 126 fences stale callback bookkeeping and distinguishes definitive rejection.
+ * Generation 127 keeps malformed accepted selected sends transport-ambiguous.
+ * Generation 128 bounds Discord provider work before Router revocation.
+ * Generation 129 bounds every Discord REST operation across retries.
+ * Generation 130 invalidates Discord effect lease renewal when shutdown drain expires.
+ * Generation 131 invalidates Discord effect leases at the journal mutation boundary.
+ * Generation 132 invalidates Discord create-intent leases at drain expiry.
+ * Generation 133 serializes Discord creator invalidation with in-flight admission.
+ * Generation 134 durably restores replay after definitive provider rejection.
+ * Generation 135 revokes attachments whose provider publication hook rejects.
+ * Generation 136 keeps provider attachment publication provisional until recovery succeeds.
+ * Generation 137 fences stale reconciliation, frame tails, and identity-less replay rejection.
+ * Generation 138 starts provider handshakes only after Router publication.
+ * Generation 139 privatizes raw SDK clients and removes the Python transport package.
+ * Generation 140 retires failed handshakes and holds provisional frames until publication.
+ * Generation 141 awaits the provider handshake before Router replay to prevent retained-event deadlock.
+ * Generation 142 migrates live adoption reservations and applies create throttling to topic adoption.
+ * Generation 143 preserves topic presentation continuity across exact Router endpoint replacement.
+ * Generation 144 revalidates endpoint authority before exact publication-time requests.
+ * Generation 145 distinguishes transport reconnect from a changed same-generation endpoint successor.
+ * Generation 146 revokes token-zero and callback leases before endpoint replacement while retaining topic presentation.
+ * Generation 147 uses a restart-stable opaque Router endpoint-incarnation identity.
+ * Generation 148 classifies reconnect-time endpoint successors before attachment retirement.
+ * Generation 149 serializes successor attachment behind predecessor provider retirement.
+ * Generation 150 version-fences attaches already in flight when retirement begins.
+ * Generation 151 preserves provider continuity for endpoint-before-index replacement cleanup.
+ * Generation 152 contains a thrown steady heartbeat renewal in the run loop
+ * (a transient EPERM/EACCES/EBUSY on the state or ownership-lock read) the
+ * same way instead of terminating the daemon (#4200).
+ * Generation 153 restricts Telegram forum-topic ownership, replay, routing, callbacks,
+ * and lease renewal to identities with coordinator or lifecycle provenance.
+ * Generation 154 archives private-chat topics through deleteForumTopic, settles
+ * TOPIC_ID_INVALID as definitive, and drains durable archive retries periodically.
+ * Generation 155 unifies the duplicated durable terminal-retention write path
+ * (bus and SDK-only host runtimes) into a single `boundTerminalRetentionState`
+ * helper in `session/terminal-abort.ts` (#4329).
+ * Generation 156 derives Telegram session eligibility from configuration
+ * (Telegram configured and effectively enabled) instead of coordinator or
+ * lifecycle launch provenance, and stops consulting a session's self-declared
+ * eligibility for topic admission: threaded mode always uses threads. Before
+ * this, every ordinary interactive session declared itself ineligible, the
+ * daemon rejected its identity header, no topic was created, and nothing was
+ * delivered while attachments still looked healthy.
+ * Generation 157 adds orphan-topic reconciliation: FORUM_TOPIC_NOT_FOUND is
+ * settled as definitive, and the unsupported-method fallback closes when
+ * deleteForumTopic is unavailable on older Bot API deployments.
+ * Generation 158 updates terminal-abort notification admission and cleanup semantics.
+ * Generation 159 fences the Windows process-incarnation authority: the native
+ * binding fallback no longer spawns powershell.exe when it cannot bind a pid,
+ * so older daemons that may still flash a console window during liveness polling
+ * are fenced off (#4362).
+ * Generation 160 introduces provider-local Telegram subscriptions, detached
+ * cleanup, stable topic bindings, and explicit archive authority. Older daemons
+ * retain attachment-level lifecycle coupling and may not serve this contract.
+ * Generation 161 completes that authority split: archive reasons and cleanup
+ * receipts are durable, topic recovery no longer reconstructs SDK endpoint
+ * authority, and replay generation cannot mutate lifecycle authority.
+ * Generation 162 removes chat-daemon ownership from the session-open critical
+ * path: the host acquires provider ownership only AFTER publishing its core
+ * endpoint, through a single-flight coordinator keyed to the full provider
+ * identity, and never awaits it on a lifecycle path. The daemon also sweeps
+ * inert notification-dir debris at startup. Older daemons assume ownership is
+ * proved before publication and do not perform that sweep. Generation 165
+ * preserves a bounded lean settlement window across autonomous continuations,
+ * so the Telegram terminal receipt cannot lose a prior user-request result.
+ * Generation 166 introduces complete owned process-group cleanup (killTree
+ * instead of root-only signalRoot), identity-fenced orphan-owner reconciliation
+ * in the daemon run loop, pre-poll stale-poller fencing, and fail-closed
+ * watchdog behavior when stable identity authority is unavailable (#4403).
+ * Generation 167 repairs the telegram daemon generation guard bootstrap so the
+ * generator's post-fix manifest check always byte-compares the regenerated disk
+ * manifest against the current tree, and auto-reaps pre-registry legacy stray
+ * Telegram daemons (#4533).
+ * Generation 168 adds per-update inbound acknowledgement authority and monotonic
+ * reaction settlement for Telegram notification delivery (#4528).
+ * Generation 169 delivers every ring-positioned session event live through the
+ * bounded, capability-gated directed subscriber leg used by replay.
  */
-export declare const DAEMON_GENERATION = 63;
+export declare const DAEMON_GENERATION = 169;
 /**
- * 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.
+ * Serving-compatibility boundary for daemon lifecycle requests. Epoch 7
+ * requires durable publication receipts and acknowledged attachment dispatch,
+ * so epoch-6 daemons cannot serve across the delivery-safety cutover. Epoch 8
+ * requires the durable claimed/confirmed publication receipt format. Epoch 9
+ * requires accepted-only confirmation and legacy receipt quarantine. Epoch 10
+ * requires replay admission to retain deferred publication claims. Epoch 11
+ * requires strict direct receipts and fail-closed continuation admission. Epoch 12
+ * requires malformed provider responses to remain unconfirmed claims.
+ * Epoch 13 requires complete direct-effect identity and pre-send retry semantics.
+ * Epoch 14 requires bounded receipt loading and fail-closed pending eviction.
+ * Epoch 15 requires BTW shutdown to preserve Router replay authority.
+ * Epoch 16 requires accepted-only settlement for special provider queues.
+ * Epoch 17 requires durable queued/attempted/confirmed publication states.
+ * Epoch 18 requires suppression-aware attempt transitions and replay confirmation.
+ * Epoch 19 requires direct invalid/rejected outcomes to retain exact receipt state.
+ * Epoch 20 requires Router cursor advancement to follow settled publication state.
+ * Epoch 21 requires ordered Router settlement waiters for queued publications.
+ * Epoch 22 requires unified dispatch guards and non-coalescing publication work.
+ * Epoch 23 requires explicit rejected state and terminal direct settlement.
+ * Epoch 24 requires bounded terminal rejection retention.
+ * Epoch 25 requires stale-dispatch retry and superseded publication settlement.
+ * Epoch 26 requires terminal-state exclusivity and complete publication barriers.
+ * Epoch 27 requires no-dispatch terminalization and post-wait revalidation.
+ * Epoch 28 requires terminal flat/pending admission and list-only Broker routing.
+ * Epoch 29 requires complete removal terminalization and direct rejection state.
+ * Epoch 30 requires terminal settlement for pending-frame flush discards.
+ * Epoch 31 requires complete direct waiter closure and pre-identity delivery.
+ * Epoch 32 removes identity-gated pending publication admission.
+ * Epoch 33 requires selected-ack shutdown removal to settle publication state.
+ * Epoch 34 requires control-file exits to terminalize queued publications first.
+ * Epoch 35 requires complete publication teardown and single-attempt dispatch.
+ * Epoch 36 closes the retry-after-stop queue race.
+ * Epoch 37 closes replay-queue settlement during stop.
+ * Epoch 38 closes selected-ack retry-after-stop settlement.
+ * Epoch 39 propagates terminal receipt persistence failure to Router shutdown.
+ * Epoch 40 closes hanging-delivery shutdown and transient persistence replay.
+ * Epoch 41 closes ordinary publication hangs during shutdown.
+ * Epoch 42 closes selected terminal receipt persistence settlement.
+ * Epoch 43 closes rich-draft transport hangs during shutdown.
+ * Epoch 44 closes terminal tool transport hangs during shutdown.
+ * Epoch 45 closes raw topic and callback transport hangs during shutdown.
+ * Epoch 46 closes timer-finalized publication persistence settlement.
+ * Epoch 47 covers every delivered/rejected persistence rollback path.
+ * Epoch 48 preserves unrelated batch settlement and rejected replayability.
+ * Epoch 49 preserves every removed inventory settlement after individual failure.
+ * Epoch 50 prevents attachment resurrection after provider shutdown.
+ * Epoch 51 fully fences Router startup and reconciliation after stop.
+ * Epoch 52 prevents provider dispatch throughout the Router stop window.
+ * Epoch 53 prevents one transport close timeout from skipping later cleanup.
+ * Epoch 54 prevents Router return before replay callbacks complete.
+ * Epoch 55 closes pending reconnect replay without hanging Router shutdown.
+ * Epoch 56 guarantees provider authority cleanup despite transport close failure.
+ * Epoch 57 prevents orphaned replay request rejection during stop.
+ * Epoch 58 guarantees old authority cleanup before replacement attachment.
+ * Epoch 59 drops old provider authority only when replacement creation fails.
+ * Epoch 60 closes provider cleanup for replacement creation interrupted by stop.
+ * Epoch 61 closes provider cleanup after published replacement handoff.
+ * Epoch 62 covers stop during recovered-frame and replay awaits.
+ * Epoch 63 prevents capacity and claim-persistence waiter leaks.
+ * Epoch 64 closes attachment replacement during claim persistence.
+ * Epoch 65 closes dual persistence failure during tentative claim teardown.
+ * Epoch 66 prevents callback shutdown deadlock and false ambiguous rejection.
+ * Epoch 67 closes concurrent claim/rejection persistence cursor concession.
+ * Epoch 68 prevents pre-stop reconciliation authority after same-instance restart.
+ * Epoch 69 prevents provisional nested replay cursor concession.
+ * Epoch 70 prevents stale run failures from stopping a restarted Router.
+ * Epoch 71 restores bounded Router restart and rejected publication replay.
+ * Epoch 72 identity-fences provider cleanup after bounded restart.
+ * Epoch 73 preserves successor retry state and ambiguous dispatched cleanup.
+ * Epoch 74 prevents replay after accepted responses lacking message identity.
+ * Epoch 75 prevents hung Discord REST work from blocking daemon shutdown.
+ * Epoch 76 cancels hung Discord REST before active-work drain expires.
+ * Epoch 77 fences late Discord effect commits after Router revocation.
+ * Epoch 78 atomically marks timed-out Discord work uncertain before Router revocation.
+ * Epoch 79 releases timed-out Discord creator ownership for successor recovery.
+ * Epoch 80 terminalizes leases admitted after shutdown invalidator snapshot.
+ * Epoch 81 preserves definitive provider rejection across persistence failure and restart.
+ * Epoch 82 fails closed before exposing provider attachments after cleanup recovery failure.
+ * Epoch 83 binds provider commands to the exact opaque attachment identity.
+ * Epoch 84 prohibits provider lifecycle-equivalent controls and detaches replacement work.
+ * Epoch 85 removes direct relay attachment and prohibits lifecycle controls on every adapter.
+ * Epoch 86 removes public discovery/client exports and retires cross-process raw transports.
+ * Epoch 87 preserves accepted Telegram delivery ambiguity and advances poisoned poll cursors.
  */
-export declare const SERVING_EPOCH = 5;
+export declare const SERVING_EPOCH = 87;

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

@@ -0,0 +1,125 @@
+import type { TelegramDaemonFs } from "./telegram-daemon";
+import { type TelegramOwnerMarker } from "./telegram-daemon-owner-registry";
+/**
+ * A stable, identity-bound reference to a process opened BEFORE the incarnation
+ * check and used for ALL subsequent operations. This closes the PID-reuse race:
+ * the native handle pins the exact process incarnation, so a reused PID cannot
+ * be signaled through a stale reference — the OS will reject the operation.
+ *
+ * `signalRoot` signals only the pinned root process (root-only).
+ * `terminateTree` signals the process AND its descendants / process group.
+ */
+export interface TelegramOrphanProcessRef {
+    /** The incarnation of the process this reference was opened against. */
+    incarnation: string;
+    /**
+     * Gracefully terminate this process and its entire descendant tree / process
+     * group (TERM → wait → KILL escalation). Returns true if the process (and
+     * its children) exited within the bounded wait.
+     */
+    terminateTree(signal?: NodeJS.Signals): boolean;
+}
+/**
+ * A pinned reference that can additionally prove the process's kernel-derived
+ * launch arguments. Used only by the legacy-stray sweep: candidate PIDs come
+ * from an untrusted enumeration, but every authorization fact (incarnation,
+ * argv) is read from this pinned reference, never from the enumeration.
+ */
+export interface TelegramStrayProcessRef extends TelegramOrphanProcessRef {
+    /** Launch arguments reported by the kernel for the pinned incarnation. */
+    args(): string[];
+}
+export interface TelegramOrphanReapDeps {
+    fs?: TelegramDaemonFs;
+    now?: () => number;
+    pidAlive: (pid: number) => boolean;
+    pidIncarnation: (pid: number) => string | undefined;
+    /**
+     * Opens a stable process reference bound to the exact process incarnation at
+     * open time. The reference must be opened BEFORE the incarnation check so
+     * that termination operates on the same identity that was proven stale.
+     */
+    processReference?: (pid: number) => TelegramOrphanProcessRef | undefined;
+    platform?: NodeJS.Platform;
+    /**
+     * Enumerates candidate PIDs for the legacy-stray sweep. The list is
+     * untrusted discovery input only; authorization derives exclusively from
+     * the pinned {@link TelegramStrayProcessRef}. Defaults to a bounded POSIX
+     * `ps` listing; returns nothing on Windows or enumeration failure.
+     */
+    listCandidatePids?: () => Promise<number[]>;
+    /** Opens a pinned argv-capable reference for stray verification. */
+    strayReference?: (pid: number) => TelegramStrayProcessRef | undefined;
+    /**
+     * First-sighting ledger for stray confirmation, keyed by
+     * `pid|incarnation` with the first-seen timestamp. Injectable for tests;
+     * defaults to a process-lifetime module ledger.
+     */
+    straySightings?: Map<string, number>;
+}
+export interface TelegramOrphanCandidate {
+    marker: TelegramOwnerMarker;
+    executablePath?: string;
+    argv?: string[];
+}
+export type OrphanReapDecision = {
+    kind: "reaped";
+    pid: number;
+    acquisitionId: string;
+} | {
+    kind: "refused";
+    pid: number;
+    acquisitionId: string;
+    reason: string;
+} | {
+    kind: "inert";
+    pid: number;
+    acquisitionId: string;
+};
+export interface TelegramOrphanRecoveryReceipt {
+    version: 1;
+    agentDir: string;
+    currentOwnerId: string;
+    currentAcquisitionId: string;
+    currentPid: number;
+    createdAt: number;
+    candidates: number;
+    terminated: number;
+    refused: number;
+    inert: number;
+    reasons: Record<string, number>;
+}
+/**
+ * Exact invocation-signature test for a legacy Telegram daemon owner:
+ * a `notify daemon-internal` subcommand bound to exactly this agent dir.
+ * This is deliberately an exact-token match on kernel-reported argv from a
+ * pinned reference — never a substring similarity over an untrusted dump.
+ */
+export declare function isLegacyStrayDaemonArgs(args: readonly string[], agentDir: string): boolean;
+/**
+ * Bounded stale-owner sweep. Authorizes termination only from product-owned
+ * marker registry bound to exact agentDir digest + acquisitionId + pid + incarnation.
+ * Never authorizes from bare /proc cmdline similarity; markers are the trust anchor.
+ *
+ * Safety invariants:
+ * 1. The stable process reference is opened BEFORE the incarnation check and
+ *    used for termination, so a reused PID cannot be signaled through a stale
+ *    handle.
+ * 2. Process-group termination (not root-only signal) ensures reparented
+ *    descendants of an orphaned daemon are also cleaned up.
+ * 3. Zombies and dead processes are classified inert without any signaling.
+ * 4. The sweep is bounded: at most MAX_REAP_CANDIDATES markers are inspected.
+ */
+export declare function reapTelegramDaemonOrphans(input: {
+    agentDir: string;
+    currentOwnerId: string;
+    currentAcquisitionId: string;
+    currentPid: number;
+    currentIncarnation: string;
+    fsImpl: TelegramDaemonFs;
+    deps: TelegramOrphanReapDeps;
+}): Promise<{
+    decisions: OrphanReapDecision[];
+    receipt: TelegramOrphanRecoveryReceipt;
+}>;
+export declare function writeTelegramOrphanRecoveryReceipt(fsImpl: TelegramDaemonFs, agentDir: string, receipt: TelegramOrphanRecoveryReceipt): Promise<void>;