@gajae-code/coding-agent 0.16.4 → 0.16.6

package/dist/types/gjc-runtime/ultragoal-succession.d.ts

@@ -0,0 +1,251 @@
+import { type RepositoryBinding } from "./repository-binding";
+import { type UltragoalCommandResult, type UltragoalGjcGoalMode, type UltragoalGoalStatus, type UltragoalPlan } from "./ultragoal-runtime";
+export declare const ULTRAGOAL_SUCCESSION_OPERATION_SCHEMA: "gjc.ultragoal_succession_operation.v1";
+export declare const ULTRAGOAL_SUCCESSION_OFFER_SCHEMA: "gjc.ultragoal_succession_offer.v1";
+export declare const ULTRAGOAL_SUCCESSION_FENCE_SCHEMA: "gjc.ultragoal_succession_fence.v1";
+export declare const ULTRAGOAL_SUCCESSION_ADOPTION_SCHEMA: "gjc.ultragoal_succession_adoption.v1";
+export declare const ULTRAGOAL_SUCCESSION_CLAIM_SCHEMA: "gjc.ultragoal_succession_claim.v1";
+export declare const SUCCESSION_ADOPTED_EVENT: "succession_adopted";
+export type UltragoalSuccessionErrorCode = "source_plan_missing" | "source_not_quiescent" | "invalid_selection" | "unsafe_target" | "authorization_required" | "divergent_operation" | "goal_handed_off" | "adoption_unpublished" | "publication_conflict" | "published_plan_missing" | "fence_missing" | "fence_mismatch" | "source_changed" | "offer_untrusted" | "offer_path_escape" | "target_mismatch" | "target_occupied" | "duplicate_adoption";
+export declare class UltragoalSuccessionError extends Error {
+    readonly code: UltragoalSuccessionErrorCode;
+    constructor(code: UltragoalSuccessionErrorCode, message: string);
+}
+export interface UltragoalSuccessionArtifactDigests {
+    briefSha256: string;
+    goalsSha256: string;
+    ledgerSha256: string;
+}
+export interface UltragoalSuccessionCarriedGoal {
+    sourceGoalId: string;
+    title: string;
+    /** The source objective, verbatim. Never a summary. */
+    objective: string;
+    /** Historical provenance only; never a receipt. */
+    sourceStatusAtOffer: UltragoalGoalStatus;
+    unresolvedObligations: string[];
+    /**
+     * Source dependency groups this goal belonged to, carried as an obligation
+     * with explicit id mapping. The group's *metadata* (batch hashes, receipts)
+     * is deliberately not carried — that would be inherited validation authority.
+     * What is carried is the requirement that these goals be validated together.
+     */
+    dependencyGroups: UltragoalSuccessionDependencyGroup[];
+}
+export type UltragoalSuccessionDependencyGroupKind = "validation-batch" | "review-blocker";
+export interface UltragoalSuccessionDependencyGroup {
+    kind: UltragoalSuccessionDependencyGroupKind;
+    groupId: string;
+    memberSourceGoalIds: string[];
+    /** For validation batches: the source goal that closed the batch. */
+    finalSourceGoalId?: string;
+}
+/**
+ * Per-selected-goal snapshot of exactly what was offered.
+ *
+ * Admission compares *this*, not whole-file equality. The fence deliberately
+ * leaves unselected goals schedulable, so ordinary source progress moves
+ * `goals.json`/`ledger.jsonl` bytes; requiring whole-file equality would
+ * permanently strand the selected work through drift that never touched it
+ * (issue #5353 review item 3). Whole-file digests remain recorded as provenance
+ * and any observed drift is written into the adoption record.
+ */
+export interface UltragoalSuccessionSelectionSnapshot {
+    /** The brief carries global constraints, so it must not change. */
+    briefSha256: string;
+    goals: Array<{
+        sourceGoalId: string;
+        recordSha256: string;
+        obligationsSha256: string;
+    }>;
+    snapshotSha256: string;
+}
+export interface UltragoalSuccessionOffer {
+    schema: typeof ULTRAGOAL_SUCCESSION_OFFER_SCHEMA;
+    operationId: string;
+    createdAt: string;
+    source: {
+        sessionId: string;
+        repository: RepositoryBinding;
+        /** Whole-file digests at offer time. Provenance; not the admission test. */
+        artifacts: UltragoalSuccessionArtifactDigests;
+        /** The authoritative admission test for "did the offered work change". */
+        selectionSnapshot: UltragoalSuccessionSelectionSnapshot;
+        gjcGoalMode: UltragoalGjcGoalMode;
+    };
+    target: {
+        repository: RepositoryBinding;
+    };
+    selection: {
+        goalIds: string[];
+    };
+    carryover: {
+        /** The source brief, verbatim. */
+        brief: string;
+        goals: UltragoalSuccessionCarriedGoal[];
+    };
+    authorization: {
+        statement: string;
+        authorizedBy: string;
+    };
+    provenanceNotice: string;
+}
+export interface UltragoalSuccessionFence {
+    schema: typeof ULTRAGOAL_SUCCESSION_FENCE_SCHEMA;
+    operationId: string;
+    createdAt: string;
+    sourceSessionId: string;
+    sourceRepository: RepositoryBinding;
+    targetRepository: RepositoryBinding;
+    selectedGoalIds: string[];
+    sourceArtifacts: UltragoalSuccessionArtifactDigests;
+    offerPath: string;
+    offerSha256: string;
+}
+export interface UltragoalSuccessionGoalMapping {
+    sourceGoalId: string;
+    targetGoalId: string;
+}
+export interface UltragoalSuccessionAdoption {
+    schema: typeof ULTRAGOAL_SUCCESSION_ADOPTION_SCHEMA;
+    operationId: string;
+    status: "pending" | "published";
+    claimedAt: string;
+    publishedAt?: string;
+    targetSessionId: string;
+    targetRepository: RepositoryBinding;
+    source: {
+        sessionId: string;
+        repository: RepositoryBinding;
+        artifacts: UltragoalSuccessionArtifactDigests;
+        /** Whole-file digests observed at adoption; may differ from the offer. */
+        artifactsAtAdoption: UltragoalSuccessionArtifactDigests;
+        /** Whole-file drift on goals the offer did not select, recorded honestly. */
+        unselectedDrift: string[];
+        verifiedAt: string;
+    };
+    goalMap: UltragoalSuccessionGoalMapping[];
+    /**
+     * Content digest of the plan this operation is entitled to publish, recorded
+     * before publication. A pending replay may only proceed when the target plan
+     * is absent or matches this exactly; anything else is someone else's work.
+     */
+    expectedPlanDigest: string;
+    /** Pinned so the published plan is a deterministic function of the claim. */
+    plannedAt: string;
+    offerPath: string;
+    offerSha256: string;
+    fencePath: string;
+    claimPath: string;
+    authorization: {
+        statement: string;
+        authorizedBy: string;
+    };
+    provenanceNotice: string;
+}
+/**
+ * Repository-wide adoption claim.
+ *
+ * The session-scoped adoption record cannot be the exclusion primitive: two
+ * simultaneous sessions in one repository each create their own file and both
+ * win. This claim is a single O_EXCL file per operation for the whole
+ * repository, so exclusion is atomic rather than scan-then-write.
+ */
+export interface UltragoalSuccessionRepositoryClaim {
+    schema: typeof ULTRAGOAL_SUCCESSION_CLAIM_SCHEMA;
+    operationId: string;
+    targetSessionId: string;
+    targetWorktreeRoot: string;
+    targetCommonDir: string | null;
+    claimedAt: string;
+}
+export declare function ultragoalSuccessionDir(cwd: string, sessionId: string): string;
+export declare function ultragoalSuccessionFencePath(cwd: string, sessionId: string): string;
+export declare function ultragoalSuccessionAdoptionPath(cwd: string, sessionId: string): string;
+export declare function ultragoalSuccessionOfferPath(cwd: string, sessionId: string, operationId: string): string;
+/**
+ * Repository-wide (deliberately NOT session-scoped) adoption claim.
+ *
+ * Session directories cannot express "this repository has already adopted this
+ * operation", so the exclusion primitive lives beside them under the shared
+ * ultragoal root that `getUltragoalPaths` already uses for session-less state.
+ */
+export declare function ultragoalSuccessionClaimPath(cwd: string, operationId: string): string;
+/** Read the durable outgoing ownership fence for a source session, if any. */
+export declare function readUltragoalSuccessionFence(cwd: string, sessionId: string): Promise<UltragoalSuccessionFence | null>;
+/** Read the durable adoption claim for a target session, if any. */
+export declare function readUltragoalSuccessionAdoption(cwd: string, sessionId: string): Promise<UltragoalSuccessionAdoption | null>;
+/**
+ * Source admission guard: a goal that has been handed off to a successor run is
+ * no longer this run's to schedule or checkpoint.
+ *
+ * Goals outside the fenced selection stay fully schedulable — the fence defines
+ * one owner per goal, not a freeze of the whole source run.
+ */
+export declare function assertUltragoalGoalNotFenced(cwd: string, sessionId: string | null | undefined, goalId: string): Promise<void>;
+/**
+ * Target admission guard: an adoption that has not finished publishing does not
+ * yet own anything.
+ *
+ * Publication writes `goals.json` before it marks the claim published, so a
+ * crash leaves a *visible plan with an unpublished claim*. A visible plan is not
+ * admission evidence — the claim is. Without this, the target executes goals
+ * whose adoption was never completed, and the run's own completion receipts
+ * would rest on a transaction that never committed.
+ *
+ * Callers must invoke this before any mutation so a refusal leaves `goals.json`
+ * and `ledger.jsonl` untouched.
+ */
+export declare function assertUltragoalAdoptionPublished(cwd: string, sessionId: string | null | undefined): Promise<void>;
+export interface UltragoalSuccessionOfferInput {
+    cwd: string;
+    sessionId?: string | null;
+    targetRepositoryPath: string;
+    goalIds: readonly string[];
+    authorization: string;
+    authorizedBy: string;
+}
+export interface UltragoalSuccessionOfferResult {
+    operationId: string;
+    offerPath: string;
+    fencePath: string;
+    offer: UltragoalSuccessionOffer;
+    /** True when an identical prior operation was reconciled instead of re-recorded. */
+    reconciled: boolean;
+}
+/**
+ * Record an explicit successor offer and fence the selected goals off from the
+ * source run. Writes nothing to the source brief, goals or ledger.
+ */
+export declare function offerUltragoalSuccession(input: UltragoalSuccessionOfferInput): Promise<UltragoalSuccessionOfferResult>;
+export interface UltragoalSuccessionAdoptInput {
+    cwd: string;
+    sessionId?: string | null;
+    offerPath: string;
+    gjcGoalMode?: UltragoalGjcGoalMode;
+}
+export interface UltragoalSuccessionAdoptResult {
+    operationId: string;
+    adoptionPath: string;
+    plan: UltragoalPlan;
+    goalMap: UltragoalSuccessionGoalMapping[];
+    reconciled: boolean;
+}
+/**
+ * Adopt an explicit successor offer into this repository/session.
+ *
+ * Fails closed on a forged or stale offer, a changed source, a missing source
+ * fence, an unnamed target, an occupied target, and any duplicate or divergent
+ * adoption anywhere in this repository. A retry reconciles the exact recorded
+ * operation or fails closed; it never resumes a different one.
+ */
+export declare function adoptUltragoalSuccession(input: UltragoalSuccessionAdoptInput): Promise<UltragoalSuccessionAdoptResult>;
+/**
+ * `gjc ultragoal succession <offer|adopt|status>`.
+ *
+ * Kept out of `RECONCILE_COMMANDS` on purpose: the reconcile pass appends a
+ * `reconcile_failed` ledger row on failure, which would move the very source
+ * digests this feature records. The target's workflow state and HUD reconcile on
+ * the next ordinary `gjc ultragoal status`.
+ */
+export declare function runUltragoalSuccessionCommand(args: readonly string[], cwd: string): Promise<UltragoalCommandResult>;

package/dist/types/modes/components/bash-execution.d.ts

@@ -15,6 +15,7 @@ export declare class BashExecutionComponent extends Container {
     appendOutput(chunk: string): void;
     setComplete(exitCode: number | undefined, cancelled: boolean, options?: {
         output?: string;
+        signal?: string;
         truncation?: TruncationMeta;
     }): void;
     render(width: number): string[];

package/dist/types/modes/components/execution-shared.d.ts

@@ -34,6 +34,7 @@ export declare function createCollapsedPreview(previewText: string, previewLines
 export declare function buildStatusFooter(opts: {
     status: ExecutionStatus;
     exitCode: number | undefined;
+    signal?: string;
     truncation: TruncationMeta | undefined;
     hiddenLineCount: number;
     /** Suppress the "… N more lines" hint (used when sixel passthrough renders the full output). */

package/dist/types/modes/interactive-mode.d.ts

@@ -198,6 +198,8 @@ export declare class InteractiveMode implements InteractiveModeContext {
     beginOAuthUrlForCopy(url: string): () => void;
     hasOAuthUrlForCopy(): boolean;
     copyOAuthUrl(): Promise<void>;
+    /** Clear the status display without settling the foreground run during maintenance/retry. */
+    clearLoadingAnimation(): void;
     syncActivityIndicator(): void;
     ensureLoadingAnimation(): void;
     stopLoadingAnimation(options?: ActivityIndicatorStopOptions): void;

package/dist/types/modes/types.d.ts

@@ -57,6 +57,11 @@ export type ActivityIndicatorStopOptions = Readonly<{
     /** The terminal event is authoritative even if the session's streaming flag has not settled yet. */
     foregroundSettled?: boolean;
 }>;
+export declare function clearInteractiveActivityIndicator(ctx: {
+    loadingAnimation?: Loader;
+    statusContainer?: PartialActivityStatusContainer;
+    clearLoadingAnimation?: () => void;
+}): void;
 export declare function stopInteractiveActivityIndicator(ctx: {
     loadingAnimation?: Loader;
     statusContainer?: PartialActivityStatusContainer;
@@ -190,6 +195,7 @@ export interface InteractiveModeContext {
     setWorkingMessage(message?: string): void;
     applyPendingWorkingMessage(): void;
     ensureLoadingAnimation(): void;
+    clearLoadingAnimation(): void;
     syncActivityIndicator(): void;
     suspendActivityIndicator(): () => void;
     stopLoadingAnimation(options?: ActivityIndicatorStopOptions): void;

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

@@ -1,7 +1,9 @@
 import { type ChildProcess } from "node:child_process";
 import type { FileHandle } from "node:fs/promises";
+import { type FileLockOptions } from "../../config/file-lock";
 import { type BrokerDiscovery } from "./discovery";
 import { type SdkInternalSpawnCommand } from "./runtime";
+export declare function isBrokerGenerationCompatible(discovery: BrokerDiscovery | null): boolean;
 export interface EnsureBrokerSettings {
     agentDir: string;
     heartbeatTtlMs?: number;
@@ -12,6 +14,27 @@ export interface EnsureBrokerSettings {
      */
     env?: NodeJS.ProcessEnv;
 }
+type SpawnLockOptions = Pick<FileLockOptions, "retries" | "retryDelayMs" | "signal">;
+declare function readBrokerDiscoveryBeforeDeadline(agentDir: string, heartbeatTtlMs: number | undefined, deadline: number): Promise<BrokerDiscovery | null>;
+/**
+ * Cross-process single-flight for the detached broker spawn (#5198).
+ *
+ * `ensureInFlight` only dedupes within one process. Every CLI invocation is
+ * its own process, so N concurrent invocations that all miss discovery each
+ * spawn a broker; the losers of the runtime's ownership lock then leave
+ * quarantine tombstones behind and the next start fails with
+ * `quarantine_collision`. The spawn itself must be exclusive across process
+ * death and PID reuse, so it uses the shared identity-bound file-lock protocol:
+ * complete owner metadata is published atomically, stale removal is bound to
+ * the exact directory generation, and ownership includes the OS incarnation.
+ */
+declare function acquireSpawnLock(agentDir: string, options?: SpawnLockOptions): Promise<() => Promise<void>>;
+/**
+ * Child-owned fence for the interval from bootstrap through discovery publication.
+ * The parent-held spawn lock prevents ordinary stampedes; this second fence keeps
+ * startup single-flight if that detached child's launcher dies and its lock is reclaimed.
+ */
+export declare function withBrokerStartupLock<T>(agentDir: string, operation: (deadline: number) => Promise<T>): Promise<T>;
 /**
  * Tail of the detached broker's stderr folded into a discovery failure.
  *
@@ -62,6 +85,12 @@ interface ReapTiming {
     killVerifyMs: number;
 }
 type BrokerOwnerIdentity = Pick<BrokerDiscovery, "ownerId" | "pid" | "incarnation">;
+/** Start client teardown, but never await it past the retirement operation's absolute deadline. */
+export declare function closeBrokerClientBeforeDeadline(client: {
+    close(): Promise<void>;
+}, deadline: number): Promise<void>;
+/** Reconcile an observed broker generation before entering a startup critical section. */
+export declare function reconcileBrokerGenerationForStartup(settings: EnsureBrokerSettings, deadline?: number): Promise<BrokerDiscovery | undefined>;
 /** Starts the detached broker entrypoint when discovery has no live owner. */
 export declare function ensureBroker(settings: EnsureBrokerSettings): Promise<BrokerDiscovery>;
 /** Starts one fresh fixture broker and returns its sole exact-child close lease. */
@@ -73,6 +102,9 @@ export declare function startFixtureBrokerWithLeaseForTest(settings: EnsureBroke
  */
 export declare function startFixtureBrokerCommandWithLeaseForTest(command: FixtureBrokerCommand): StartedFixtureBrokerCommand;
 /** Test hook: returns a stop handle for the detached broker this process spawned. */
+export declare const acquireSpawnLockForTest: typeof acquireSpawnLock;
+/** Test hook: proves discovery reads honor their enclosing absolute deadline. */
+export declare const readBrokerDiscoveryBeforeDeadlineForTest: typeof readBrokerDiscoveryBeforeDeadline;
 export declare function brokerOwnerForTest(agentDir: string): BrokerOwner | undefined;
 /** Test hook: verifies the complete broker owner identity used during stale retirement. */
 export declare function brokerOwnerIdentityMatchesForTest(left: BrokerOwnerIdentity | null, right: BrokerOwnerIdentity): boolean;

package/dist/types/sdk/broker/lifecycle-ledger.d.ts

@@ -78,7 +78,6 @@ export interface LifecycleLedgerEntry {
     unresolvedCleanupResponseDigest?: string;
     uncertainCleanupSessionId?: string;
     uncertainCleanupSessionIds?: string[];
-    uncertainCleanupAllSessions?: true;
     ts: number;
 }
 export type BeginResult = {

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

@@ -173,14 +173,20 @@ export declare function observeProcessForTest(pid: number, expectedIncarnation:
  * deliberately left untouched.
  */
 export declare function reapDeadLifecycleMarkers(root: string, limit?: number): Promise<number>;
+export declare function writeEffectMarker(root: string, id: string, marker: EffectMarker): Promise<void>;
 /** The child writes this only after its endpoint and semantic ready event are both live. */
 export declare function writeSessionLifecycleReady(root: string, id: string, effectMarker: string): Promise<void>;
 export interface LifecycleTranscriptEvidence {
     digest: string;
     identity: SessionLifecycleTranscriptIdentity;
 }
+type LifecycleFailureArtifact = EffectMarker & SdkStartupFailure & {
+    rollback: SdkStartupRollbackResult;
+    transcript?: LifecycleTranscriptEvidence;
+};
 /** Writes bounded startup diagnostics. The child stamps its own pid; the broker may stamp a proven child identity. */
 export declare function writeSessionLifecycleFailure(root: string, id: string, effectMarker: string, failure: SdkStartupFailure, rollback: SdkStartupRollbackResult, transcript?: LifecycleTranscriptEvidence, ownerIncarnation?: string, ownerPid?: number): Promise<void>;
+export declare function readSessionLifecycleFailure(root: string, id: string, expected: EffectMarker): Promise<LifecycleFailureArtifact | undefined>;
 export declare function readSessionLifecycleFailureForTest(root: string, id: string, expected: {
     pid: number;
     effectMarker: string;

package/dist/types/sdk/broker/startup-failure.d.ts

@@ -1,5 +1,5 @@
 export interface BrokerStartupFailureMarker {
-    version: 1;
+    version: 2;
     reason: string;
     exitCode: number | null;
     signal: string | null;
@@ -13,6 +13,8 @@ export interface BrokerStartupFailureMarker {
      * failure.
      */
     pid: number;
+    /** Kernel-derived identity for the exact process incarnation that wrote the marker. */
+    incarnation: string;
 }
 export declare function brokerStartupFailurePath(agentDir: string): string;
 /**
@@ -26,6 +28,7 @@ export declare function writeBrokerStartupFailureMarker(agentDir: string, failur
     exitCode: number | null;
     signal: string | null;
     pid: number;
+    incarnation?: string;
 }): Promise<void>;
 /** Reads a bounded startup-failure marker; `undefined` when absent or malformed. */
 export declare function readBrokerStartupFailureMarker(agentDir: string): Promise<BrokerStartupFailureMarker | undefined>;

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

@@ -105,6 +105,8 @@ export type ChatDaemonAction = "stop" | "reload";
  * Discord generation 72 / Slack generation 75 serialize same-generation
  * successor attachment admission behind predecessor provider retirement, so a
  * pre-upgrade owner cannot retain the queue race fixed by #5120.
+ * Slack generation 80 persists and fences the inbound SDK dispatch boundary so
+ * crashes, recovery, and attachment retirement cannot replay ambiguous work.
  */
 export declare const CHAT_DAEMON_GENERATIONS: Readonly<Record<ChatDaemonKind, number>>;
 export declare function chatDaemonGeneration(kind: ChatDaemonKind): number;

package/dist/types/sdk/bus/chat-effect-journal.d.ts

@@ -2,7 +2,7 @@ import { type ConversationRecord, type ConversationStoreFs } from "./conversatio
 export declare const CHAT_EFFECT_JOURNAL_VERSION = 1;
 export declare const MAX_TERMINAL_CHAT_EFFECTS = 128;
 export declare function chatEffectJournalPath(agentDir: string, transport: "discord" | "slack"): string;
-export type ChatEffectState = "pending" | "leased" | "accepted" | "uncertain" | "terminal";
+export type ChatEffectState = "pending" | "leased" | "dispatching" | "accepted" | "uncertain" | "terminal";
 /** Provider receipts are identifiers/status only. Never put request or response bodies here. */
 export interface ChatEffectReceipt {
     provider?: string;
@@ -77,9 +77,24 @@ export declare class ChatEffectJournal {
     enqueueAndClaim<TPayload>(input: EnqueueChatEffect<TPayload>, owner: string, leaseMs: number): Promise<ChatEffect<TPayload> | undefined>;
     claim<TPayload = unknown>(id: string, owner: string, leaseMs: number): Promise<ChatEffect<TPayload> | undefined>;
     renew<TPayload = unknown>(id: string, lease: ChatEffectLease, leaseMs: number): Promise<ChatEffect<TPayload> | undefined>;
+    markDispatching<TPayload = unknown>(id: string, lease: ChatEffectLease): Promise<ChatEffect<TPayload> | undefined>;
+    ownsDispatching(id: string, lease: ChatEffectLease): Promise<boolean>;
+    /** Hold the durable dispatching lease until the synchronous SDK prewire boundary. */
+    dispatchWithLeaseFence<R>(id: string, lease: ChatEffectLease, dispatch: () => Promise<R>, dispatched: Promise<void>): Promise<{
+        value: R;
+    } | undefined>;
+    recoverDispatchingAsUncertain<TPayload = unknown>(id: string, options?: {
+        onlyIfExpired?: boolean;
+    }): Promise<ChatEffect<TPayload> | undefined>;
     /** Persists provider progress without releasing the owner/epoch fence. */
     recordReceipt<TPayload = unknown>(id: string, lease: ChatEffectLease, receipt: ChatEffectReceipt): Promise<ChatEffect<TPayload> | undefined>;
-    record<TPayload = unknown>(id: string, lease: ChatEffectLease, state: Exclude<ChatEffectState, "pending" | "leased">, receipt?: ChatEffectReceipt): Promise<ChatEffect<TPayload> | undefined>;
+    record<TPayload = unknown>(id: string, lease: ChatEffectLease, state: "accepted" | "uncertain" | "terminal", receipt?: ChatEffectReceipt): Promise<ChatEffect<TPayload> | undefined>;
     /** Irreversibly rejects an effect whose mapping never accepted its authority. */
     terminalize(id: string, receipt: ChatEffectReceipt, lease?: ChatEffectLease): Promise<ChatEffect | undefined>;
+    /**
+     * Terminalize only a decided effect. The uncertainty check and state change
+     * share one store transaction so a concurrent sender cannot publish an
+     * ambiguity tombstone between a caller's read and stale cleanup.
+     */
+    terminalizeDecided(id: string, receipt: ChatEffectReceipt, lease?: ChatEffectLease): Promise<ChatEffect | undefined>;
 }

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

@@ -88,4 +88,15 @@ export declare class ConversationStore<T extends ConversationRecord> {
      * other writer uses.
      */
     transactWithSnapshot(key: string, update: (current: T | undefined, conversations: Readonly<Record<string, T>>) => T | undefined | Promise<T | undefined>): Promise<T | undefined>;
+    /**
+     * Hold the cross-process mapping lock until a prepared dispatch either reaches
+     * its synchronous wire boundary or fails before sending. The result may remain
+     * pending after the lock is released while the remote response is awaited.
+     */
+    dispatchWithSnapshotFence<R>(key: string, prepare: (current: T | undefined, conversations: Readonly<Record<string, T>>) => {
+        result: Promise<R>;
+        dispatched: Promise<void>;
+    } | undefined): Promise<{
+        value: R;
+    } | undefined>;
 }

package/dist/types/sdk/bus/lifecycle-commands.d.ts

@@ -1,5 +1,11 @@
 import type { SessionCloseTarget, SessionCreateTarget, SessionLifecycleResponse, SessionResumeTarget } from "./index";
 export type LifecycleCommandVerb = "session_create" | "session_close" | "session_resume";
+export interface LifecycleCommandContext {
+    chatType?: string;
+    botUsername?: string;
+    /** Session durably associated with the Telegram topic containing the command. */
+    threadSessionId?: string;
+}
 /** A parsed, validated lifecycle command (transport identity added by caller). */
 export type ParsedLifecycleCommand = {
     kind: "create";
@@ -27,10 +33,7 @@ export type ParsedLifecycleCommand = {
 /** True when the text begins with any /session_* token, regardless of addressability. */
 export declare function isLifecycleCommandLikeText(text: string | undefined): boolean;
 /** True when the text begins an addressable /session_* command (cheap pre-gate). */
-export declare function isLifecycleCommandText(text: string | undefined, ctx?: {
-    chatType?: string;
-    botUsername?: string;
-}): boolean;
+export declare function isLifecycleCommandText(text: string | undefined, ctx?: LifecycleCommandContext): boolean;
 /**
  * Parse a paired-chat message into a lifecycle command. Returns `none` for
  * non-lifecycle text, `usage`/`reject` for malformed input (no side effect), or
@@ -39,10 +42,7 @@ export declare function isLifecycleCommandText(text: string | undefined, ctx?: {
  * The caller MUST have already enforced paired-chat authorization; this function
  * performs grammar + target validation only.
  */
-export declare function parseLifecycleCommand(text: string | undefined, ctx?: {
-    chatType?: string;
-    botUsername?: string;
-}): ParsedLifecycleCommand;
+export declare function parseLifecycleCommand(text: string | undefined, ctx?: LifecycleCommandContext): ParsedLifecycleCommand;
 /** The canonical usage text (exported for the daemon's help replies). */
 export declare function lifecycleUsage(): string;
 /**

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

@@ -30,7 +30,7 @@ export interface SlackNotificationDaemonOptions {
     resolveAttachment: (sessionId: string) => Promise<SessionAttachment | null>;
     /** Exact Router proof for adopting an existing root. */
     resolveBindingAuthority?: (sessionId: string) => Promise<SlackBindingAuthority | undefined>;
-    onCommand?: (sessionId: string, content: string, attachment: SessionAttachment, idempotencyKey: string) => Promise<boolean>;
+    onCommand?: (sessionId: string, content: string, attachment: SessionAttachment, idempotencyKey: string, beforeDispatch: () => void, dispatchFence: <T>(dispatch: () => Promise<T>) => Promise<T>) => Promise<boolean>;
 }
 /**
  * Slack Socket Mode notification daemon. Accepted inbound SDK effects are

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

@@ -206,6 +206,14 @@ export declare class TopicRegistry {
     private rebuildInboundRoutes;
     /** Resolve the owning session for a topic id (for fail-closed inbound routing). */
     sessionForTopic(topicId: string): string | undefined;
+    /**
+     * Resolve a durable topic association for explicit lifecycle controls.
+     *
+     * Unlike inbound message routing, this may return an inactive session so a
+     * user can resume it from its old topic. Ambiguous, malformed, cross-chat,
+     * and quarantined records fail closed.
+     */
+    sessionForLifecycleTopic(topicId: string, chatId: string): string | undefined;
     /** All session ids with a persisted topic record. */
     sessionIds(): string[];
     /** The existing topic record for a session, if any. */

package/dist/types/sdk/client/client.d.ts

@@ -12,6 +12,10 @@ export declare class SdkClientError extends Error {
     readonly reconnect?: SdkReconnectExhaustedDetails;
     constructor(code: SdkErrorCode, message: string, details?: unknown, reconnect?: SdkReconnectExhaustedDetails);
 }
+/** A prepared transport operation failed before any wire handoff. */
+export declare class SdkPreparedDispatchError extends SdkClientError {
+    constructor(error: SdkClientError);
+}
 export type SdkReconnectTerminationReason = "attempts_exhausted" | "deadline" | "cancelled";
 /**
  * Reconnect-cycle termination diagnostics. `attemptsConsumed` counts retry slots,
@@ -66,6 +70,8 @@ export interface SdkRequestOptions {
      * alter that settlement.
      */
     onDispatch?: SdkDispatchHandler;
+    /** Internal prepared-dispatch mode: fail pre-send instead of reconnecting. */
+    connectedOnly?: boolean;
 }
 export type SdkFrame = Record<string, unknown>;
 /**

package/dist/types/sdk/host/host.d.ts

@@ -117,6 +117,8 @@ export declare class SessionSdkHost {
      * publishing a second readiness signal.
      */
     activate(expectedGeneration?: number): Promise<SessionActivationOutcome>;
-    stop(): Promise<"stopped" | "already">;
+    stop(options?: {
+        allowLockContention?: boolean;
+    }): Promise<"stopped" | "already">;
     registerWithBroker(writer: BrokerIndexWriter): Promise<void>;
 }

package/dist/types/sdk/host/session-runtime.d.ts

@@ -189,7 +189,7 @@ export declare class SessionSdkSessionRuntime {
      * asked for. Delivery failure is ignored: a disconnected consumer must never
      * disturb the turn producing the content.
      */
-    sendFrameTo(connectionIds: Iterable<string>, frame: SdkFrame): void;
+    sendFrameTo(connectionId: string, frame: SdkFrame): void;
     publish(frame: SdkFrame): void;
     startHost(): Promise<"started" | "already">;
     startTransport(): Promise<{
@@ -198,7 +198,9 @@ export declare class SessionSdkSessionRuntime {
     start(): Promise<{
         url: string;
     }>;
-    stop(): Promise<void>;
+    stop(options?: {
+        allowLockContention?: boolean;
+    }): Promise<void>;
     registerWithBroker(writer: BrokerIndexWriter): Promise<void>;
 }
 /** Narrow extension-facing factory for the SDK-only session path. */

package/dist/types/sdk/lifecycle/service.d.ts

@@ -137,6 +137,7 @@ export interface SessionLifecycleSessionResult {
     readonly sessionId: string;
     readonly cwd?: string;
     readonly endpointGeneration?: number;
+    readonly endpointIncarnation?: string;
     readonly reused?: boolean;
     readonly note?: string;
 }

package/dist/types/sdk/router/session-router.d.ts

@@ -2,6 +2,7 @@ import { type SessionIndex } from "../broker/session-index";
 import { type SdkDispatchContext, type SdkDispatchHandler } from "../client/client";
 import { type ActivatedPreparedSession } from "../session-activation";
 export interface SessionEndpointIdentity {
+    readonly dev: bigint;
     readonly mtimeMs: number;
     readonly mtimeNs: bigint;
     readonly ctimeNs: bigint;
@@ -32,7 +33,10 @@ export interface SessionAttachment {
     readonly connectionId?: string;
     readonly generation: number;
     isCurrent(): boolean;
-    send(frame: Record<string, unknown>): unknown;
+    send(frame: Record<string, unknown>, options?: {
+        beforeDispatch?: () => void;
+        dispatchFence?: (dispatch: () => Promise<void>) => Promise<void>;
+    }): unknown;
     /**
      * Idempotent provider-lease heartbeat send that skips the pre-send authority
      * reconcile (#4689).
@@ -106,6 +110,7 @@ export interface SessionRouterClient {
     connect?(): Promise<void>;
     request(frame: Record<string, unknown>, options?: {
         timeoutMs?: number;
+        connectedOnly?: boolean;
         /** Synchronous pre-send observer; a throw aborts the dispatch before the wire. */
         beforeDispatch?: (context: SdkDispatchContext) => void;
         /** Synchronous post-send boundary observer for transport-close-aware consumers. */
@@ -208,6 +213,7 @@ export declare class SessionRouter {
         timeoutMs?: number;
         beforeDispatch?: (context: SdkDispatchContext) => void;
         onDispatch?: SdkDispatchHandler;
+        dispatchFence?: (dispatch: () => Promise<Record<string, unknown>>) => Promise<Record<string, unknown>>;
     }): Promise<Record<string, unknown>>;
     /** Resolves the exact provider-neutral binding authority for operator adoption. */
     bindingAuthority(sessionId: string): Promise<{
@@ -224,5 +230,7 @@ export declare class SessionRouter {
     /** Activates a prepared session through one Router-owned, one-shot SDK client. */
     activatePreparedSession(sessionId: string): Promise<ActivatedPreparedSession>;
     /** Lists saved sessions through Router-owned Broker discovery without exposing credentials or mutation authority. */
-    listBrokerSessions(input: Record<string, unknown>, idempotencyKey: string): Promise<Record<string, unknown>>;
+    listBrokerSessions(input: Record<string, unknown>, idempotencyKey: string, options?: {
+        beforeDispatch?: (context: SdkDispatchContext) => void;
+    }, dispatchFence?: (dispatch: () => Promise<Record<string, unknown>>) => Promise<Record<string, unknown>>): Promise<Record<string, unknown>>;
 }