@gajae-code/coding-agent 0.11.3 → 0.11.5

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

@@ -1,3 +1,4 @@
+import type { WriteFileOptions } from "node:fs";
 import type { Settings } from "../../config/settings";
 /**
  * Strip secrets from a human-facing diagnostic string. Redacts the configured
@@ -21,7 +22,18 @@ export interface NotificationExactUnlinkResult {
     ok: boolean;
     code?: string;
     detachedPath?: string;
-}
+    /** A live publisher successor retained after an exact-unlink race. */
+    retainedSuccessorPath?: string;
+    /** An internal exchange placeholder whose verified cleanup failed. */
+    retainedPlaceholderPath?: string;
+    /** A cleanup entry whose identity could not be verified after a race. */
+    retainedUnknownPath?: string;
+}
+/** Read one regular file together with the identity required for exact removal. */
+export declare function readNotificationEndpointFile(file: string): Promise<NotificationEndpointFile>;
+/** Bump when the native exact-deletion identity contract changes. */
+export declare const NATIVE_PATH_IDENTITY_CONTRACT_VERSION = 1;
+export declare function exactUnlinkNotificationFile(file: string, identity: NotificationEndpointFileIdentity, quarantineName: string): NotificationExactUnlinkResult;
 /** Minimal filesystem surface the service needs; injectable for tests. */
 export interface NotificationServiceFs {
     readdir(dir: string): Promise<string[]>;
@@ -29,13 +41,10 @@ export interface NotificationServiceFs {
     readEndpointFile(file: string): Promise<NotificationEndpointFile>;
     exactUnlink(file: string, identity: NotificationEndpointFileIdentity): Promise<NotificationExactUnlinkResult>;
     unlink(file: string): Promise<void>;
-    /**
-     * Atomically create `file` with O_EXCL semantics: resolves `true` when this
-     * call created it, `false` when it already existed. Used to hold the daemon
-     * steal-mutex ({@link DaemonPaths.steal}) during owner-bound lock removal so
-     * recovery and a concurrent daemon takeover are mutually exclusive.
-     */
-    createExclusive(file: string): Promise<boolean>;
+    writeFile?(file: string, data: string, opts?: WriteFileOptions): Promise<void>;
+    stat?(file: string): Promise<{
+        mtimeMs: number;
+    }>;
 }
 /** Injectable dependencies shared across service operations. */
 export interface NotificationServiceDeps {
@@ -143,6 +152,12 @@ export interface NotificationRecoveryReport {
     endpointsKept: number;
     endpointsUnreadable: number;
     endpointsDetached?: string[];
+    /** Successor paths retained after an exact-unlink race, distinct from stale quarantines. */
+    endpointsRetainedSuccessors?: string[];
+    /** Internal exchange placeholders retained after verified cleanup failure. */
+    endpointsRetainedPlaceholders?: string[];
+    /** Cleanup entries retained with unverified or mismatching identity. */
+    endpointsRetainedUnknown?: string[];
     daemon: {
         action: DaemonRecoveryAction;
         detail: string;
@@ -155,6 +170,53 @@ export interface RecoveryOptions {
     stateRoot?: string;
     deps?: NotificationServiceDeps;
 }
+export interface DaemonTransitionLock {
+    pid: number;
+    incarnation: string;
+    createdAt: number;
+    /** Unique fencing generation for this particular transition acquisition. */
+    token: string;
+}
+type TransitionMarkerFs = {
+    readFile(file: string, encoding: "utf8"): Promise<string>;
+    writeFile?(file: string, data: string, opts?: WriteFileOptions): Promise<void>;
+    readEndpointFile?(file: string): Promise<NotificationEndpointFile>;
+    exactUnlink?(file: string, identity: NotificationEndpointFileIdentity): Promise<NotificationExactUnlinkResult>;
+};
+/** True only while the exact transition acquisition still occupies the marker path. */
+export declare function daemonTransitionLockIsHeld(input: {
+    fs: Pick<TransitionMarkerFs, "readFile" | "readEndpointFile">;
+    path: string;
+    lock: DaemonTransitionLock;
+}): Promise<boolean>;
+/** Removes only the caller's exact marker through the identity-bound detach primitive. */
+export declare function releaseDaemonTransitionLock(input: {
+    fs: TransitionMarkerFs;
+    path: string;
+    lock: DaemonTransitionLock;
+}): Promise<boolean>;
+/**
+ * Acquire the daemon lifecycle transition lock using durable owner metadata.
+ * The full marker is published in the single O_EXCL write which reserves it;
+ * canonical markers are detached only through their captured filesystem identity.
+ *
+ * Malformed and empty markers deliberately remain blocked regardless of age. They
+ * have no owner provenance, so reclaiming them could detach a generation-6 empty
+ * reservation while its paused legacy writer can still resume. Operators must
+ * manually clean up such legacy debris after confirming no legacy process remains.
+ */
+export declare function acquireDaemonTransitionLock(input: {
+    fs: TransitionMarkerFs;
+    path: string;
+    pid: number;
+    pidAlive: (pid: number) => boolean;
+    pidIncarnation: (pid: number) => string | undefined;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    retries?: number;
+    retryDelayMs?: number;
+    randomToken?: () => string;
+}): Promise<DaemonTransitionLock | undefined>;
 /**
  * Ownership-protected cleanup. Removes only DEAD-owner artifacts:
  * per-session endpoint files with positive proof of death (a stale tombstone or
@@ -168,3 +230,4 @@ export interface RecoveryOptions {
 export declare function recoverNotifications(opts: RecoveryOptions): Promise<NotificationRecoveryReport>;
 /** Render a recovery report as human-readable lines (no secrets). */
 export declare function formatNotificationRecoveryReport(report: NotificationRecoveryReport): string;
+export {};

package/dist/types/sdk/bus/session-control.d.ts

@@ -14,7 +14,7 @@ export interface BoundNotificationSession<Context extends NotificationSessionCon
     unbind(): void;
 }
 export type NotificationEndpointStartResult = "started" | "already" | "disabled" | "failed";
-export type TelegramDaemonPreflightResult = "ready" | "blocked_identity";
+export type TelegramDaemonPreflightResult = "ready" | "blocked_identity" | "failed";
 /**
  * The endpoint implementation is deliberately injected. The controller owns
  * policy and session-local state while the extension continues to own its
@@ -29,6 +29,10 @@ export interface NotificationSessionRuntime<Context extends NotificationSessionC
      * emit a frame. `blocked_identity` is fail-closed and starts nothing.
      */
     ensureTelegramDaemon?(binding: BoundNotificationSession<Context>): Promise<TelegramDaemonPreflightResult>;
+    /** Refresh mutable delivery policy from the same configuration snapshot used for reconciliation. */
+    refreshPolicy?(binding: BoundNotificationSession<Context>, policy: NotificationRuntimePolicy): void;
+    /** Enables delivery only after the controller has committed a stable policy. */
+    activate?(binding: BoundNotificationSession<Context>): void;
 }
 export interface NotificationSessionStatus {
     eligible: boolean;
@@ -41,6 +45,12 @@ export interface NotificationSessionReconcileResult {
     outcome: NotificationEndpointStartResult | "stopped";
     status: NotificationSessionStatus;
 }
+export interface NotificationRuntimePolicy {
+    redact: boolean;
+    verbosity: NotificationConfig["verbosity"];
+    stream: boolean;
+    mode: "provisional" | "committed";
+}
 export interface NotificationSessionControllerOptions {
     /** Gate A result, resolved once by the SDK from the canonical host predicate. */
     eligible: boolean;
@@ -49,13 +59,6 @@ export interface NotificationSessionControllerOptions {
     /** Kept as a reference so test and embedding hosts can supply their own environment. */
     env?: NodeJS.ProcessEnv;
 }
-/**
- * Shared owner of notification session policy.
- *
- * Gate A is captured at creation. Gate B is evaluated for each session
- * operation with `isSessionNotificationsEnabled`. Gate C verifies complete
- * Telegram ownership before a generic endpoint is allowed to start.
- */
 export declare class NotificationSessionController {
     #private;
     constructor(options: NotificationSessionControllerOptions);

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

@@ -30,6 +30,11 @@ export declare function createLightweightDaemonSettings(input: {
 }): LightweightDaemonSettings;
 export declare function loadLightweightDaemonSettings(agentDir: string): Promise<LightweightDaemonSettings>;
 export declare function ownerPidFromOwnerId(ownerId: string): number | undefined;
+/** Creates owner-fenced daemon control hooks for the CLI lifecycle boundary. */
+export declare function createDaemonControlHooks(settings: Settings): {
+    shouldStop: (owner: string) => Promise<boolean>;
+    clear: (owner: string) => Promise<void>;
+};
 export declare function runDaemonSmoke(opts?: {
     agentDir?: string;
 }): Promise<void>;

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

@@ -11,7 +11,10 @@ export declare const NOTIFICATION_PROTOCOL_VERSION = 3;
  * freshly-upgraded host must still recognize an older, still-live daemon that
  * predates capability-gated frame enforcement and trigger a reload. Bump this
  * on every daemon-behavior change independent of the wire version.
- * The current development baseline already includes #2299's generation 4;
- * this behavior change therefore advances the operational generation to 5.
+ * The current development baseline already includes #2299's generation 4,
+ * incarnation fencing in generation 5, owner-lock authority in generation 6,
+ * identity-atomic transition markers in generation 7, stable signaling plus
+ * tri-state foreign-owner provenance in generation 8, and retained managed
+ * filesystem authority changes in generation 9.
  */
-export declare const DAEMON_GENERATION = 5;
+export declare const DAEMON_GENERATION = 9;

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

@@ -22,11 +22,18 @@ export declare function telegramControlRequestPath(agentDir: string): string;
 export declare function readTelegramControlRequest(settings: Settings, fsImpl?: TelegramDaemonFs): Promise<TelegramDaemonControlRequest | undefined>;
 export declare function writeTelegramControlRequest(settings: Settings, request: TelegramDaemonControlRequest, fsImpl?: TelegramDaemonFs): Promise<void>;
 export declare function clearTelegramControlRequest(settings: Settings, requestId?: string, fsImpl?: TelegramDaemonFs): Promise<void>;
+export interface DaemonProcessReference {
+    incarnation: string;
+    signalRoot(signal: NodeJS.Signals): void;
+}
 export interface TelegramDaemonControlDeps {
     fs?: TelegramDaemonFs;
     now?: () => number;
     pidAlive?: (pid: number) => boolean;
-    sendSignal?: (pid: number, signal: NodeJS.Signals) => void;
+    processReference?: (pid: number) => DaemonProcessReference | undefined;
+    pidIncarnation?: (pid: number) => string | undefined;
+    /** Test seam for platform-specific default stable-process authority. */
+    platform?: NodeJS.Platform;
     spawn?: TelegramDaemonDeps["spawn"];
     execPath?: string;
     /**
@@ -40,20 +47,30 @@ export interface TelegramDaemonControlDeps {
     randomId?: () => string;
     sleep?: (ms: number) => Promise<void>;
     waitStepMs?: number;
+    /** Bounded startup-readiness timeout; injectable for deterministic controller tests. */
+    readinessTimeoutMs?: number;
 }
+export type TelegramGenerationReloadResult = {
+    outcome: "ready";
+    operation: DaemonOperationResult;
+} | {
+    outcome: "failed";
+    operation: DaemonOperationResult;
+};
 export declare class TelegramDaemonController implements BuiltInDaemonController {
     private readonly settings;
     private readonly deps;
     readonly kind: "telegram";
     private readonly fsImpl;
-    private readonly now;
     private readonly pidAlive;
-    private readonly sendSignal;
+    private readonly now;
+    private readonly processReference;
     private readonly waitStepMs;
     constructor(settings: Settings, deps?: TelegramDaemonControlDeps);
     private runtimeInfo;
     status(): Promise<DaemonStatus>;
     private spawnDeps;
+    private spawnAndWait;
     private sleep;
     /**
      * Wait until the captured pid is dead. Ownership-file movement is NOT treated
@@ -61,10 +78,12 @@ export declare class TelegramDaemonController implements BuiltInDaemonController
      * which is what the no-409 invariant requires before spawning a fresh poller.
      */
     private waitForPidDeath;
+    private signalCapturedOwner;
     private result;
     reload(opts?: DaemonOperationOptions): Promise<DaemonOperationResult>;
+    reloadForGenerationUpgrade(opts?: DaemonOperationOptions): Promise<TelegramGenerationReloadResult>;
     stop(opts?: DaemonOperationOptions): Promise<DaemonOperationResult>;
     private stopOrReload;
-    /** Clear our own control request unless a newer owner-scoped request replaced it. */
+    /** Clear only our exact control request; a successor request must survive. */
     private clearOwnRequest;
 }

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

@@ -2,6 +2,8 @@ import * as fs from "node:fs";
 import type { Settings } from "../../config/settings";
 import type { DaemonRuntimeInfo } from "../../daemon/control-types";
 import { HEARTBEAT_TTL_MS } from "./daemon-paths";
+import { type DaemonTransitionLock, type NotificationEndpointFile, type NotificationEndpointFileIdentity, type NotificationExactUnlinkResult } from "./notification-service";
+import { type DaemonProcessReference } from "./telegram-daemon-control";
 export { DAEMON_GENERATION, NOTIFICATION_PROTOCOL_VERSION } from "./telegram-daemon-contract";
 import { type ControlServerLike, type LifecycleControlServerFactory } from "./lifecycle-control-runtime";
 import type { OrchestratorDeps } from "./lifecycle-orchestrator";
@@ -10,9 +12,16 @@ import { type AliasTable, type CallbackRoute } from "./telegram-reference";
 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";
+export type TelegramDaemonOwnershipPhase = "provisional" | "ready" | "retired";
 export interface DaemonState {
     pid: number;
+    /** OS process-start provenance; mandatory for PID-authorized ownership actions. */
+    incarnation: string;
     ownerId: string;
+    /** Unique, durable identity for one ownership acquisition. */
+    acquisitionId?: string;
+    /** A provisional owner is physical-live but MUST NOT be attached as ready. */
+    ownershipPhase?: TelegramDaemonOwnershipPhase;
     tokenFingerprint: string;
     chatId: string;
     startedAt: number;
@@ -26,10 +35,8 @@ export interface DaemonState {
     version: 1;
     /**
      * Operational daemon generation of the process that owns the lock, distinct
-     * from the persisted state-schema {@link DaemonState.version}. It records the
-     * wire generation ({@link DAEMON_GENERATION}) the owning daemon speaks so a
-     * freshly-upgraded host can detect — and reload — a still-live pre-upgrade
-     * daemon whose schema version is unchanged. Absent on pre-generation state.
+     * from both the persisted state-schema {@link DaemonState.version} and the
+     * notification wire protocol version. Absent on pre-generation state.
      */
     generation?: number;
     stoppedAt?: number;
@@ -45,8 +52,14 @@ export interface TelegramDaemonFs {
     }>;
     readdir(path: string): Promise<string[]>;
     chmod(path: string, mode: number): Promise<void>;
+    stat?(path: string): Promise<{
+        mtimeMs: number;
+    }>;
+    readEndpointFile?(path: string): Promise<NotificationEndpointFile>;
+    exactUnlink?(path: string, identity: NotificationEndpointFileIdentity): Promise<NotificationExactUnlinkResult>;
 }
 export interface SpawnResult {
+    pid?: number;
     unref?: () => void;
 }
 export interface TelegramDaemonDeps {
@@ -54,6 +67,10 @@ export interface TelegramDaemonDeps {
     now?: () => number;
     pid?: number;
     pidAlive?: (pid: number) => boolean;
+    /** Opens an identity-stable process authority for destructive lifecycle operations. */
+    processReference?: (pid: number) => DaemonProcessReference | undefined;
+    /** Returns immutable process-start provenance, or undefined when unsupported. */
+    pidIncarnation?: (pid: number) => string | undefined;
     spawn?: (command: string, args: string[], opts: {
         detached: boolean;
         stdio: "ignore";
@@ -71,6 +88,8 @@ export interface TelegramDaemonDeps {
     sendSignal?: (pid: number, signal: NodeJS.Signals) => void;
     sleep?: (ms: number) => Promise<void>;
     waitStepMs?: number;
+    /** Bounded startup-readiness timeout; injectable for deterministic handoff tests. */
+    readinessTimeoutMs?: number;
 }
 export declare const HEARTBEAT_INTERVAL_MS = 5000;
 export { HEARTBEAT_TTL_MS };
@@ -104,6 +123,53 @@ export declare function startDaemonLifecycleControl(input: {
     auditRedactionKey: Uint8Array;
     env?: NodeJS.ProcessEnv;
 }): OrchestratorDeps;
+export declare function tryCreateOwnershipLock(fsImpl: TelegramDaemonFs, file: string, initialization: OwnershipLockMetadata): Promise<boolean>;
+type OwnershipLockMetadata = {
+    pid: number;
+    incarnation: string;
+    ownerId?: string;
+    acquisitionId?: string;
+    startedAt: number;
+};
+type LegacyOwnershipLockMetadata = {
+    pid: number;
+    incarnation?: string;
+    startedAt: number;
+};
+type OwnershipLockRead = {
+    kind: "missing";
+} | {
+    kind: "malformed";
+    raw: string;
+    mtimeMs?: number;
+} | {
+    kind: "legacy";
+    metadata: LegacyOwnershipLockMetadata;
+} | {
+    kind: "valid";
+    metadata: OwnershipLockMetadata;
+};
+/** Read lock provenance without treating a corrupt legacy artifact as a filesystem failure. */
+export declare function readOwnershipLock(fsImpl: TelegramDaemonFs, file: string): Promise<OwnershipLockRead>;
+/**
+ * A live initializer lock only proves that a concurrent publisher is active.
+ * It never proves a ready daemon: legacy or unavailable provenance remains
+ * blocked, while a canonical mismatch proves PID reuse and can be reclaimed
+ * under the transition lock.
+ */
+export declare function liveOwnershipLockDecision(input: {
+    lock: OwnershipLockRead;
+    pidAlive: (pid: number) => boolean;
+    pidIncarnation: (pid: number) => string | undefined;
+}): {
+    acquired: false;
+    attached: false;
+    blocked: true;
+} | {
+    acquired: false;
+    attached: false;
+    provisional: true;
+} | undefined;
 export declare function registerNotificationRoot(input: {
     settings: Settings;
     cwd: string;
@@ -121,12 +187,39 @@ export declare function unregisterNotificationRoot(input: {
     sessionId: string;
     fs?: TelegramDaemonFs;
 }): Promise<UnregisterNotificationRootResult>;
+export declare function hasSafeDaemonStateShape(state: unknown): state is DaemonState;
+/** True for a physically live owner with this configuration, including legacy generations. */
+export declare function isPhysicalMatchingOwner(input: {
+    state: DaemonState | undefined;
+    tokenFingerprint: string;
+    chatId: string;
+    pidAlive: (pid: number) => boolean;
+    pidIncarnation?: (pid: number) => string | undefined;
+}): boolean;
+/** True only for a signalable legacy owner or this generation's ready bound child. */
+export declare function isSignalableMatchingOwner(input: {
+    state: DaemonState | undefined;
+    tokenFingerprint: string;
+    chatId: string;
+    pidAlive: (pid: number) => boolean;
+    pidIncarnation?: (pid: number) => string | undefined;
+}): boolean;
 export declare function isFreshLiveOwner(input: {
     state: DaemonState | undefined;
     now: number;
     tokenFingerprint: string;
     chatId: string;
     pidAlive: (pid: number) => boolean;
+    pidIncarnation?: (pid: number) => string | undefined;
+}): boolean;
+/** True only when a physically live matching owner can serve this build's daemon lifecycle contract. */
+export declare function isCurrentCompatibleOwner(input: {
+    state: DaemonState | undefined;
+    now: number;
+    tokenFingerprint: string;
+    chatId: string;
+    pidAlive: (pid: number) => boolean;
+    pidIncarnation?: (pid: number) => string | undefined;
 }): boolean;
 export declare function acquireDaemonOwnership(input: {
     settings: Settings;
@@ -137,6 +230,7 @@ export declare function acquireDaemonOwnership(input: {
     now?: () => number;
     pid?: number;
     pidAlive?: (pid: number) => boolean;
+    pidIncarnation?: (pid: number) => string | undefined;
     randomId?: () => string;
     /** Permit one Windows source launcher PID to daemon PID handoff. */
     allowPidRebind?: boolean;
@@ -145,32 +239,100 @@ export declare function acquireDaemonOwnership(input: {
 }): Promise<{
     acquired: boolean;
     ownerId?: string;
+    acquisitionId?: string;
     attached?: boolean;
     blocked?: boolean;
+    provisional?: boolean;
     reason?: "identity_mismatch";
     reloadRequired?: boolean;
 }>;
 export declare function renewDaemonHeartbeat(input: {
     settings: Settings;
     ownerId: string;
-    /** Bind a daemon heartbeat to the Telegram identity that acquired the lock. */
+    acquisitionId?: string;
+    tokenFingerprint?: string;
+    chatId?: string;
+    fs?: TelegramDaemonFs;
+    now?: () => number;
+    pid?: number;
+    generation?: number;
+    pidIncarnation?: (pid: number) => string | undefined;
+    sleep?: (ms: number) => Promise<void>;
+    stealRetries?: number;
+    stealRetryDelayMs?: number;
+}): Promise<boolean>;
+/** Acquire the lifecycle transition lock with bounded retry for bind/retire races. */
+export declare function acquireTransitionLock(input: {
+    fs: TelegramDaemonFs;
+    path: string;
+    pidAlive?: (pid: number) => boolean;
+    pidIncarnation?: (pid: number) => string | undefined;
+    sleep?: (ms: number) => Promise<void>;
+    retries?: number;
+    retryDelayMs?: number;
+}): Promise<DaemonTransitionLock | undefined>;
+/** Retire only the unchanged provisional acquisition after bounded readiness fails. */
+export declare function retireProvisionalDaemonOwnership(input: {
+    settings: Settings;
+    ownerId: string;
+    acquisitionId?: string;
+    pidIncarnation?: (pid: number) => string | undefined;
+    pidAlive?: (pid: number) => boolean;
+    /** Detached child PID, when the launcher successfully reported it. */
+    pid: number;
+    /** PID which created the provisional reservation before the child was bound. */
+    launcherPid?: number;
+    fs?: TelegramDaemonFs;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    stealRetries?: number;
+    stealRetryDelayMs?: number;
+    /** Only no-child confirmation may retire a ready-like launcher publication. */
+    allowReadyWithoutChildPid?: boolean;
+}): Promise<boolean>;
+/** Wait for a matching current-generation daemon to publish a ready state. */
+export declare function waitForTelegramDaemonReady(input: {
+    settings: Settings;
+    ownerId?: string;
+    acquisitionId?: string;
+    pid?: number;
+    excludedPid?: number;
     tokenFingerprint: string;
     chatId: string;
-    /** Require the current daemon PID after the launcher-to-daemon PID rebind. */
-    pid: number;
     fs?: TelegramDaemonFs;
     now?: () => number;
+    pidAlive?: (pid: number) => boolean;
+    pidIncarnation?: (pid: number) => string | undefined;
+    sleep?: (ms: number) => Promise<void>;
+    waitStepMs?: number;
+    timeoutMs?: number;
 }): Promise<boolean>;
-export declare function releaseDaemonOwnership(input: {
+/** Confirm the provisional owner or retire only its unchanged acquisition. */
+export declare function confirmTelegramDaemonSpawn(input: {
     settings: Settings;
-    ownerId: string;
-    /** Bind release to the Telegram identity that acquired the lock. */
+    spawned: TelegramSpawnOwnerResult;
     tokenFingerprint: string;
     chatId: string;
-    /** Require the current daemon PID after the launcher-to-daemon PID rebind. */
     pid: number;
     fs?: TelegramDaemonFs;
     now?: () => number;
+    pidAlive?: (pid: number) => boolean;
+    pidIncarnation?: (pid: number) => string | undefined;
+    sleep?: (ms: number) => Promise<void>;
+    waitStepMs?: number;
+    timeoutMs?: number;
+}): Promise<boolean>;
+export declare function releaseDaemonOwnership(input: {
+    settings: Settings;
+    ownerId: string;
+    acquisitionId?: string;
+    tokenFingerprint?: string;
+    chatId?: string;
+    pid?: number;
+    generation?: number;
+    pidIncarnation?: (pid: number) => string | undefined;
+    fs?: TelegramDaemonFs;
+    now?: () => number;
 }): Promise<void>;
 /** Read the persisted daemon ownership state (or undefined when absent). */
 export declare function readDaemonState(settings: Pick<Settings, "getAgentDir">, fs?: TelegramDaemonFs): Promise<DaemonState | undefined>;
@@ -182,18 +344,30 @@ export interface TelegramSpawnOwnerInput {
     tokenFingerprint: string;
     chatId: string;
 }
-export interface TelegramSpawnOwnerResult {
-    result: EnsureDaemonResult;
-    ownerId?: string;
+export interface TelegramSpawnAcquisition {
+    readonly ownerId: string;
+    readonly acquisitionId: string;
+    /** PID of the launcher which reserved provisional ownership before spawn. */
+    readonly launcherPid?: number;
+    /** Actual detached child which must publish the ready owner state. */
+    readonly pid?: number;
+}
+export type TelegramSpawnOwnerResult = {
+    result: "owner_spawned";
+    acquisition: TelegramSpawnAcquisition;
+    runtime: DaemonRuntimeInfo;
+    warnings: string[];
+} | {
+    result: "attached";
     runtime: DaemonRuntimeInfo;
     warnings: string[];
-    /**
-     * Set when ownership was NOT acquired because a still-live owner is running an
-     * older daemon generation. The caller must hand off via a reload rather than
-     * attach; see {@link ensureTelegramDaemonRunning}.
-     */
     reloadRequired?: boolean;
-}
+} | {
+    result: "blocked";
+    runtime: DaemonRuntimeInfo;
+    warnings: string[];
+    reloadRequired?: boolean;
+};
 /**
  * Build the detached spawn command/args for the daemon-internal entrypoint.
  * Source mode prepends the entry script so the respawn loads edited source;
@@ -331,6 +505,7 @@ export interface TelegramDaemonOptions {
     pid?: number;
     /** Liveness probe for skipping dead-PID endpoint records in {@link TelegramNotificationDaemon.scanRoots}. */
     pidAlive?: (pid: number) => boolean;
+    pidIncarnation?: (pid: number) => string | undefined;
     botApi?: BotApi;
     control?: DaemonControlHooks;
     /**
@@ -358,6 +533,10 @@ export interface TelegramDaemonOptions {
     richDraft?: {
         enabled: boolean;
     };
+    /** Tool start/completion messages (enabled by default). */
+    toolActivity?: {
+        enabled: boolean;
+    };
     /**
      * Per-session Telegram forum-topic naming. `nameTemplate` supports the
      * `{repo}`, `{branch}`, and `{title}` placeholders; unset preserves the
@@ -403,6 +582,16 @@ export declare class TelegramNotificationDaemon {
     readonly messageRoutes: Map<string | number, CallbackRoute | Omit<CallbackRoute, "answer">>;
     /** Telegram message id backing each streamed `${sessionId}:${coalesceKey}`, for in-place edits. */
     private readonly liveMessages;
+    /** Endpoint-bound ownership for visible or dispatching tool bubbles. */
+    private readonly toolActivityOwners;
+    private readonly revokedToolEndpoints;
+    private readonly unresolvedToolTerminalizations;
+    private toolTerminalizationChain;
+    private toolActivityPolicyEpoch;
+    private toolActivityStopping;
+    private readonly replayToolActivityEpochs;
+    private toolShutdownBarrier;
+    private toolActivityAmbiguous;
     readonly sessions: Map<string, SessionSocket>;
     private readonly runtime;
     private readonly sessionRouter;
@@ -525,6 +714,9 @@ export declare class TelegramNotificationDaemon {
      * (so a delayed old close cannot delete a replacement), and best-effort closes
      * the socket. `scanRoots()` then reconnects the session.
      */
+    private enqueueToolTerminalization;
+    private scheduleVisibleToolTerminalization;
+    private beginToolActivityShutdown;
     private dropSession;
     private deleteMessageRoutes;
     private static readonly THREADED_FRAMES;
@@ -543,6 +735,8 @@ export declare class TelegramNotificationDaemon {
     private topicIdentityBase;
     private topicOwnerForIdentity;
     private sessionCanClaimIdentity;
+    private toolActivityOwner;
+    private toolActivityAuthorityIsCurrent;
     private submitThreadedFrame;
     private existingTopicForPrivateChat;
     private topicAuthorityLease;

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

@@ -1,4 +1,4 @@
-import { type AgentTelemetryConfig, ThinkingLevel } from "@gajae-code/agent-core";
+import { type AgentMessage, type AgentTelemetryConfig, ThinkingLevel } from "@gajae-code/agent-core";
 import { type AuthCredentialSelector, type Model, type ProviderSessionState } from "@gajae-code/ai";
 import { createAppendOnlyContextManager, providerSupportsAppendOnlyAuto, resolveAppendOnlyMode } from "../append-only-mode";
 import { type Rule } from "../capability/rule";
@@ -25,6 +25,19 @@ import { type BuildSystemPromptResult } from "../system-prompt";
 import { BashTool, BUILTIN_TOOLS, createTools, EditTool, EvalTool, FindTool, HIDDEN_TOOLS, type LspStartupServerInfo, loadSshTool, ReadTool, ResolveTool, SearchTool, type Tool, type ToolSession, WebSearchTool, WriteTool } from "../tools";
 import { EventBus } from "../utils/event-bus";
 import { type WorkspaceTree } from "../workspace-tree";
+/**
+ * Reconcile a resumed transcript that ends on an unpaired tool call.
+ *
+ * When a subagent finishes by calling `yield` (or any turn is torn down right
+ * after a tool executes), the terminating abort can land before the tool
+ * result is persisted, leaving the saved session ending on an assistant
+ * `toolCall` with no matching `toolResult`. Replaying that history verbatim on
+ * resume produces an invalid provider request (a tool_use not followed by a
+ * tool_result) and the resumed turn fails immediately. Synthesize a placeholder
+ * result for any such trailing unpaired tool call so a resumed session always
+ * starts from a valid, paired history. No-op for well-formed transcripts.
+ */
+export declare function reconcileTrailingToolCalls(messages: AgentMessage[]): AgentMessage[];
 export interface CreateAgentSessionOptions {
     /** Working directory for project-local discovery. Default: getProjectDir() */
     cwd?: string;
@@ -152,6 +165,8 @@ export interface CreateAgentSessionOptions {
     notificationHostModeSupported?: boolean;
     /** Whether this host mode can own the root SDK endpoint. Default: true. */
     sdkHostModeSupported?: boolean;
+    /** Override configured Discord/Slack daemon readiness, primarily for embedded hosts and deterministic tests. */
+    ensureNotificationProviderDaemon?: (provider: "discord" | "slack", settings: Settings) => Promise<unknown>;
     /**
      * Opt-in OpenTelemetry instrumentation forwarded to the underlying Agent.
      * Passing `{}` enables the loop's GenAI-semantic-convention spans. See